VPS者

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

Hugo Book is a documentation theme for Hugo. It provides a clean, readable layout for technical docs with minimal dependencies and no build tooling beyond Hugo itself.

Design Goals

Minimalism over features.: The theme ships only what most documentation sites need: a sidebar menu, search, and a few shortcodes. There is no attempt to cover every use case. CSS is written by hand, not generated by a framework. JavaScript is optional for core navigation.
Theme as an extendable base.: Hugo Book is meant to be extended and adapted. ‘Inject’ partials, custom CSS, and Hugo’s template override system let you change any part of the theme without modifying the source, while keeping the codebase intentionally small.
Long-term maintainability.: Few dependencies means fewer things to break. The theme avoids heavy JavaScript libraries, CSS frameworks, and complex build pipelines.

Get Started

Organisation

Mon, 01 Jan 0001 00:00:00 +0000

Content Organisation

Hugo Book renders pages from a section as a sidebar menu. By default this is the docs/ directory.

Example Directory Structure

content/
├── docs/
│ ├── _index.md
│ ├── getting-started.md
│ ├── guide/
│ │ ├── _index.md
│ │ ├── install.md
│ │ └── configure.md
│ └── reference/
│ └── _index.md
├── posts/
│ ├── _index.md
│ └── my-post.md
└── _index.md

Pages are ordered by weight frontmatter, then alphabetically. Section _index.md files define the section entry in the menu.

Mon, 01 Jan 0001 00:00:00 +0000

Page Frontmatter

Every page can use these frontmatter parameters to control its behavior in the theme.

YAML


 _index.md

---
title: My Page
weight: 10
params:
 bookToC: true
 bookCollapseSection: true
---

TOML


 _index.md

+++
title = 'My Page'
weight = 10
bookToC = true
bookCollapseSection = true
+++

JSON


 _index.md

{
 "title": "My Page",
 "weight": 10,
 "bookToC": true,
 "bookCollapseSection": true
}

These parameters control how the page appears in the sidebar menu. Set in page frontmatter.

Mon, 01 Jan 0001 00:00:00 +0000

Create a Site

Prerequisites

Hugo
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 Organisation for details.

Styles

Mon, 01 Jan 0001 00:00:00 +0000

Styles

Built-in Themes

Theme comes with a set of predefined color schemes, Use BookTheme parameter in your site config:


 hugo.toml

[params]
 BookTheme = 'light' # or 'dark', 'auto'

Theme	Description
`light`	Default. Light background with dark text
`dark`	Dark background (Nord palette) with light text
`auto`	Switches between light and dark based on OS
`contrast-light`	High contrast light variant
`contrast-dark`	High contrast dark variant
`contrast-auto`	High contrast, auto-switching
`catppuccin-light`	Catppuccin Latte palette
`catppuccin-dark`	Catppuccin Frappe palette
`catppuccin-auto`	Catppuccin, auto-switching
`ayu-light`	Ayu light palette
`ayu-dark`	Ayu mirage dark palette
`ayu-auto`	Ayu, auto-switching

The list of themes, except light, dark, and auto is not written in stone and potentially would change in the future.

Mon, 01 Jan 0001 00:00:00 +0000

Hugo Book supports two types of menus: an automatic file-tree menu built from your content structure, and Hugo’s standard menu system for additional navigation.

The sidebar menu is automatically generated from pages in the BookSection directory (default: docs/). The hierarchy mirrors your directory structure.

Control how sections appear with page frontmatter.

Hugo Menus

The theme renders three Hugo menu locations:

Menu	Location
`menu.before`	Rendered above the file-tree menu.
`menu.after`	Rendered below the file-tree menu.
`menu.home`	Rendered on the landing page header (only on pages with `layout: landing`).

Configuration

Define menus in your site config

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Configuration

All theme parameters are set under [params] in your site config. Every parameter is optional.

Theme Parameters


 hugo.toml

[params]
# (Optional, default light) Sets color theme: light, dark or auto.
# Theme 'auto' switches between dark and light modes based on browser/os preferences
BookTheme = 'light'

# (Optional, default true) Controls table of contents visibility on right side of pages.
# Start and end levels can be controlled globally with markup.tableOfContents setting.
# You can also specify this parameter per page in front matter.
BookToC = true

# (Optional, default false) Controlls breadcurms, if true breadcrumbs are displayed at the beginning of the document.
# You can also specify this parameter per page in front matter.
BookBreadcrumbs = true

# (Optional, default false) Enableds incoming and outgoing links display next to table of contents on a page
# You can also specify this parameter per page in front matter.
BookPageLinks = true

# (Optional, default none) Set the path to a logo for the book.
# If the logo is /static/logo.png then the path would be logo.png
# BookLogo = 'favicon.svg'

# (Optional, default docs) Specify root page to render child pages as menu.
# Page is resoled by .GetPage function: https://gohugo.io/functions/getpage/
# For backward compatibility you can set '*' to render all sections to menu. Acts same as '/'
BookSection = 'docs'

# Here for backward compatibility, not required.
# It's here as an example how to use it with BookLastChangeLink or BookEditLink
BookRepo = 'https://github.com/alex-shpak/hugo-book/'

# (Optional, default none) Set template for commit link for the page. Requires enableGitInfo.
# When set enabled 'Last Modified' and a link to the commit in the footer of the page.
# Param is executed as template using .Site, .Page and .GitInfo as context.
BookLastChangeLink = '{{ .Site.Params.BookRepo }}/commit/{{ .GitInfo.Hash }}'

# (Optional, default none) Set template for edit page link.
# When set enabled 'Edit this page' link in the footer of the page.
# Param is executed as template using .Site, .Page and .Path as context.
# .Path is relative to the project, or to the module root for modules outside it.
BookEditLink = '{{ .Site.Params.BookRepo }}/edit/main/exampleSite/{{ .Path }}'

# (Optional, default 'January 2, 2006') Configure the date format used on the pages
# - In git information
# - In blog posts
# https://gohugo.io/functions/time/format/
BookDateFormat = 'January 2, 2006'

# (Optional, default true) Enables search function with MiniSearch.
# Index is built on fly, therefore it might slowdown your website.
# Configuration for indexing can be adjusted in i18n folder per language.
BookSearch = true

# (Optional, default false) Enables comments template on pages
# By default partials/docs/comments.html includes Disqus template
# See https://gohugo.io/content-management/comments/#configure-disqus
# Can be overwritten by same param in page frontmatter
BookComments = false

# /!\ This is an experimental feature, might be removed or changed at any time
# (Optional, experimental, default false) Enables portable links and link checks in markdown pages.
# Portable links meant to work with text editors and let you write markdown without relref shortcode
# Hugo Book will print warning or error if page referenced in markdown does not exists.
# Possible values are false | 'warning' | 'error'
BookPortableLinks = 'warning'

# /!\ This is an experimental feature, might be removed or changed at any time
# (Optional, experimental, default false)
# When set to 'preache' it enables a service worker that caches visited pages and resources for offline use.
# Possible values are false | true | 'precache'
BookServiceWorker = 'precache'

Search

Full-text search is enabled by default using MiniSearch. The search index is built at page load from a generated JSON file.

Inject Partials

Mon, 01 Jan 0001 00:00:00 +0000

Inject Partials

The theme provides empty partial templates at key points in the page layout. Override these to inject custom HTML without modifying the base templates.

Create matching files in your project’s layouts/_partials/docs/inject/ directory.

Partial	Location
`inject/head.html`	Inside `<head>`, e.g. meta tags, stylesheets, scripts
`inject/body.html`	Before `</body>`, e.g. analytics, chat widgets, scripts
`inject/menu-before.html`	Before the sidebar menu
`inject/menu-after.html`	After the sidebar menu
`inject/content-before.html`	Before the page content
`inject/content-after.html`	After the page content
`inject/toc-before.html`	Before the table of contents
`inject/toc-after.html`	After the table of contents
`inject/footer.html`	Inside the page footer

Example

To add a Google Analytics script, create layouts/_partials/docs/inject/head.html

Mon, 01 Jan 0001 00:00:00 +0000

Blog

Hugo Book includes templates for blog-style posts with dates, tags, and pagination. Blog functionality is very basic.

Setup

Create a posts/ section in your content directory

content/
└── posts/
 ├── _index.md
 └── my-first-post.md

Add the blog section to a menu so readers can find it

---
title: Blog
menu:
 after:
 weight: 5
---

Post Frontmatter

---
title: "My First Post"
date: 2025-01-15
tags: ["hugo", "documentation"]
categories: ["Guides"]
---

Thumbnails

Posts can display a thumbnail image. By default the theme looks for a file matching thumbnail.* in the post’s page bundle. Override the pattern per-post

Multi-Language

Mon, 01 Jan 0001 00:00:00 +0000

Multi-Language Support

Hugo Book supports Hugo’s multilingual mode with content translation by directory.

Configuration

Define languages in your site config


 hugo.toml

[languages]
[languages.en]
 label = 'English'
 contentDir = 'content.en'
 weight = 1

[languages.zh]
 label = 'Chinese'
 contentDir = 'content.zh'
 weight = 2

[languages.he]
 label = 'Hebrew'
 contentDir = 'content.he'
 direction = 'rtl'
 weight = 3

A language selector dropdown appears automatically when multiple languages are configured.

RTL Support

Set direction = 'rtl' on a language to enable right-to-left layout. The entire page layout, including the sidebar menu, mirrors automatically.

Example Blog Post

Wed, 15 Jan 2025 00:00:00 +0000

This is an example blog post demonstrating the Hugo Book blog layout.

What This Demonstrates

Blog posts in Hugo Book support standard Hugo content features:

Date display: configured via BookDateFormat
Tags and categories: displayed as metadata
Pagination: automatic when multiple posts exist
Prev/next navigation: links between posts in the section

Adding Your Own Posts

Create markdown files under content/posts/:

content/
└── posts/
 ├── _index.md
 ├── first-post.md
 └── second-post.md

Each post needs at minimum a title and date in frontmatter. See Blog for full documentation.

Mon, 01 Jan 0001 00:00:00 +0000

Asciinema

Embed terminal recordings with the Asciinema player.

Syntax

{{< asciinema
 cast="recording.cast"
 loop=true
 autoplay=true
 speed=2 >}}

The cast parameter accepts page resources, site resources, or remote URLs.

Example

Parameters

cast: Path to the .cast file. Can be a local resource or a remote URL.

All other parameters are passed directly to the Asciinema player. See the Asciinema player options for the full list.

Common options: autoplay, loop, speed, theme, cols, rows, idleTimeLimit, preload.

Mon, 01 Jan 0001 00:00:00 +0000

Buttons

Styled links that can point to local pages or external URLs. External links automatically open in a new tab.

Syntax

{{< button relref="/" [class="..."] >}}Get Home{{< /button >}}
{{< button href="https://github.com/alex-shpak/hugo-book" >}}Github{{< /button >}}

Example

Home Github

Parameters

href: URL for external links.
relref: Hugo page reference for internal links.
class: Additional CSS classes.

Mon, 01 Jan 0001 00:00:00 +0000

Columns

Organize content horizontally. Renders a markdown list as up to 3 side-by-side columns.

Syntax

{{% columns [ratio="1:1"] [class="..."] %}}
- ### Left
 Content...

- ### Right
 Content...
{{% /columns %}}

Example

File-Tree Menu

The sidebar menu is automatically generated from your content directory structure. Pages are ordered by weight frontmatter.
Hugo Menus

Additional menu entries can be added above or below the file-tree using Hugo’s standard menu system in your site config.
Landing Menu

Pages with layout: landing use a separate menu defined under menu.home for header navigation.

Mon, 01 Jan 0001 00:00:00 +0000

Details

Collapsible content using the HTML5 <details> element.

Syntax

Positional arguments:

{{% details "Title" [open] %}}
Markdown content
{{% /details %}}

Named parameters:

{{% details title="Title" open=true %}}
Markdown content
{{% /details %}}

Example

What Hugo version is required?

Hugo Book requires Hugo {x} or later.

How do I override the theme?

Create matching files in your project’s layouts/ or assets/ directory. Hugo’s lookup order will use your files over the theme’s.

Parameters

title (or first positional argument): The summary text shown when collapsed.
open (or second positional argument): Start expanded. Default: collapsed.

Mon, 01 Jan 0001 00:00:00 +0000

Images

Enhanced image display with click-to-expand behavior.

Syntax

{{< image src="photo.jpg" alt="Description" title="Caption" loading="lazy" >}}

Example

Parameters

src: Path to the image. Supports page resources, site resources, and URLs.
alt: Alternate text for accessibility.
title: Caption displayed below the image.
width: Set image width, height is calculated automatically
loading: Loading strategy: lazy, eager, or auto.
class: Additional CSS classes on the <img> element.

Mon, 01 Jan 0001 00:00:00 +0000

Hints

Callout blocks for notes, warnings, and other contextual messages. Also supports standard GitHub markdown alerts.

Syntax

{{% hint [info|success|warning|danger] %}}
Markdown content
{{% /hint %}}

Or using markdown alerts

> [!NOTE|TIP|IMPORTANT|WARNING|CAUTION]
> Markdown content

Example

Default hint
Without a specified type.

Info
Use for supplementary information that helps the reader.

Success
Use to highlight a recommended approach or positive outcome.

Warning
Use for important caveats or potential issues.

Danger
Use for critical warnings about breaking changes or data loss.

Mon, 01 Jan 0001 00:00:00 +0000

Mermaid

Render diagrams and charts with Mermaid. The library is loaded automatically on first use. By default diagrams follows the site theme colors.

Override Mermaid initialization by creating assets/mermaid.json in your project. A theme set there takes precedence over the CSS variable.

Syntax

Use fenced code blocks (recommended) or the shortcode

```mermaid
graph LR
 A --> B
```

{{< mermaid [class="..."] >}}
graph LR
 A --> B
{{< /mermaid >}}

Examples

flowchart TD
 A[Content Files] --> B[Hugo Build]
 B --> C[HTML Output]
 B --> D[Search Index]
 B --> E[RSS Feed]

sequenceDiagram
 Browser->>Hugo: Request page
 Hugo->>Theme: Apply template
 Theme->>Browser: Rendered HTML
 Browser->>Browser: Load shortcodes

pie title Theme Assets
 "SCSS" : 8
 "HTML Templates" : 30
 "JavaScript" : 3
 "i18n Files" : 35

gitGraph
 commit id: "init"
 commit id: "add theme"
 branch feature
 checkout feature
 commit id: "add docs"
 commit id: "add config"
 checkout main
 merge feature
 commit id: "deploy"

Explore more diagram types on the Mermaid documentation.

Mon, 01 Jan 0001 00:00:00 +0000

Section

Render child pages of the current section as a definition list with titles and descriptions.

Syntax

{{< section [summary] >}}

Parameters

summary: When present, includes the page summary below each title.

Mon, 01 Jan 0001 00:00:00 +0000

Steps

Render an ordered list as a series of numbered steps with visual connectors.

Syntax

{{% steps %}}
1. ## Step Title
 Step description...

2. ## Step Title
 Step description...
{{% /steps %}}

Example

Create your site

Run hugo new site my-docs to scaffold a new Hugo project.
Add the theme

Clone or add hugo-book as a submodule in your themes/ directory.
Write content

Add markdown files under content/docs/. Each file becomes a page in the sidebar menu.
Deploy

Run hugo to build the site. The output is in the public/ directory, ready for any static hosting.

Mon, 01 Jan 0001 00:00:00 +0000

Tabs

Organize content by context, for example installation instructions for each supported platform.

Syntax

{{< tabs >}}
{{% tab "First" %}} Markdown content {{% /tab %}}
{{% tab "Second" %}} Markdown content {{% /tab %}}
{{< /tabs >}}

Example

macOS

brew install hugo

Linux

sudo snap install hugo

Windows

choco install hugo

KaTeX

Mon, 01 Jan 0001 00:00:00 +0000

KaTeX

Render math typesetting with KaTeX.

Activation

KaTeX styles are included on the page by the first use of the shortcode or a katex code block. In order to use delimiters passthrough needs to be configured.

Block Rendering

Three equivalent ways to render display math:

Shortcode

{{< katex displayMode=true >}}
f(x) = \int_{-\infty}^\infty
\hat f(\xi)\,e^{2 \pi i \xi x}\,d\xi
{{< /katex >}}

Code block

```katex
f(x) = \int_{-\infty}^\infty
\hat f(\xi)\,e^{2 \pi i \xi x}\,d\xi
```

Dollar delimiters

$$
f(x) = \int_{-\infty}^\infty
\hat f(\xi)\,e^{2 \pi i \xi x}\,d\xi
$$

Result:

VPS者

Introduction

Design Goals

Organisation

Content Organisation

Example Directory Structure

Page Frontmatter

Navigation

Create a Site

Prerequisites

Quick Start

Styles

Styles

Built-in Themes

Menu System

File-Tree Menu

Hugo Menus

Configuration

Configuration

Configuration

Theme Parameters

Search

Inject Partials

Inject Partials

Example

Blog

Setup

Post Frontmatter

Thumbnails

Multi-Language

Multi-Language Support

Configuration

RTL Support

Example Blog Post

What This Demonstrates

Adding Your Own Posts

Asciinema

Syntax

Example

Parameters

Buttons

Syntax

Example

Parameters

Columns

Syntax

Example

File-Tree Menu

Hugo Menus

Landing Menu

Details

Syntax

Example

Parameters

Images

Syntax

Example

Parameters

Hints

Syntax

Example

Mermaid

Syntax

Examples

Section

Syntax

Parameters

Steps

Syntax

Example

Create your site

Add the theme

Write content

Deploy

Tabs

Syntax

Example

KaTeX

KaTeX

Activation