Configuration#

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

Theme Parameters#

hugo.toml 
[params]
  # Color theme: 'light', 'dark' or 'auto'
  # Auto switches based on OS/browser preference
  BookTheme = 'light'

  # Show table of contents on right side of pages
  # Can also be set per-page via frontmatter
  BookToC = true

  # Path to favicon file relative to 'static' directory
  BookFavicon = 'favicon.png'

  # Path to logo image file relative to 'static' directory
  BookLogo = 'logo.png'

  # Root section to render as sidebar menu
  # Default: 'docs'
  BookSection = 'docs'

  # Repository URL, used for edit and commit links
  BookRepo = 'https://github.com/user/repo'

  # Template for "Last Modified" commit link in page footer
  # Requires enableGitInfo = true in site config
  # Available context: .Site, .Page, .GitInfo
  BookLastChangeLink = '{{ .Site.Params.BookRepo }}/commit/{{ .GitInfo.Hash }}'

  # Template for "Edit this page" link in page footer
  # Available context: .Site, .Page, .Path
  BookEditLink = '{{ .Site.Params.BookRepo }}/edit/main/{{ .Path }}'

  # Date format used in git info and blog posts
  BookDateFormat = 'January 2, 2006'

  # Enable full-text search with fuse.js
  BookSearch = true

  # Enable comments template on pages
  # By default uses Disqus; override partials/docs/comments.html for others
  BookComments = true

  # Enable portable markdown links (resolve relative .md links)
  # Values: false, 'warning', 'error'
  BookPortableLinks = false

  # Enable service worker for offline caching
  # Values: false, true, 'precache'
  BookServiceWorker = false

  # Only show languages that have translations for current page
  BookTranslatedOnly = false

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

hugo.toml 
[params]
  BookSearch = true

To exclude a page from the search index, set bookSearchExclude: true in its frontmatter.

If search is not working, verify that baseURL in your config matches the URL where the site is hosted. A mismatch prevents the search index from loading.

Hugo Site Configuration#

These Hugo settings are relevant for the theme

hugo.toml 
# Preserve URL casing (recommended)
disablePathToLower = true

# Enable git metadata for "Last Modified" footer
enableGitInfo = true

Markup#

Goldmark Renderer#

The unsafe option is required for Mermaid and KaTeX shortcodes to render correctly

hugo.toml 
[markup.goldmark.renderer]
  unsafe = true

Table of Contents#

Control the heading levels included in the table of contents

hugo.toml 
[markup.tableOfContents]
  startLevel = 1
  endLevel = 4

The startLevel and endLevel values apply globally. Individual pages can toggle the ToC on or off with the bookToC frontmatter parameter.

Output Formats#

The theme supports plain text output alongside HTML, useful for accessibility and LLMs

hugo.toml 
[outputFormats.txt]
  mediaType = 'text/plain'
  baseName = 'source'
  isPlainText = true

[outputs]
  home = ['html', 'txt', 'rss']
  page = ['html', 'txt']
  section = ['html', 'txt']

Experimental feature. May change or be removed.

Portable links resolve relative markdown links ([text](./other-page.md) or [text](/docs/other-page.md)) to the correct Hugo URLs. This lets you write standard markdown that works in both text editors and the rendered site.

hugo.toml 
[params]
  BookPortableLinks = 'warning'
false
Disabled. Relative .md links are not resolved.
'warning'
Enabled. Hugo prints a warning during build if a linked page doesn’t exist.
'error'
Enabled. Hugo fails the build if a linked page doesn’t exist.

With portable links enabled, you can write

See [Configuration](./configuration.md) for details.

Instead of Hugo’s relref shortcode. Both image links and page links are resolved.

Service Worker#

Experimental feature. May change or be removed.

Hugo Book can register a service worker for offline access to visited pages.

hugo.toml 
[params]
  BookServiceWorker = 'precache'
false
Disabled (default).
true
Enables a service worker that caches pages as you visit them for offline reading.
'precache'
Enables a service worker that pre-populates the cache with all site pages on first load. Visited resources are also cached.