hugo-theme-zzo/README.md

# Zzo theme for Hugo

**Zzo** theme made for bloggers.

It uses HTML5 with a modern CSS grid and flex layout. Recent versions of all the mayor browsers support it, see [Can I use css grid](http://caniuse.com/#search=grid).

## Table of contents

* [Features](#features)
* [Reference](#reference)
* [Dependency](#dependency)
* [Minimum Hugo version](#minimum-hugo-version)
* [Installation](#installation)
* [Updating](#updating)
* [Run example site](#run-example-site)
* [Configuration](#configuration)
* [Layout](#layout)
* [Gallery](#gallery)
* [Multi Language](#multi-language)
* [Customizing](#customizing)
* [Shortcodes](#shortcodes)


## Features

* Multiple sub themes(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:

* [zen theme](https://github.com/frjo/hugo-theme-zen)
* [docdock theme](https://github.com/vjeantet/hugo-theme-docdock)
* [learn theme](https://github.com/matcornic/hugo-theme-learn/)
* [academic theme](https://sourcethemes.com/academic/)
* [overreacted.io](https://github.com/gaearon/overreacted.io)

## Dependency

Zzo theme is using this library.

* jquery@3.4.1
* mark.js
* clipboard.js
* fetch-inject
* lazysizes
* masonry
* lunr
* jquery.toc
* photoswipe
* prism
* shave.js
* perfect-scrollbar

## 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](#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:

```bash
$ 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:

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

## Updating

From the root of your site:

```bash
git submodule update --remote --merge
```

## Run example site

From the root of themes/zzo/exampleSite:

```bash
hugo server --themesDir ../..
```

## Configuration

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

1. config folder structure

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

2. config.toml

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

defaultContentLanguage = "en"
defaultContentLanguageInSubdir = true
hasCJKLanguage = true

summaryLength = 70

googleAnalytics = ""
copyright = "©yourcopyright"
timeout = 10000
enableEmoji = true
paginate = 7
rssLimit = 100

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

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

```

3. languages.toml

```bash
[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.

```bash
[[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

```bash
description = "The Zzo theme for Hugo example site."
custom_css = ["css/custom.css", "css/custom.css"]
custom_js = ["js/custom.js"]
custom_skin = "custom"

# body
enableToc = true
enableBreadcrumb = true
enableCustomScrollbar = true
enablePhotoSwipe = true
enableSearch = true
enableMark = true

# sidebar
enableSidebarTags = true
enableSidebarSeries = true
enableSidebarCategories = true

# footer
showPoweredBy = true
showFeedLinks = true
showSocialLinks = true
enableLangChange = true
enableThemeChange = true
themeOptions = ["dark", "light", "hacker", "solarized"]
[socialOptions]
  facebook = "http://example.org/"
  twitter = "http://example.org/"
  github = "http://example.org/"
  stack-overflow = ""
  instagram = ""
  google-plus = ""
  youtube = ""
  medium = ""
  tumblr = ""
  linkedin = ""
  pinterest = "http://example.org/"
  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

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

Follow the steps below if you want to make gallery

1. Make a gallery folder under the content folder

```bash
root
├── content
│   ├── gallery
```

2. Make a sub folder under the gallery folder

```bash
root
├── content
│   ├── gallery
│   │   ├── mygallery
```

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

```bash
hugo new gallery/mygallery/index.md
```

4. Put your images in static folder

```bash
root
├── static
│   ├── gallery
│   │   ├── mygallery
│   │   │   ├── ...your images here
```

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

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

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

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

3. Make an i18n file.

```bash
i18n/ko.toml

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

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

[taxo-tags]
other = "태그"

...
```

## Customizing

### custom css

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

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

```bash
assets/scss/custom.scss
assets/css/custom.css
```

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

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

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

```bash
assets/js/custom.js
```

### custom skin(sub theme)

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

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

3. Change the color you want.

4. Edit config/_default/params.toml file. The option name must be custom.

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

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

### custom font

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

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

3. Change the font you want. Make sure that you have imported that font.

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

## Shortcodes

### warning

```bash
{{% 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

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

### img

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

### notice

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