zdoc

Zdoc theme for Hugo

Thank you for click me!. Zdoc theme is a simple documentation theme powered by Hugo

Table of contents

• Features
• Minimum Hugo version
• Installation
• Updating
• Run example site
• Configuration
• How to make Doc
• Multi Language
• Favicon

Features

• Dark mode
• A mobile menu
• Simple documentation
• Search
• Search Engine Optimization(SEO)
• Multilingual (i18n)
• Responsive design

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-zdoc.git themes/zdoc

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

From the root of your site:

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

Updating

From the root of your site:

git submodule update --remote --merge

Run example site

From the root of themes/zdoc/exampleSite:

hugo server --themesDir ../..

Configuration

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

2. config folder structure. Keep in mind the underscore on the _default folder

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

3. config.toml

   baseURL = "http://example.org"
   title = "Hugo ZDoc Theme"
   theme = "zdoc"
   
   defaultContentLanguage = "en"
   defaultContentLanguageInSubdir = true
   hasCJKLanguage = true
   
   copyright = "©{year}, All Rights Reserved"
   timeout = 10000
   enableEmoji = true
   paginate = 13
   rssLimit = 100
   
   googleAnalytics = ""
   
   [markup]
   [markup.goldmark]
   [markup.goldmark.renderer]
     hardWraps = true
     unsafe = true
     xHTML = true
   [markup.highlight]
   codeFences = true
   lineNos = true
   lineNumbersInTable = true
   noClasses = false
   [markup.tableOfContents]
   endLevel = 4
   ordered = false
   startLevel = 2
   
   [outputs]
   home = ["HTML", "RSS", "JSON"]
   
   [taxonomies]
   tag = "tags"
   

4. languages.toml

   [en]
   title = "Hugo ZDoc Theme"
   languageName = "English"
   weight = 1
   
   [ko]
   title = "Hugo ZDoc Theme"
   languageName = "한국어"
   weight = 2
   

5. menus.en.toml

You shoud make your own menu.

[[main]]
  identifier = "docs"
  name = "Docs"
  url = "docs"
  weight = 1

[[main]]
  identifier = "updates"
  name = "Updates"
  url = "updates"
  weight = 2

[[main]]
  identifier = "blog"
  name = "Blog"
  url = "blog"
  weight = 3
...

1. params.toml

   logo = true # Logo that appears in the site navigation bar.
   logoText = "ZDoc" # Logo text that appears in the site navigation bar.
   logoType = "short" # long, short
   description = "The ZDoc theme for Hugo example site." # for SEO
   
   themeOptions = ["light", "dark"] # select options for site color theme
   
   useFaviconGenerator = true # https://www.favicon-generator.org/
   
   enableSearch = true
   enableLangChange = true
   enableDarkMode = true
   enableBreadcrumb = true
   enableToc = true
   enableMenu = true
   enableNavbar = true
   enableFooter = true
   showPoweredBy = true
   
   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
   taxoPaginate = 13 # items per page
   taxoGroupByDate = "2006" # "2006-01": group by month, "2006": group by year
   
   github = "https://github.com/zzossig/hugo-theme-zdoc"
   

How to make doc

1. Make a folder in the content folder. The folder will be appeared in the menu. I'm going to make doc folder.

2. Make a _index.md file in the doc folder.

   ---
   title: "Documentation"
   description: "test doc index"
   date: 2020-01-11T14:09:21+09:00
   ---
   
   The content here is appeared when you click the manu. So called overview page.
   

3. There are two types of pages. One is a single page and the other is collapsible page.

• single page - Just make a md file in the doc folder

  ---
  title: "Content Formats"
  description: "test post"
  date: 2020-01-28T00:38:51+09:00
  draft: false
  weight: 1
  ---
  
  *Markdown here*
  
  

• collapsible page - We need to make a new folder inside the doc folder. I'll make a folder named gettingstarted. And then, make a _index.md file.

  root/content/doc/gettingstarted/_index.md

  ---
  title: "Getting started"
  description: "test post index"
  date: 2020-01-28T00:36:39+09:00
  draft: false
  weight: 2
  collapsible: true
  ---
  
  

  The weight defines the order of the post. If the collapsible param set true, you can see the menu that can be collapsible.

• Make more pages in the collapsible section. Something like Getting Started, Installation, Basic usage, etc... For example, make a file at root/content/doc/gettingstarted/installation.md

  ---
  title: "Frontmatter"
  description: "test post"
  date: 2020-01-28T00:36:14+09:00
  draft: false
  ---
  
  *Markdown here*
  
  

1. Finally, make a menu in the file at root/config/_default/menus.en.toml.

You should make your own menu.

[[main]]
  identifier = "docs"
  name = "Docs"
  url = "docs"
  weight = 1

[[main]]
  identifier = "updates"
  name = "Updates"
  url = "updates"
  weight = 2

[[main]]
  identifier = "blog"
  name = "Blog"
  url = "blog"
  weight = 3

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일"
   
   [tags]
   other = "태그"
   
   ...
   

4. Edit config.toml file.

   defaultContentLanguage = "ko"
   defaultContentLanguageInSubdir = true
   hasCJKLanguage = true
   

Favicon

Put your favicon.ico file under the static folder. The filename should be favicon and the extension should be ico.

Using favicon-genarator

If you want to support mobile favicon, use favicon-generator.

• Make favicons from favicon-generator site.
• Make a folder at root/static/favicon
• Unzip the generated favicon to that folder.
• Set the config param useFaviconGenerator to true