Zzo theme for Hugo

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

Features

Multiple Skins(dark, light, solarized, hacker)
A mobile menu
CSS grid and flex for layout
HTML5
Hugo Pipes for js and sass
jQuery
Simple blog
Minify css
Meta tags and JSON-LD
Multilingual (i18n)
Responsive design
RSS and JSON feeds with full content
Search with Lunr
Gallery with Masonry, Photoswipe
Prism.js for highlight code
Lazy image load with lazysizes

Reference

I have referenced:

engimo
even theme
zen theme
docdock theme
learn theme
academic theme
overreacted.io

Minimum Hugo version

Hugo version 0.58.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

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

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

config.toml

baseURL = "http://example.org/"
title = "Hugo Zzo Theme"
theme = "zzo"

defaultContentLanguage = "en"
defaultContentLanguageInSubdir = true
hasCJKLanguage = true

summaryLength = 70

copyright = "&copy;{year}, All Rights Reserved"
timeout = 10000
enableEmoji = true
paginate = 13
rssLimit = 100

pygmentsOptions = "linenos=table"
pygmentsCodefences = true
pygmentsUseClasses = true
pygmentsCodefencesGuessSyntax = true

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

[mediaTypes."application/manifest+json"]
  suffixes = ["webmanifest"]

[outputFormats.WebAppManifest]
  mediaType = "application/manifest+json"
  rel = "manifest"

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

languages.toml

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

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

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
...

params.toml

logoText = "Zzo"
description = "The Zzo theme for Hugo example site."
custom_css = []
custom_js = []

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

# body
enableBreadcrumb = true
enablePhotoSwipe = true
enableSearch = true
enableMark = true
enableGoToTop = true
enableWhoami = true
summaryShape = "classic" # card, classic, compact
archiveGroupByDate = "2006" # "2006-01": group by month, "2006": group by year
archivePaginate = 13
paginateWindow = 1

# whoami
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
enableSidebar = true
enableSidebarTags = true
enableSidebarSeries = true
enableSidebarCategories = true
enableToc = true
enableTocSwitch = true
itemsPerCategory = 5
enableSideSubscribe = false
searchLanguages = ['en']

# footer
showPoweredBy = true
showFeedLinks = true
showSocialLinks = true
enableLangChange = true
enableThemeChange = true
themeOptions = ["dark", "light", "hacker", "solarized", "custom"]

# 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'"

[marketing]
  google_analytics = ""
  google_tag_manager = ""

[socialOptions]
  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 = ""

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 frontmatter.

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 works
  - image: image1.jpg
    caption: caption1
  - image: image2.jpg
    caption: caption2
    ...
---

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

Make a gallery folder under the content folder

root
├── content
│   ├── gallery

Make a sub folder under the gallery folder

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

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

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

Put your images in static folder

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

Multi Language

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

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
...

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
...

Make an i18n file.

i18n/ko.toml

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

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

[taxo-tags]
other = "태그"

...

Customizing

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

custom css

Add this line of code to your params.toml file

config/_default/params.toml

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

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

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

If you want to modify zzo theme's default color, you should override the theme style. For example, if you want to change the body background-color, because I set the background-color in #body selector, not in body tag selector, you should override body background-color there. body tag selector won't work. And make sure to set !important.

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

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

custom js

Add this line of code to your params.toml file

config/_default/params.toml

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

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

assets/js/custom.js

custom skin(sub theme)

Make a skin.toml file in data folder. (data/skin.toml)
Copy the contents of themes/zzo/data/skin.toml file and paste it into the skin.toml file you created above.
Change the color you want.
Edit config/_default/params.toml file. The option name must be custom.

...
themeOptions = ["custom", "dark", ...]
...

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

custom font

Make a font.toml file in data folder. (data/font.toml)
Copy the contents of themes/zzo/data/font.toml file and paste it into the font.toml file you created above.
Change the font you want. Make sure that you have imported that font.
Once you change the font.toml file, restart hugo.

data/font.toml example

search_placeholder = "'Montserrat', sans-serif"
summary_title = "'Montserrat', sans-serif"
summary_subtitle = "'Merriweather', serif"
summary_text = "'Merriweather', serif"
taxo_titie = "'Montserrat', sans-serif"
footer_content = "'Montserrat', sans-serif"
header_title = "'Montserrat', sans-serif"
navbar_item = "'Montserrat', sans-serif"
sidebar_title = "'Montserrat', sans-serif"
sidebar_list = "inherit"
page_not_found = "'Montserrat', sans-serif"
gallery_contents = "'Merriweather', serif"
list_title = "'Montserrat', sans-serif"
list_desc = "'Merriweather', serif"
single_title = "'Montserrat', sans-serif"
single_contents = "'Merriweather', serif"

custom header

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

Set param at config/_default/params.toml(homeHeaderType)
Make _index.md file at root/content/_index.md and copy & paste below.

---
header:
  - type: text
    height: 235
    paddingX: 50
    paddingY: 0
    align: left
    title:
      - header title1
      - header title2
    subtitle:
      - header subtitle1
      - header subtitle2
    titleFontSize: 44
    subtitleFontSize: 16
    spaceBetweenTitleSubtitle: 20
  
  - type: img
    image: images/header/background.png
    height: 235
    paddingX: 50
    paddingY: 0
    align: center
    title:
      - header title1
      - header title2
    subtitle:
      - header subtitle1
      - header subtitle2
    titleFontSize: 44
    subtitleFontSize: 16
    spaceBetweenTitleSubtitle: 20

  - type: slide
    height: 235
    slide:
      - paddingX: 50
        paddingY: 0
        align: left
        image: images/header/background.png
        title:
          - header title1
        subtitle:
          - header subtitle1
        titleFontSize: 44
        subtitleFontSize: 16
        spaceBetweenTitleSubtitle: 20

      - paddingX: 50
        paddingY: 0
        align: center
        image: images/header/background.png
        title:
          - header title2
        subtitle:
          - header subtitle2
        titleFontSize: 44
        subtitleFontSize: 16
        spaceBetweenTitleSubtitle: 20

      - paddingX: 50
        paddingY: 0
        align: right
        image: images/header/background.png
        title:
          - header title3
        subtitle:
          - header subtitle3
        titleFontSize: 44
        subtitleFontSize: 16
        spaceBetweenTitleSubtitle: 20
---

Edit params as you wish.

custom grid

Make a grid.toml file in data folder. (data/grid.toml)
Copy the contents of themes/zzo/data/grid.toml file and paste it into the grid.toml file you created above.
Change the grid you want.
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"

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 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

{{% img src="https://example.com" title="Image4" caption="Image description" alt="image alt" %}}

notice

{{% notice note %}}
A notice disclaimer
{{% /notice %}}

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Zzo theme for Hugo

Table of contents

Features

Reference

Minimum Hugo version

Installation

Updating

Run example site

Configuration

Layout

CSS grid for layout

grid structure

grid structure example applied in home page

Gallery

Multi Language

Customizing

custom css

custom js

custom skin(sub theme)

custom font

custom header

custom grid

External Library

Shortcodes

warning

expand

img

notice

Files

README.md

Latest commit

History

README.md

File metadata and controls

Zzo theme for Hugo

Table of contents

Features

Reference

Minimum Hugo version

Installation

Updating

Run example site

Configuration

Layout

CSS grid for layout

grid structure

grid structure example applied in home page

Gallery

Multi Language

Customizing

custom css

custom js

custom skin(sub theme)

custom font

custom header

custom grid

External Library

Shortcodes

warning

expand

img

notice