Getting Started#

Prerequisites#

Hugo extended edition (required for SCSS processing)
Git (for theme installation using git submodules)
Go (for theme installation using Hugo Modules)

Quick Start#

Use the starter repository to get a working site in seconds. It can also be used as a GitHub template to create a new repository.

git clone https://github.com/alex-shpak/hugo-book-starter documentation
cd documentation
git submodule update --init --remote
hugo server --minify

By default, the theme renders pages under docs/ section as the sidebar menu. See Content Organization for details.

Installation Methods#

Git Submodule

The simplest approach. The theme is vendored directly into your repository.

git init
git submodule add https://github.com/alex-shpak/hugo-book themes/hugo-book

Set the theme in your config

hugo.toml

theme = 'hugo-book'

To update the theme later

git submodule update --remote --merge

Hugo Module

Uses Hugo Modules (requires Go).

Initialize your site as a module

hugo mod init github.com/user/my-docs

Add the theme import to your config

hugo.toml

[module]
[[module.imports]]
  path = 'github.com/alex-shpak/hugo-book'

To update the theme later

hugo mod get -u

Manual Download

Download the theme from GitHub releases and extract it to themes/hugo-book.

Set the theme in your config

hugo.toml

theme = 'hugo-book'

To update, download and extract the new release again.

Minimal Configuration#

hugo.toml

baseURL = 'https://example.com/'
title = 'My Documentation'
theme = 'hugo-book'

# Required for mermaid and katex shortcodes
[markup.goldmark.renderer]
  unsafe = true

See Configuration for the full list of parameters.