Zzo theme for Hugo

English | 한국어

🎄🎄🎄🎅The minimum Hugo version changed to 0.60.0. This version changed the markdown rendering library, so if you are using an older version, it may not be compatible.🎄🎄🎄

Thank you for click me!. Zzo theme is a blog theme powered by Hugo with free(always), and many features.

Table of contents

• Features
• Minimum Hugo version
• Installation
• Updating
• Run example site
• Configuration
• Layout
• Gallery
• Contact Page
• Multi Language
• Customizing
• External libraries
• Shortcodes

Features

• Multiple Skins(dark, light, solarized, hacker)
• A mobile menu
• CSS grid and flex for layout
• HTML5
• Hugo Pipes for js and sass
• Simple blog
• Search Engine Optimization(SEO)
• Multilingual (i18n)
• Responsive design
• RSS and JSON feeds with full content
• Search with Fuse
• Gallery with Masonry, Photoswipe
• Fast code highlighting

Minimum Hugo version

Hugo version 0.60.0 or higher is required.

Installation

First of all, You need to add config files. Follow the Configuration step.

Then, You can download and unpack the theme manually from Github but it's easier to use git to clone the repo.

From the root of your site:

$ git clone https://github.com/zzossig/hugo-theme-zzo.git themes/zzo

If you use git to version control your site, highly recommended, it's best to add the zzo theme as a submodule.

From the root of your site:

git submodule add https://github.com/zzossig/hugo-theme-zzo.git themes/zzo

Updating

From the root of your site:

git submodule update --remote --merge

Run example site

From the root of themes/zzo/exampleSite:

hugo server --themesDir ../..

Configuration

0. From the root of your site: delete config.toml file and add the files below

1. config folder structure

root
├── config
│   ├── _default
│   │   ├── config.toml
│   │   ├── languages.toml
│   │   ├── menus.en.toml
│   │   ├── params.toml

2. config.toml

baseURL = "http://example.org/" # The URL of your site.
title = "Hugo Zzo Theme" # Title of your site
theme = "zzo" # Name of Zzo theme folder in `themes/`.

defaultContentLanguage = "en" # Default language to use (if you setup multilingual)
defaultContentLanguageInSubdir = true # baseURL/en/, baseURL/kr/ ...
hasCJKLanguage = true # Set `true` for Chinese/Japanese/Korean languages.

summaryLength = 70 # The length of a post description on a list page.

copyright = "©{year}, All Rights Reserved" # copyright symbol: $copy; current year: {year}
timeout = 10000
enableEmoji = true
paginate = 13 # Number of items per page in paginated lists.
rssLimit = 100

enableGitInfo = false # When true, the modified date will appear on a summary and single page. Since GitHub info needs to be fetched, this feature will slow down to build depending on a page number you have
googleAnalytics = ""

[markup]
  [markup.goldmark]
    [markup.goldmark.renderer]
      hardWraps = true
      unsafe = true
      xHTML = true
  [markup.highlight]
    codeFences = true
    lineNos = true
    lineNumbersInTable = true
    noClasses = false

[outputs]
  home = ["HTML", "RSS", "JSON"]

[taxonomies]
  category = "categories"
  tag = "tags"
  series = "series"

3. languages.toml

[en]
  title = "Hugo Zzo Theme"
  languageName = "English"
  weight = 1

[ko]
  title = "Hugo Zzo Theme"
  languageName = "한국어"
  weight = 2

4. menus.en.toml

You shoud make your own menu.

[[main]]
  identifier = "about"
  name = "about"
  url = "about"
  weight = 1

[[main]]
  identifier = "archive"
  name = "archive"
  url = "archive"
  weight = 2

[[main]]
  identifier = "gallery"
  name = "gallery"
  url = "gallery"
  weight = 3
    
[[main]]
  parent = "gallery"
  name = "cartoon"
  url = "gallery/cartoon"

[[main]]
  parent = "gallery"
  name = "photo"
  url = "gallery/photo"

[[main]]
  identifier = "posts"
  name = "posts"
  url = "posts"
  weight = 4
    
[[main]]
  identifier = "notes"
  name = "notes"
  url = "notes"
  weight = 5
...

5. params.toml

logoText = "Zzo" # Logo text that appears in the site navigation bar.
description = "The Zzo theme for Hugo example site." # for SEO
custom_css = [] # custom_css = ["scss/custom.scss"] and then make file at root/assets/scss/custom.scss
custom_js = [] # custom_js = ["js/custom.js"] and then make file at root/assets/js/custom.js

# header
homeHeaderType = "text" # text, img, slide

# navbar
enableThemeChange = true # site color theme

# body
enableBreadcrumb = true # breadcrumb for list, single page
enablePhotoSwipe = true # image viewer for gallery, single page
enableSearch = true # site search with Fuse
enableGoToTop = true # scroll to top
enableWhoami = true # at the end of single page
summaryShape = "classic" # card, classic, compact
archiveGroupByDate = "2006" # "2006-01": group by month, "2006": group by year
archivePaginate = 13 # items per page
paginateWindow = 1 # setting it to 1 gives 7 buttons, 2 gives 9, etc. If set 1: [1 ... 4 5 6 ... 356] [1 2 3 4 5 ... 356] etc

# whoami: usage - home page sidebar, single page bottom of post. all values can be empty
myname = "zzossig"
email = "zzossig@gmail.com"
whoami = "Web Developer"
useGravatar = false
location = "Seoul, Korea"
organization = "Hugo"
link = "https://github.com/zzossig/hugo-theme-zzo"

# sidebar
enableBio = true # home page sidebar
enableSidebar = true # Set to false to create the full width of the content.
enableSidebarTags = true # if you want to use tags.
enableSidebarSeries = true
enableSidebarCategories = true
enableToc = true # single page table of contents
enableTocSwitch = true # single page table of contents visibility switch
itemsPerCategory = 5 # maximum number of posts shown in the sidebar.

# footer
showPoweredBy = true # show footer text: Powered by Hugo and Zzo theme
showFeedLinks = true # RSS Feed 
showSocialLinks = true # email, facebook, twitter ...
enableLangChange = true # show button at bottom left of footer.
themeOptions = ["dark", "light", "hacker", "solarized", "custom"] # select options for site color theme

# service
baiduAnalytics = "" # alternative of google analytics
enableBusuanzi = false # if set true, total page view, total unique visitors show up in the footer.
busuanziSiteUV = true # unique visitors (total number of visitors)
busuanziSitePV = true # site total page view count
busuanziPagePV = true # post view count

# comment
enableComment = true
disqus_shortname = "" 
commento = false

[gitment]          # Gitment is a comment system based on GitHub issues. see https://github.com/imsun/gitment
  owner = ""              # Your GitHub ID
  repo = ""               # The repo to store comments
  clientId = ""           # Your client ID
  clientSecret = ""       # Your client secret

[utterances]       # https://utteranc.es/
  owner = ""              # Your GitHub ID
  repo = ""               # The repo to store comments

[gitalk]           # Gitalk is a comment system based on GitHub issues. see https://github.com/gitalk/gitalk
  owner = ""              # Your GitHub ID
  repo = ""               # The repo to store comments
  clientId = ""           # Your client ID
  clientSecret = ""       # Your client secret

# Valine.
# You can get your appid and appkey from https://leancloud.cn
# more info please open https://valine.js.org
[valine]
  enable = false
  appId = '你的appId'
  appKey = '你的appKey'
  notify = false  # mail notifier , https://github.com/xCss/Valine/wiki
  verify = false # Verification code
  avatar = 'mm' 
  placeholder = '说点什么吧...'
  visitor = false

[changyan]
  changyanAppid = ""        # Changyan app id             # 畅言
  changyanAppkey = ""       # Changyan app key

[livere]
  livereUID = ""            # LiveRe UID                  # 来必力

# Isso: https://posativ.org/isso/
[isso]
  enable = false
  scriptSrc = "" # "https://isso.example.com/js/embed.min.js"
  dataAttrs = "" # "data-isso='https://isso.example.com' data-isso-require-author='true'"

[socialOptions] # if set, social icons will show up.
  email = "mailto:your@email.com"
  facebook = "http://example.org/"
  twitter = "http://example.org/"
  github = "https://github.com/zzossig/hugo-theme-zzo"
  stack-overflow = ""
  instagram = ""
  google-plus = ""
  youtube = ""
  medium = ""
  tumblr = ""
  linkedin = ""
  pinterest = ""
  stack-exchange = ""
  telegram = ""
  steam = ""
  weibo = ""

[donationOptions] 
  enable = false # if set, the donation button will show up on the single page.
  alipay = "" # Alipay QR Code image (example path: images/donation/alipay-qrcode.png) and put your file at root/static/images/donation/
  wechat = "" # Wechat pay QR Code image (example path: same as above)
  paypal = "" # Paypal URL
  patreon = "" # Patreon URL

Layout

CSS grid for layout

Modern CSS grid is the easiest and cleanest way to layout your pages.

The CSS grid layout are in assets/sass/layout/_grid.scss. A lot can be done by just reordering "grid-template-rows".

grid structure

left	right
1	2
3	4
5	6
7	8

• left, right column width ratio => 5 : 2
• 1 => .navbar-main
• 2 => .navbar-side
• 1 + 2 => .navbar
• 3 => .header-main
• 4 => .header-side
• 3 + 4 => .header
• 5 => .main-main
• 6 => .main-side
• 5 + 6 => .main
• 7 => .footer-main
• 8 => .footer-side
• 7 + 8 => .footer

grid structure example applied in home page

<div class="navbar"></div>
<div class="header"></div>
<div>
  <div class="main-main"></div>
  <div class="main-side"></div>
</div>
<div class="footer></div>

Gallery

There are two ways to make gallery. You can specify mode at front-matter.

content/gallery/anygalleryname/index.md

---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
description: 
type: gallery
mode: one-by-one # at-once or one-by-one
tags:
-
series:
-
categories:
-
images: # when mode is one-by-one, images front-matter variable works
  - image: image1.jpg
    caption: caption1
  - image: image2.jpg
    caption: caption2
    ...
---

If you set the mode to one-by-one, the list.html page will use images front-matter variable you set above. If you set the mode to at-once, list.html page will not use front-matter images variable and just read all files under the static/gallery/anygalleryname folder.

1. Make a gallery folder under the content folder

root
├── content
│   ├── gallery

2. Make a sub folder under the gallery folder

root
├── content
│   ├── gallery
│   │   ├── anygalleryname

3. Make a index.md file under the sub folder using this command

hugo new --kind gallery gallery/anygalleryname/index.md

4. Put your images in static folder

root
├── static
│   ├── gallery
│   │   ├── anygalleryname
│   │   │   ├── ...your images here

Contact Page

Currently available service: [formspree]. Open an issue if you need another service vendor.

1. Make a file at root/contact/index.md

---
title: "Contact"
date: 2019-12-17T23:58:33+09:00
description: Contact page
type: contact
service: formspree
formId: "your@email.com"
---

This is contact page.

2. Add contact menu at root/config/_default/menus.en.toml.

...
[[main]]
  identifier = "contact"
  name = "contact"
  url = "contact"
  weight = 6

Multi Language

The default language of this theme is English. If you want to use another language, follow these steps

1. Make a menu file.

root
├── config
│   ├── _default
│   │   ├── ...
│   │   ├── menus.ko.toml

config/_default/menus.ko.toml

[[main]]
  identifier = "about"
  name = "about"
  url = "/about/"
  weight = 1

[[main]]
    identifier = "archive"
    name = "archive"
    url = "/archive/"
    weight = 2
...

2. Make a content file. Add your language code before the md extension.

hugo new about/index.ko.md
hugo new posts/markdown-syntax.ko.md
...

3. Make an i18n file.

i18n/ko.toml

[search-placeholder]
other = "검색..."

[summary-dateformat]
other = "2006년 01월 02일"

[taxo-tags]
other = "태그"

...

4. Edit config.toml file.

defaultContentLanguage = "ko"
defaultContentLanguageInSubdir = true
hasCJKLanguage = true

Customizing

It's a better idea not to modify the Zzo theme's folder if you want future support and upgrade. (You can modify if it doesn't matter) If you want more customizing options, open a new issue.

custom css

1. Add this line of code to your params.toml file

config/_default/params.toml

...
custom_css = ["css/custom.css", "scss/custom.scss", ...]
...

2. Add your file to assets folder. Filename must match with config params you set above.

assets/scss/custom.scss
assets/css/custom.css

3. If you want to modify the Zzo theme's default color, you should override the theme style. For example, if you're going to change the body background-color because I set the background-color in #body selector, not in the body tag selector, you should override body background-color there. Body tag selector won't work. And make sure to set !important. After setting the values, restart Hugo.

assets/scss/custom.scss or assets/css/custom.css

...
#body {
  background-color: red !important;
}
...

custom js

1. Add this line of code to your params.toml file

config/_default/params.toml

...
custom_js = ["js/custom.js", ...]
...

2. Add your file to assets folder. Filename must match with config params you set above.

assets/js/custom.js

custom skin(sub theme)

1. Make a skin.toml file in data folder. (data/skin.toml)

2. Set custom_theme_primary_color variable. The range of value that can be set is from "0" to "359".

3. Restart hugo.

4. Once you change the skin.toml file, restart hugo.

custom syntax highlighting

1. Make a skin.toml file at root/data folder. Set the chroma_theme value as you want. Refer this link. If chroma_theme value include - or _ like special character, just delete it. For example, if you want use solarized-dark256 style, set the param like this.

root/data/skin.toml

chroma_theme = "solarizeddark256"

2. Add a custom style file if you want to change specific colors. [custom-css] Then, override chroma class. You can find this class at themes/zzo/assets/sass/syntax folder. Example code is like this.

root/assets/scss/custom.scss

.chroma {
  background-color: #123456 !important;
}

Make sure that !important is necessary. After you changed this param, restart hugo.

custom header

You may want to change home page header. There are 4 options which is slider, image, text, empty.

1. Set param at config/_default/params.toml(homeHeaderType)

2. Make _index.md file at root/content/_index.md and copy & paste below.

---
header:
  - type: text
    height: 200
    paddingX: 50
    paddingY: 0
    align: center
    title:
      - HUGO
    subtitle:
      - The world’s fastest framework for building websites
    titleFontSize: 44
    subtitleFontSize: 16
    spaceBetweenTitleSubtitle: 20
  
  - type: img
    imageSrc: images/header/background.jpg # your image file path: root/static/images/header/background.jpg
    imageSize: cover # auto|length|cover|contain|initial|inherit
    imageRepeat: no-repeat # repeat|repeat-x|repeat-y|no-repeat|initial|inherit
    imagePosition: center # x% y%| xpos ypos| left top| center bottom| ...
    height: 235
    paddingX: 50
    paddingY: 0
    align: center
    title:
      -
    subtitle:
      -
    titleFontSize: 44
    subtitleFontSize: 16
    spaceBetweenTitleSubtitle: 20

  - type: slide
    height: 235
    slide:
      - paddingX: 50
        paddingY: 0
        align: left
        imageSrc: images/header/background.jpg
        imageSize: cover
        imageRepeat: no-repeat
        imagePosition: center
        title:
          - header title1
        subtitle:
          - header subtitle1
        titleFontSize: 44
        subtitleFontSize: 16
        spaceBetweenTitleSubtitle: 20

      - paddingX: 50
        paddingY: 0
        align: center
        imageSrc: images/header/background.jpg
        imageSize: cover
        imageRepeat: no-repeat
        imagePosition: center
        title:
          - header title2
        subtitle:
          - header subtitle2
        titleFontSize: 44
        subtitleFontSize: 16
        spaceBetweenTitleSubtitle: 20

      - paddingX: 50
        paddingY: 0
        align: right
        imageSrc: images/header/background.jpg
        imageSize: cover
        imageRepeat: no-repeat
        imagePosition: center
        title:
          - header title3
        subtitle:
          - header subtitle3
        titleFontSize: 44
        subtitleFontSize: 16
        spaceBetweenTitleSubtitle: 20
---

3. Edit params as you wish.

custom grid

1. Make a grid.toml file in data folder. (data/grid.toml)

2. Copy the contents of themes/zzo/data/grid.toml file and paste it into the grid.toml file you created above.

3. Change the grid as you want.

4. Once you change the grid.toml file, restart hugo.

data/grid.toml example

grid_max_width = "960"
grid_max_unit = "px" #  "px", "\"%\""  Using% is limited to using full width.
grid_main_main_width = "5"
grid_main_main_unit = "fr" # "fr", "px"
grid_main_side_width = "2"
grid_main_side_unit = "fr" # "fr", "px"
grid_column_gap_width = "32"
grid_column_gap_unit = "px" # "px"
grid_navbar_height = "50px" # "px"
grid_row_gap = "0"

custom font

1. Add custom css file

config/_default/params.toml

...
custom_css = ["css/font.css"]
...

Set the above param and add file to assets/css/font.css

2. In your font.css file, add font-face something like this.

@font-face {
    font-family: 'Montserrat';
    src: url('../fonts/montserrat-black.woff2') format('woff2'),
         url('../fonts/montserrat-black.woff') format('woff');
    font-weight: 900;
    font-style: normal;
}

@font-face {
    font-family: 'Merriweather';
    src: url('../fonts/merriweather-regular.woff2') format('woff2'),
         url('../fonts/merriweather-regular.woff') format('woff');
    font-weight: 400;
    font-style: normal;
}

3. Add your fonts file at root/static/fonts/myfont.xxx (If your url in step2 is ('../fonts/myfont.xxx')).

4. Make a font.toml file at root/data/font.toml and make variables as below.

title_font = "\"Montserrat\", sans-serif"
content_font = "\"Merriweather\", serif"

5. Another approach

Make a file at root/layouts/partials/head/custom-head.html and then load font style.

<link href="https://fonts.googleapis.com/css?family=Noto+Sans+KR:400,700&display=swap&subset=korean" rel="stylesheet">

External Library

If you want use external libraries, this theme currently supporting Katex, MathJax, Mermaid, Flowchart.js, chart.js, viz-graph, wavedrom, js-sequence-diagram. Just add some variable to a front-matter.

---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
...
libraries:
- katex 
- mathjax
- chart
- flowchartjs
- msc
- katex
- mermaid
- viz
- wavedrom
---

You can add some config option parameters at data/flowchartjs.json

Shortcodes

warning

{{% alert theme="info" %}}**this** is a text{{% /alert %}}
{{% alert theme="success" %}}**Yeahhh !** is a text{{% /alert %}}
{{% alert theme="warning" %}}**Be carefull** is a text{{% /alert %}}
{{% alert theme="danger" %}}**Beware !** is a text{{% /alert %}}

expand

{{%expand "Expand me" %}}Good job{{% /expand%}}

img

// path: static/images/whoami/avatar.jpg, you can set width, height also
{{< img src="/images/whoami/avatar.jpg" title="Image4" caption="Image description" alt="image alt" >}}

notice

{{% notice note %}} # note, info, tip, warning
A notice disclaimer
{{% /notice %}}

color

{{< color "#0000ff" >}}*text*{{< /color >}}