VPS者

- Introduction: http://vpser.xyz/docs/getting-started/introduction/
- Create a Site: http://vpser.xyz/docs/getting-started/create-a-site/
- Configuration: http://vpser.xyz/docs/getting-started/configuration/
- Organisation: http://vpser.xyz/docs/content/organisation/
- Pages: http://vpser.xyz/docs/content/pages/
- Menus: http://vpser.xyz/docs/content/menus/
- Blog: http://vpser.xyz/docs/content/blog/
- Multi-Language: http://vpser.xyz/docs/content/multilingual/
- Shortcodes: http://vpser.xyz/docs/content/shortcodes/
- Asciinema: http://vpser.xyz/docs/content/shortcodes/asciinema/
- Buttons: http://vpser.xyz/docs/content/shortcodes/buttons/
- Columns: http://vpser.xyz/docs/content/shortcodes/columns/
- Details: http://vpser.xyz/docs/content/shortcodes/details/
- Images: http://vpser.xyz/docs/content/shortcodes/experimental/images/
- Hints: http://vpser.xyz/docs/content/shortcodes/hints/
- Mermaid: http://vpser.xyz/docs/content/shortcodes/mermaid/
- Steps: http://vpser.xyz/docs/content/shortcodes/steps/
- Tabs: http://vpser.xyz/docs/content/shortcodes/tabs/
- KaTeX: http://vpser.xyz/docs/content/shortcodes/katex/
- Styles: http://vpser.xyz/docs/customization/styles/
- Inject Partials: http://vpser.xyz/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 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](/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/)
- [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]
# (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](https://lucaong.github.io/minisearch/). 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.

## Favicon

The theme links these files from the `static` directory:

- `favicon.svg`: modern browsers
- `favicon.png`: fallback for browsers without SVG favicon support
- `apple-touch-icon.png`: iOS home screen icon

To use your own favicon, place files with the same names in your project's `static` directory. They take precedence over the theme's files.

To use different file names or formats, override `layouts/_partials/docs/html-head-favicon.html` in your project.

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

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 {filename=_index.md}
---
title: My Page
weight: 10
params:
  bookToC: true
  bookCollapseSection: true
---
```
{{% /tab %}}

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

{{% tab "JSON" %}}
```json {filename=_index.md}
{
  "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. |
| `bookBreadcrumbs`   | | Show or hide breadcrumbs. Overrides the site-level `BookBreadcrumbs` setting. |
| `bookPageLinks`     | | Show or hide linked pages under the table of contents. Overrides the site-level `BookPageLinks` 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]
    class = 'custom-class'     # CSS class to add to the menu item
    bookIcon = 'star'          # Icon name to display next to the item
    bookNewTab = true          # Open the link in a new tab
    bookCollapseSection = true # Collapse child items
```


# 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

All configured languages appear in the selector. A language without a translation of the current page links to its home page.


# 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.
{{% /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" width="50%" >}}

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

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

> [!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. By default diagrams follows the site theme colors.

> [!TIP]
> 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

````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
```
{{% /tab %}}

{{< /tabs >}}


# KaTeX

Render math typesetting with [KaTeX](https://katex.org/).

## 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](#passthrough) needs to be configured.

## Block Rendering

Three equivalent ways to render display math:

{{% columns %}}

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

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

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

{{% /columns %}}

Result:
```katex
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) \\)` | {{< katex >}}\pi(x){{< /katex >}} |

## Parameters

Shortcode and block parameters are the same as original from `transform.ToMath`. See Hugo [documentation](https://gohugo.io/functions/transform/tomath/#options)

## Passthrough 

Hugo offers a hook to render math as passthrough, without codeblocks or shortcodes. See [configuration](https://gohugo.io/functions/transform/tomath/#example) in Hugo documentation.

```yaml {filename=hugo.yaml}
markup:
  goldmark:
    extensions:
      passthrough:
        enable: true
        delimiters:
          block:
          - ['\[', '\]']
          - ['$$', '$$']
          inline:
          - ['\(', '\)']
```

```go {filename="layouts/_markup/render-passthrough.html"}
{{/*- $opts := dict "displayMode" (eq .Type "block") -*/}}
{{/*- (transform.ToMath .Inner $opts) -*/}}
```


# Styles

## Built-in Themes

Theme comes with a set of predefined color schemes, Use `BookTheme` parameter 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 |
| `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 |

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

## Custom Theme

A theme is just a block of CSS variables selected by `data-theme`. You can define your own in `assets/styles/custom.css`:

```css {filename="assets/styles/custom.css"}
:root[data-theme="mytheme"] {
  --body-background: #fafafa;
  --body-font-color: #333;
  ...
}
```

Then set `BookTheme = 'mytheme'`.

## Custom Styles

The file `assets/styles/custom.css` is loaded last, so it overrides every theme style, in this way you can customize styles without editing Hugo theme sources.

```css {filename="assets/styles/custom.css"}
.book-page {
  max-width: 60rem;
}

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

## CSS Variables

The theme is driven by CSS variables:

- Per-theme colors — [`assets/styles/themes.css`](https://github.com/alex-shpak/hugo-book/blob/main/assets/styles/themes.css)
- Base tokens (font sizes, spacing, etc) — [`assets/styles/variables.css`](https://github.com/alex-shpak/hugo-book/blob/main/assets/styles/variables.css)

Override any of them in `assets/styles/custom.css`. To adjust the current theme regardless of which one is active, target `:root`:

```css {filename="assets/styles/custom.css"}
:root {
  --menu-width: 18rem;
}
```

## File overrides

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