Hugo Book

- Introduction: https://book.alxs.dev/docs/getting-started/introduction/
- Create a Site: https://book.alxs.dev/docs/getting-started/create-a-site/
- Configuration: https://book.alxs.dev/docs/getting-started/configuration/
- Organisation: https://book.alxs.dev/docs/content/organisation/
- Pages: https://book.alxs.dev/docs/content/pages/
- Menus: https://book.alxs.dev/docs/content/menus/
- Blog: https://book.alxs.dev/docs/content/blog/
- Multi-Language: https://book.alxs.dev/docs/content/multilingual/
- Shortcodes: https://book.alxs.dev/docs/content/shortcodes/
- Asciinema: https://book.alxs.dev/docs/content/shortcodes/asciinema/
- Buttons: https://book.alxs.dev/docs/content/shortcodes/buttons/
- Columns: https://book.alxs.dev/docs/content/shortcodes/columns/
- Details: https://book.alxs.dev/docs/content/shortcodes/details/
- Images: https://book.alxs.dev/docs/content/shortcodes/experimental/images/
- OpenAPI: https://book.alxs.dev/docs/content/shortcodes/experimental/openapi/
- Hints: https://book.alxs.dev/docs/content/shortcodes/hints/
- Mermaid: https://book.alxs.dev/docs/content/shortcodes/mermaid/
- Steps: https://book.alxs.dev/docs/content/shortcodes/steps/
- Tabs: https://book.alxs.dev/docs/content/shortcodes/tabs/
- KaTeX: https://book.alxs.dev/docs/content/shortcodes/katex/
- Styles: https://book.alxs.dev/docs/customization/styles/
- Inject Partials: https://book.alxs.dev/docs/customization/inject-partials/

# Introduction

Hugo Book is a documentation theme for [Hugo](https://gohugo.io). 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 SCSS, 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](/docs/getting-started/create-a-site/)

## Links
- [Source code](https://github.com/alex-shpak/hugo-book)
- [Hugo documentation](https://gohugo.io/documentation/)


# Create a Site

## Prerequisites

- [Hugo](https://gohugo.io/installation/) **extended** edition (required for SCSS processing)
- [Git](https://git-scm.com/downloads) (for theme installation using git submodules)
- [Go](https://go.dev/dl/) (for theme installation using Hugo Modules)

## Quick Start

Use the [starter repository](https://github.com/alex-shpak/hugo-book-starter) to get a working site in seconds. It can also be used as a [GitHub template](https://github.com/alex-shpak/hugo-book-starter/generate) to create a new repository.

```shell
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](/docs/content/organisation/) for details.

## Installation Methods

{{< tabs >}}

{{% tab "Git Submodule" %}}
The simplest approach. The theme is vendored directly into your repository.

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

Set the theme in your config

```toml {filename=hugo.toml}
theme = 'hugo-book'
```

To update the theme later

```shell
git submodule update --remote --merge
```
{{% /tab %}}

{{% tab "Hugo Module" %}}
Uses [Hugo Modules](https://gohugo.io/hugo-modules/) (requires [Go](https://go.dev/dl/)).

Initialize your site as a module

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

Add the theme import to your config

```toml {filename=hugo.toml}
[module]
[[module.imports]]
  path = 'github.com/alex-shpak/hugo-book'
```

To update the theme later

```shell
hugo mod get -u
```
{{% /tab %}}

{{% tab "Manual Download" %}}
Download the theme from [GitHub releases](https://github.com/alex-shpak/hugo-book/releases) and extract it to `themes/hugo-book`.

Set the theme in your config

```toml {filename=hugo.toml}
theme = 'hugo-book'
```

To update, download and extract the new release again.
{{% /tab %}}

{{< /tabs >}}

## Minimal Configuration

```toml {filename=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](/docs/getting-started/configuration/) for the full list of parameters.


# Configuration

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

## Theme Parameters

```toml {filename=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

  # /!\ Experimental, may change or be removed.
  # Enable portable markdown links to resolve relative .md links to Hugo URLs.
  # Lets you write [text](./other.md) instead of Hugo's relref shortcode.
  #   false     - disabled, relative .md links not resolved
  #   'warning' - enabled, prints a build warning if linked page doesn't exist
  #   'error'   - enabled, fails the build if linked page doesn't exist
  BookPortableLinks = false

  # /!\ Experimental, may change or be removed.
  # Register a service worker for offline access to visited pages.
  #   false      - disabled (default)
  #   true       - caches pages as you visit them
  #   'precache' - pre-populates cache with all site pages on first load
  BookServiceWorker = false

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

## Search

Full-text search is enabled by default using [Fuse.js](https://www.fusejs.io/). The search index is built at page load from a generated JSON file.

```toml {filename=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

```toml {filename=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

```toml {filename=hugo.toml}
[markup.goldmark.renderer]
  unsafe = true
```

### Table of Contents

Control the heading levels included in the table of contents

```toml {filename=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

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

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



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

## Changing the Menu Section

By default, pages under `docs/` are rendered as the sidebar menu. Change this with the `BookSection` parameter in [Configuration](/docs/getting-started/configuration/). Set to `'/'` to render all top-level sections.

## Page Layouts

The theme provides several layouts:

| Layout    | Usage                | Description |
| --- | --- | --- |
| (default) | Documentation pages  | Sidebar menu + content + optional ToC |
| `landing` | `layout: landing`    | Full-width, no sidebar. Used for homepages. |
| `book`    | `layout: book`       | Single-page view with all subsections listed |
| `posts`   | Pages under `posts/` | Blog-style with date, tags, pagination |

Set the layout in frontmatter

```yaml {filename=_index.md}
---
layout: landing
---
```

See [Pages](/docs/content/pages/) for frontmatter reference and [Menus](/docs/content/menus/) for navigation controls.


# Page Frontmatter

Every page can use these [frontmatter](https://gohugo.io/content-management/front-matter/) parameters to control its behavior in the theme.

{{< tabs >}}
{{% tab "YAML" %}}
```yaml
---
title: My Page
weight: 10
bookToC: true
bookCollapseSection: true
---
```
{{% /tab %}}

{{% tab "TOML" %}}
```toml
+++
title = 'My Page'
weight = 10
bookToC = true
bookCollapseSection = true
+++
```
{{% /tab %}}

{{% tab "JSON" %}}
```json
{
  "title": "My Page",
  "weight": 10,
  "bookToC": true,
  "bookCollapseSection": true
}
```
{{% /tab %}}
{{< /tabs >}}

## Navigation

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

| Parameter | Default | Description |
| --- | --- | --- |
| `weight` | | Menu ordering. Lower values appear first. Without weight, pages are sorted alphabetically. |
| `bookHidden` | `false` | Hide the page from the sidebar menu. The page is still accessible by URL. |
| `bookCollapseSection` | `false` | Make a section collapsible in the sidebar. Subsections are hidden until clicked. |
| `bookFlatSection` | `false` | Display subsection pages at the same level instead of nesting them. |
| `bookHref` | | Override the menu link with an external URL. |
| `bookIcon` | | Display an icon next to the menu entry. |

## Content Display

These parameters control page content rendering. Set in page frontmatter.

| Parameter | Default | Description |
| --- | --- | --- |
| `bookToC` | | Show or hide the table of contents. Overrides the site-level `BookToC` setting. |
| `bookComments` | | Show or hide comments. Overrides the site-level `BookComments` setting. |
| `bookSearchExclude` | `false` | Exclude this page from the search index. |

See [Blog](/docs/content/blog/) for post-specific frontmatter.


# Menu System

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.

## File-Tree Menu

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](/docs/content/pages/).

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

```toml {filename=hugo.toml}
[[menu.before]]
  name = 'Overview'
  url = '/overview/'
  weight = 1

[[menu.after]]
  name = 'Github'
  url = 'https://github.com/user/repo'
  weight = 10

[[menu.after]]
  name = 'Hugo Themes'
  url = 'https://themes.gohugo.io/themes/hugo-book/'
  weight = 20
```

Or add pages to menus via frontmatter

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

### Menu Item Parameters

Menu items support these params under `[params]`:

```toml {filename=hugo.toml}
[[menu.after]]
  name = 'Example'
  url = '/example/'
  weight = 10
  [menu.after.params]
    bookIcon = 'star'       # Icon name to display next to the item
    bookNewTab = true        # Open the link in a new tab
    class = 'custom-class'   # CSS class to add to the menu item
```


# 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

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

## Post Frontmatter

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

```yaml
---
bookPostThumbnail: "cover.*"
---
```

## Date Format

The date display format is configured site-wide via `BookDateFormat`. See [Configuration](/docs/getting-started/configuration/) for details.


# Multi-Language Support

Hugo Book supports Hugo's [multilingual mode](https://gohugo.io/content-management/multilingual/) with content translation by directory.

## Configuration

Define languages in your site config

```toml {filename=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.

## Translation Dropdown

By default, all configured languages appear in the selector. To only show languages that have a translation for the current page

```toml {filename=hugo.toml}
[params]
  BookTranslatedOnly = true
```


# Shortcodes

Hugo Book includes shortcodes for common documentation patterns. All interactive shortcodes work without JavaScript using CSS-only techniques.

Hugo shortcodes use two delimiter styles:

`{{</* shortcode */>}}`
: Renders inner content as plain HTML. Use for shortcodes that don't contain markdown.

`{{%/* shortcode */%}}`
: Processes inner content as markdown. Use when the shortcode body contains markdown formatting.

> [!NOTE]
> Use `{{%/* shortcode */%}}` when the body contains markdown that needs to be rendered. `{{</* shortcode */>}}` passes content as-is without markdown processing.
> When nesting shortcodes (e.g. tabs inside columns), the outer shortcode must use `{{%/* shortcode */%}}` for the inner shortcodes and markdown to be processed.

# Asciinema

Embed terminal recordings with the [Asciinema](https://asciinema.org/) player.

## Syntax

```tpl
{{</* asciinema
  cast="recording.cast"
  loop=true
  autoplay=true
  speed=2 */>}}
```

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

## Example

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

## 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](https://docs.asciinema.org/manual/player/options/) for the full list.

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

# Buttons

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

## Syntax

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

## Example

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

## Parameters

`href`
: URL for external links.

`relref`
: Hugo page reference for internal links.

`class`
: Additional CSS classes.

# Columns

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

## Syntax

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

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

## Example

{{% columns %}}
- ### 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.
{{% /columns %}}

## Custom Ratio

Set relative column widths with the `ratio` parameter

```tpl
{{%/* columns ratio="1:2" */%}}
- ### Sidebar
- ### Content Area
{{%/* /columns */%}}
```

{{% columns ratio="1:2" %}}
- ### 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.
{{% /columns %}}

# Details

Collapsible content using the HTML5 `<details>` element.

## Syntax

Positional arguments:
```tpl
{{%/* details "Title" [open] */%}}
Markdown content
{{%/* /details */%}}
```

Named parameters:
```tpl
{{%/* details title="Title" open=true */%}}
Markdown content
{{%/* /details */%}}
```

## Example

{{% details "What Hugo version is required?" %}}
Hugo Book requires Hugo {x} or later, extended edition. The extended edition is needed for SCSS processing.
{{% /details %}}

{{% details "How do I override the theme?" open %}}
Create matching files in your project's `layouts/` or `assets/` directory. Hugo's lookup order will use your files over the theme's.
{{% /details %}}

## Parameters

`title` (or first positional argument)
: The summary text shown when collapsed.

`open` (or second positional argument)
: Start expanded. Default: collapsed.

# Images

Enhanced image display with click-to-expand behavior.

## Syntax

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

## Example

{{< image src="placeholder.svg" alt="Placeholder image" title="Click to expand" loading="lazy" >}}

## Parameters

`src`
: Path to the image. Supports page resources, site resources, and URLs.

`alt`
: Alternate text for accessibility.

`title`
: Caption displayed below the image.

`loading`
: Loading strategy: `lazy`, `eager`, or `auto`.

`class`
: Additional CSS classes on the `<img>` element.


# OpenAPI

Renders an OpenAPI 3.x specification as a documentation page. Operations are grouped by their first tag.

## Syntax

```tpl
{{%/* openapi src="spec.json" */%}}
```

The spec file is loaded via `resources.Get`, so the path is relative to the site's `assets/` directory. JSON and YAML are both supported.

## Example

{{% openapi src="tictactoe.json" %}}

# Hints

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

## Syntax

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

Or using markdown alerts

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

## Example

{{% hint %}}
**Default hint**  
Without a specified type.
{{% /hint %}}

{{% hint info %}}
**Info**  
Use for supplementary information that helps the reader.
{{% /hint %}}

{{% hint success %}}
**Success**  
Use to highlight a recommended approach or positive outcome.
{{% /hint %}}

{{% hint warning %}}
**Warning**  
Use for important caveats or potential issues.
{{% /hint %}}

{{% hint danger %}}
**Danger**  
Use for critical warnings about breaking changes or data loss.
{{% /hint %}}

## Markdown Alerts

Standard GitHub markdown alert syntax is also supported:

> [!NOTE]
> The theme requires Hugo **extended** edition for SCSS processing.

> [!TIP]
> Set `disablePathToLower = true` in your config to preserve URL casing.

> [!IMPORTANT]
> The `unsafe = true` goldmark setting is required for Mermaid and KaTeX shortcodes.

> [!WARNING]
> Service worker support is experimental and may change in future releases.

> [!CAUTION]
> Enabling `BookPortableLinks = 'error'` will fail the build if any markdown link targets are missing.

# Mermaid

Render diagrams and charts with [Mermaid](https://mermaid.js.org/). The library is loaded automatically on first use.

> [!TIP]
> Override Mermaid initialization by creating `assets/mermaid.json` in your project.

## Syntax

Use fenced code blocks (recommended) or the shortcode

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

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

## Examples

{{% columns %}}

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

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

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

  ```mermaid
  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"
  ```

{{% /columns %}}

Explore more diagram types on the [Mermaid documentation](https://mermaid.js.org/syntax/flowchart.html).

# Steps

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

## Syntax

```tpl
{{%/* steps */%}}
1. ## Step Title
   Step description...

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

## Example

{{% steps %}}
1. ## Create your site
   Run `hugo new site my-docs` to scaffold a new Hugo project.

2. ## Add the theme
   Clone or add hugo-book as a submodule in your `themes/` directory.

3. ## Write content
   Add markdown files under `content/docs/`. Each file becomes a page in the sidebar menu.

4. ## Deploy
   Run `hugo` to build the site. The output is in the `public/` directory, ready for any static hosting.
{{% /steps %}}

# Tabs

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

## Syntax

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

## Example

{{< tabs >}}

{{% tab "macOS" %}}
```shell
brew install hugo
```
{{% /tab %}}

{{% tab "Linux" %}}
```shell
sudo snap install hugo
```
{{% /tab %}}

{{% tab "Windows" %}}
```shell
choco install hugo-extended
```
{{% /tab %}}

{{< /tabs >}}


# KaTeX

Render math typesetting with [KaTeX](https://katex.org/). The library is loaded automatically on first use.

{{< katex />}}

## Activation

KaTeX is activated on the page by the first use of the shortcode or a `katex` code block. You can force activation with `{{</* katex /*/>}}`, then use delimiters anywhere on the page.

## Block Rendering

Three equivalent ways to render display math:

{{% columns %}}

- **Shortcode**
  ```tpl
  {{</* katex display=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
  $$
  ```

{{% /columns %}}

Result:

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

## Inline Rendering

| Syntax | Output |
| -- | -- |
| `{{</* katex >}}\pi(x){{< /katex */>}}` | {{< katex >}}\pi(x){{< /katex >}} |
| `\\( \pi(x) \\)` | \\( \pi(x) \\) |

## Configuration

Override KaTeX options by creating `assets/katex.json`. For example, to enable `$...$` inline delimiters

```json
{
  "delimiters": [
    {"left": "$$", "right": "$$", "display": true},
    {"left": "$", "right": "$", "display": false},
    {"left": "\\(", "right": "\\)", "display": false},
    {"left": "\\[", "right": "\\]", "display": true}
  ]
}
```

See [KaTeX options](https://katex.org/docs/options.html) for all available settings.


# Styles

## Built-in Themes

Set `BookTheme` in your site config

```toml {filename=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/browser preference (`prefers-color-scheme`). |

## Plugin Themes

Additional themes are available as SCSS plugins. Import in your `assets/_custom.scss`

```scss
@import "plugins/themes";
```

Then set `BookTheme` to one of:

| Theme | Description |
| --- | --- |
| `contrast-light`    | High contrast light variant |
| `contrast-dark`     | High contrast dark variant |
| `contrast-auto`     | High contrast, auto-switching |
| `catppuccin-light`  | [Catppuccin](https://catppuccin.com/) Latte palette |
| `catppuccin-dark`   | Catppuccin Frappe palette |
| `catppuccin-auto`   | Catppuccin, auto-switching |
| `ayu-light`         | [Ayu](https://github.com/ayu-theme) light palette |
| `ayu-dark`          | Ayu mirage dark palette |
| `ayu-auto`          | Ayu, auto-switching |

## Custom Theme

Define a theme mixin in `assets/_custom.scss`

```scss
@mixin theme-mytheme {
  --body-background: #fafafa;
  --body-font-color: #333;
  --color-link: #0066cc;
  --color-visited-link: #6633cc;
}
```

Then set `BookTheme = 'mytheme'`. The theme uses `@include theme-{{ .Site.Params.BookTheme }}` to select the mixin at build time.

For auto-switching themes (light/dark based on OS preference), see the `theme-auto` mixin in `assets/_defaults.scss` as a reference.

## CSS Custom Properties

Override CSS custom properties in `_custom.scss` to adjust the current theme. The full set of properties is defined in [`assets/_defaults.scss`](https://github.com/alex-shpak/hugo-book/blob/main/assets/_defaults.scss).

## Custom Styles

The theme includes an empty `assets/_custom.scss` file that is loaded after all theme styles. Create this file in your project's `assets/` directory to add custom CSS without overriding the entire stylesheet.

```scss
// assets/_custom.scss

.book-page {
  max-width: 60rem;
}

.book-menu nav {
  font-size: 0.9rem;
}
```

## SCSS Plugins

The theme ships with optional SCSS plugins. Import them in your `_custom.scss`:

```scss
@import "plugins/numbered"; /* Automatically number headings in the content area */
@import "plugins/scrollbars"; /* Style scrollbars in the sidebar and content area */
```

## SCSS Variables

Layout variables like sidebar width, breakpoints, and padding are defined in [`assets/_defaults.scss`](https://github.com/alex-shpak/hugo-book/blob/main/assets/_defaults.scss). Override them in your `_custom.scss`.

## Override Priority

Hugo's [lookup order](https://gohugo.io/templates/lookup-order/) lets you override any theme file by creating the same file in your project:

- `layouts/`: Override templates and partials
- `assets/`: Override SCSS and JavaScript
- `static/`: Override static files (favicon, images)
- `i18n/`: Override or add translations


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

```html
{{ with .Site.Params.googleAnalytics }}
<script async src="https://www.googletagmanager.com/gtag/js?id={{ . }}"></script>
{{ end }}
```

To add a custom banner above every page, create `layouts/_partials/docs/inject/content-before.html`

```html
<div class="my-banner">
  This documentation is for version 2.0. See <a href="/v1/">version 1.0 docs</a>.
</div>
```