Skip to content

This is the multi-page printable view of this section. .

Return to the regular view of this page.

Authoring

Write documentation pages, blog posts, books, release pages, and API references. Learn the page structure and content organization.

This section covers all content types supported by OINK: documentation pages, blog posts, books, Expo image albums, release and download pages, and OpenAPI references. They share a single Markdown dialect and front matter schema, while each content type adds its own layout conventions.

What a documentation page is made of

Every documentation page is a single Markdown file. YAML front matter between the opening --- lines sets the page metadata (title, linkTitle, description, and weight), followed by standard Markdown and OINK’s native components:

content/docs/install.md
---
title: Install Pigsty
linkTitle: Install
description: Get a working PostgreSQL cluster onto a clean EL 9 machine.
weight: 20
---

## Prerequisites {#prerequisites}

A Linux machine you can reach over SSH, passwordless `sudo`, and Python 3.11 or
newer.

> [!IMPORTANT]
> The installer rewrites `/etc/yum.repos.d/`. Back it up first.

Save the file as content/docs/install.md and run hugo server. The page is served at /docs/install/ with an Install entry in the left sidebar.

Common Markdown patterns

Most everyday components use standard Markdown plus a Goldmark attribute block rather than custom shortcodes:

Pattern Syntax Guide
Explicit heading anchor ## Prerequisites {#prerequisites} Writing pages
Callout / admonition > [!NOTE] (TIP, IMPORTANT, WARNING, CAUTION, DETAILS) Callouts
Code tabs Adjacent code fences with ```bash {tab="macOS"} Tabs
Numbered steps An ordered list followed by {.steps} on the next line Steps
Navigation cards A bullet list of links followed by {.cards} on the next line Cards
Parameter / field table A Markdown table followed by {.fields} on the next line Fields
Captioned or sized image ![alt](/img.webp) followed by {width="800" caption="..."} Images
File tree A ```filetree fenced block using a YAML-like list FileTree

Content types and where they are covered

What you are writing Where to go
A documentation page: front matter, heading anchors, links, images, drafts Writing pages
The tree and the sidebar: _index.md, weight, icons, folding, multiple sidebar roots Organizing content
Looking up what a front matter key means Page parameters
A blog post, a release announcement, RSS Blog posts
A book: chapter numbering, figures and tables, cross-references, whole-book print Books
An image album: file structure, metadata, layouts, and the image viewer Expo albums
A release and download page: version cards, asset tables, checksums Releases and downloads
An OpenAPI reference page API reference pages
Writing in two languages: paired files, aligned anchors, fallback for untranslated pages Languages
A component’s syntax and parameters Components

1 - Writing pages

Create a documentation page. Learn where to save it, how to set front matter and anchors, and how links, images, and page-end controls work.

This page covers the complete process for writing a documentation page. It explains file location, front matter, heading anchors, links, images, drafts, and page-end controls. The site must already build locally. If it does not, start with Quick start.

Creating a page

A page is a Markdown file under content/. Its location determines its URL. For example, content/docs/install.md is published as /docs/install/. The Chinese translation is a .zh.md file of the same name in the same directory, sharing one logical path with the English page.

Use a single file for a page without attached resources. If a page has images, cast files, or example configuration, create a directory. Name the page file index.md and put the resources beside it. Hugo calls this a page bundle:

the two page shapes inside content/

  • content/
    • docs/
      • _index.mdsection index, English
      • _index.zh.mdsection index, Chinese
      • install.mdsingle-file page → /docs/install/
      • install.zh.mdits Chinese translation
      • anatomy/page bundle → /docs/anatomy/
        • index.md
        • index.zh.md
        • shell.webppage resource, shared by both languages

hugo new content docs/install.md generates an empty file with front matter from an archetype. See the Hugo documentation. You can also write the file manually.

Important

When a Chinese page has no English counterpart, Hugo does not give it resources without a language suffix. In that case the resource filename needs the .zh. infix (shell.zh.webp) while the body still writes shell.webp.

The front matter you need

Between the two --- lines at the top of the file is YAML front matter. Four keys belong on every page:

content/docs/install.md
---
title: Install Pigsty       # page heading, browser title, search result title
linkTitle: Install          # short name in the sidebar and breadcrumbs; falls back to title
description: Get a working PostgreSQL cluster onto a clean EL 9 machine.
weight: 20                  # ordering among siblings; use multiples of 10 to leave room
---

Use description to state in one sentence what the reader can accomplish. It appears on section index cards, in search results, and on social cards. weight determines sidebar order. Only equal weights use alphabetical order.

Other keys are optional. These include the icon, draft status, search weight, comment switch, and page shell. For the full table, see Page parameters.

Heading levels and stable anchors

Start body sections at ##. Reserve # for title. The theme renders the page heading. Another # in the body creates a second top-level heading. The right column outline starts at ##. Hugo’s markup.tableOfContents determines its maximum depth. This site uses ####.

Write an explicit English anchor {#id} on every ## and ###:

Source
## Prerequisites {#prerequisites}

### Disk and memory {#disk-and-memory}

There are two reasons:

  • Cross-language alignment. Hugo derives an ID from heading text. A Chinese heading produces a Chinese ID. /docs/install/#prerequisites and /zh/docs/install/#前提条件 identify equivalent places with different anchors. A translation audit cannot compare them. Give the translated heading the English page’s ID. Both pages then share one fragment.
  • Link stability. Revisions can change heading text. They should not break public links. After publication, an explicit ID is a public route. If you must rename it, leave an empty anchor for the old ID:
Source: leaving a target behind for the old anchor
## Getting started <a id="get-started"></a> {#quickstart}

Use lowercase English with hyphens, unique within the page. This site’s translation audit compares the heading IDs rendered by the English and Chinese pages and fails on a mismatch.

Use one of these three forms, according to its purpose:

Form Example When to use it
Absolute site path [Configuration](/docs/customize/config/) The default. It points at a published route, is easy to audit and replace site-wide, and survives source files moving
Relative path [another page](../organize/), ![diagram](shell.webp) Resources inside the same page bundle, or a neighboring page that should follow the source directory
The ref / relref shortcode [Configuration]({{</* ref "/docs/configure/overview" */>}}) If the target must exist at build time. A missing target fails the build instead of leaving a broken link

All three carry a trailing slash and point at directory-style routes (/docs/write/pages/), matching Hugo’s default permalinks.

The theme has no link render hook. It passes links to Goldmark unchanged. External links do not automatically receive target="_blank". If you need a new tab, write HTML or use the site’s layouts/_markup/render-link.html.

Plain Markdown links are not checked for target existence. Use these rules:

  • Prefer absolute paths for internal links. After restructuring the site, use grep to replace them site-wide.
  • When you move a page, add aliases for the old path. Update internal links to the new route. Do not use an alias for navigation indefinitely.
  • If you are unsure that a target exists, use ref. The build then checks it.

In a bilingual site, link to the logical page (/docs/write/pages/) rather than to a .zh.md filename, and keep fragment IDs language-neutral.

Where images go

Put a page’s screenshots in its page bundle. Put shared images in assets/images/. Put large files that require no processing in static/. Use ![alt text](source) for all three. An attribute line controls caption, size, zoom, and numbering. See Images.

Drafts and publishing

A page with draft: true never reaches the build output:

front matter
---
title: Migration guide, not yet final
draft: true
---

Preview with hugo server -D to show drafts (-D is --buildDrafts). A page whose date is in the future is also excluded. -F shows those pages. A production build uses neither switch, and plain hugo publishes only finished content.

OINK’s Markdown extensions

The body is standard Markdown (Goldmark) plus the native forms below. Each is ordinary Markdown syntax with one attribute line, and each stays readable as source on GitHub:

Component Shortest syntax Page
Callouts > [!NOTE] on the first line of a blockquote Callouts
Tabs Two adjacent fences each carrying {tab="Homebrew"} Tabs
Steps An ordered list followed by a {.steps} line Steps
Cards A list of links followed by a {.cards} line Cards
Field lists A table followed by {.fields meta="type default"} Fields
Table extras A table followed by {.matrix} or {caption="…"} Tables
Code blocks {title="hugo.yml" copy=false} on the fence info line Code Blocks
Images A standalone image followed by {caption="…" width="600"} Images
File trees A filetree fence, one - name/ # comment per line FileTree
Mathematics A math fence, or display math wrapped in $$ Math
Diagrams A mermaid fence (also plantuml, markmap, echarts) Mermaid

The remaining components use shortcodes. These include badges, keys, file includes, terminal recordings, and the Book figure and table family. For syntax and parameters, see Components.

A combined example: code fences and a callout inside steps.

Source
1. Install Hugo Extended, 0.168.0 at the oldest:
   ```bash
   brew install hugo
   ```
1. Clone OINK Starter and preview it:
   ```bash
   git clone https://github.com/pgsty/oink-starter my-docs
   cd my-docs && hugo server
   ```
   > [!TIP]
   > Add `-D` to preview drafts as well.
{.steps}
  1. Install Hugo Extended, 0.168.0 at the oldest:
    brew install hugo
  2. Clone OINK Starter and preview it:
    git clone https://github.com/pgsty/oink-starter my-docs
    cd my-docs && hugo server
    Tip

    Add -D to preview drafts as well.

What appears at the end of a page

The theme generates these four blocks in a fixed order. Do not write them in the body. An optional Share bar appears before them:

Position What it is Default Where to configure
1 Feedback: the two “Was this page helpful?” buttons Off Repository links and page info
2 Last modified: the time and the most recent commit subject, linked to GitHub On when Git information is available Repository links and page info
3 Pager: previous and next, in sidebar tree order On for docs / book / blog Navigation and menus
4 Comments: giscus When configured and enabled Comments

The theme also generates the action menu beside the title. It includes copy Markdown, edit this page, view history, open an issue, and print. Configure it in Repository links and page info.

To turn off a control for one page, set its front matter: feedback: false, annotation: false, pager: false, comments: false. The keys are described in Page parameters.

Verify

After writing a page, run a production build:

hugo --printPathWarnings
  • The build must exit with Total in … and no ERROR. An invalid attribute key or component parameter logs a warning with a source position and renders a safe fallback, whereas a ref pointing to a missing target fails the build.
  • --printPathWarnings flags any two pages that resolve to the same output path, which is most common in multilingual sites or after editing permalinks.

Then confirm three things in the browser:

  1. The page appears in the sidebar at the position determined by weight.
  2. The right-hand outline lists your ## headings. Clicking a heading adds an English anchor to the URL.
  3. The English and Chinese versions of the same heading share an anchor (this site audits that with node scripts/check-doc-translations.mjs --public public).

2 - Organizing content

Use the directory structure to create the sidebar tree. Configure _index.md, weight, index styles, icons, folding, hidden pages, and documentation paths.

OINK requires no separate navigation configuration. The directory structure under content/ creates the sidebar tree. This page covers how directories and files are arranged, section indexes, ordering, icons, folding, hiding, and multiple sidebar roots.

Directories are the sidebar

Hugo calls a directory a section. Its Markdown files are pages. A nested directory is a subsection. The sidebar renders this tree level by level. weight determines order. linkTitle supplies labels, with title as fallback. The tree on the left comes from this source:

the first two levels of content/docs/

  • content/
    • docs/
      • _index.mdsection root: type: docs + cascade
      • about/Introduction
        • _index.md
        • features.md
      • start/Get started
        • _index.md
      • write/Authoring (this section)
        • _index.mdweight: 30
        • pages.mdweight: 10
        • organize.mdweight: 20
        • frontmatter.mdweight: 30
      • components/Components
        • _index.md

Every directory needs an _index.md

A section index is the _index.md inside the directory (_index.zh.md for Chinese). Without this file, Hugo still creates the section. It has no title, description, icon, or weight. The sidebar shows the directory name. You cannot control its order.

content/docs/deploy/_index.md
---
title: Deploy
linkTitle: Deploy
description: Publish the site to GitHub Pages, Cloudflare Pages or your own Nginx.
weight: 50
icon: fa-solid fa-cloud-arrow-up
---

A section _index.md also supports cascade. It applies shared settings to the whole subtree. You do not need to repeat them on each page.

content/docs/reference/_index.md
---
title: Reference
weight: 90
cascade:
  pager: false        # no previous / next on any page in this subtree
  search_boost: 0.8   # reference pages rank slightly lower in search
---

Ordering: use multiples of 10 for weight

Pages in a section use ascending weight order. Only equal weights use date and linkTitle. Always use multiples of 10, such as 10, 20, and 30. You can then insert a page between others without changing their weights. A section’s own weight decides its position among its siblings.

A page with no weight counts as 0, and Hugo places those after every page that does have one, ordered among themselves by date and title. That order changes as content changes. Give every page a weight.

Single file or page bundle

A page with no resources of its own is a single slug.md. For a page with images, cast files, or example files, use a directory. Put index.md and the resources in that directory. The two shapes look identical in the sidebar and produce the same URL. See Writing pages.

List or cards on a section index

After the body of an _index.md, the theme appends an index of the child pages in one of two styles:

hugo.yml: the site-wide default
params:
  ui:
    section_index: cards # list | cards

list is the theme default. It shows one line per child page with its title and description. cards is a grid of link cards reading each child’s icon, linkTitle and description. This site uses cards, and this section’s index page is the example. Override it in a single section’s front matter when that section needs the other style:

content/docs/reference/_index.md
section_index: list
cascade:
  section_index: list   # and its descendant sections too

Two page-level switches work independently of the style. simple_list: true renders a compact bulleted list. no_list: true generates no index. Use the latter when the page body supplies its own navigation.

Tip

In the card style, description is the card body. Keep it to one sentence that fits on a single line.

Sidebar icons

Write one Font Awesome class pair in a page’s or section’s front matter:

content/docs/deploy/_index.md
icon: fa-solid fa-cloud-arrow-up

Icon density is a site-level policy, so that leaf pages do not all carry icons:

hugo.yml
params:
  ui:
    sidebar_icon_policy: groups # all | groups | none
Value Effect
all Every entry that declares an icon shows it (the compatibility default when unset)
groups Only the root and nodes with children show icons. Ordinary leaf pages do not
none No entry icons in the sidebar

For a new site, set groups explicitly. Groups then keep their identifying icons, and leaf pages omit icons. This site uses that setting. Only the six sections on the left have icons.

Expanding and folding

A section with children carries a fold arrow in the sidebar. OINK saves the whole sidebar’s collapse, width, and scroll state. To persist individual branch choices, add optional site code using the sidebar runtime API. By default, the path containing the current page is expanded. Other paths are collapsed. Blog-type sections are expanded by default.

content/docs/reference/_index.md
sidebar_expanded: true   # this section is always expanded by default

Site-level folding, compact mode, initial expansion depth, width and truncation are configured in Layouts and page types. The full key definitions are in Configuration.

Hiding from the sidebar

Front matter Effect
toc_hide: true The page is absent from the sidebar tree (it is still published, and links to it still work)
hide_summary: true The page is absent from the section index
sidebar_divider: true The entry stops being a link and becomes a group heading in the sidebar
manual_link: https://… The sidebar row points elsewhere. Pair it with manual_link_title and manual_link_target: _blank

toc_hide and hide_summary control two different entry points, so set both only when the page should appear in neither.

Groups without a landing page

Since OINK 1.1, a divider section keeps its children while its title has no link. This fixes the missing children in v1.0.0. Use this _index.md when the directory should only organize child pages:

---
title: Reference
sidebar_divider: true
build:
  render: never
---

The title is a group label. If sidebar folding is enabled, its button folds the children. The children remain in the pager, search, navigation JSON, and Print. Without JavaScript, the group stays expanded. Omit build to keep publishing the section page while still showing a non-link sidebar label. Leaf dividers keep their old separator appearance.

toc_hide hides a section’s entire subtree. no_list only removes the child list from a section’s body, and hide_summary removes an entry from its parent page. None of these is a replacement for a group-only section. build.render: link retains a permalink without publishing a page. For an unpublished group, prefer never. This prevents other navigation from creating a destination.

The shell follows type, not the path

The documentation shell (sidebar, table of contents, breadcrumbs, pager) does not depend on the directory name. It depends only on whether the page’s type is listed in params.ui.shell_types:

hugo.yml: the theme default
params:
  ui:
    shell_types: [docs, book, blog, swagger]

Documentation can therefore live at any path, with type assigned by a cascade. To put a handbook at content/handbook/, the section root reads:

content/handbook/_index.md
---
title: Operations handbook
type: docs
sidebar_root_for: self      # the sidebar tree roots here rather than falling back to /docs
cascade:
  type: docs                # the whole subtree uses the documentation shell
---
Important

When the documentation directory is not called docs, sidebar_root_for: self is needed alongside type: docs. Otherwise the sidebar looks for its root at params.ui.docs_section (default docs), and a reader under /handbook/ sees the /docs/ tree.

Multiple sidebar roots

By default, the current top-level section is the sidebar root. A row above the tree names that root. A large subtree can have its own root. For example, use a separate root for a versioned API reference or a self-contained handbook:

content/docs/api/v2/_index.md
---
title: API reference v2
sidebar_root_for: self   # self | children
---
Value Meaning
self The section’s index page and all its descendants take it as their sidebar root
children The index page stays in the parent tree. Only descendants use this root

The switcher above the root is site-wide. It lists every top-level section and every section that declares sidebar_root_for: self. With one entry, it shows a plain link. With two or more entries, it shows a dropdown. To keep a top-level section or nested self-root out of the global choices, write sidebar_root_menu: false in its _index.md. The current root remains as a location marker when browsing that section.

Below the switcher, the section index remains the tree’s first link. The switcher selects a tree. The root link opens a document. sidebar_root_link_self: false makes that row point at the parent section instead.

Verify

hugo --printPathWarnings

The build must complete with Total in … and no ERROR. --printPathWarnings flags any two pages that resolve to the same output path when restructuring directories.

Then confirm each of these in the browser:

  1. The sidebar order matches the weight values you wrote, and a new section appears where expected.
  2. The section index lists every child (a missing one comes from hide_summary or a missing _index.md).
  3. Breadcrumbs and the pager follow the same order as the sidebar, because the pager reads the same tree.
  4. The tree has the same shape after switching language (every _index.md needs a .zh.md counterpart).

When sidebar entries exceed params.ui.sidebar_menu_truncate, the build warns and says what to raise it to. Do not ignore that warning. Truncated entries never appear in the sidebar.

Controlling a branch from site code

The window.OinkSidebar API is available since OINK 1.1. v1.0.0 does not provide it. Load site code after the theme scripts, for example through layouts/_partials/hooks/body-end.html, and wait for ready before reading or restoring branch state. This example expands the first sidebar group:

const sidebar = window.OinkSidebar;
if (sidebar) {
  sidebar.ready.then(() => {
    const button = document.querySelector(
      '#td-shell-sidebar [data-td-shell-tree-toggle]'
    );
    if (!button) return;
    const id = button.getAttribute('aria-controls');
    sidebar.setExpanded(id, true);
  });
}

Use the button’s existing aria-controls value as the region ID. getState(id) returns {id, expanded} or null. A change sends one oink:sidebar-disclosure event on document, after the button, region and accessibility state agree. Its detail is {id, expanded, source}. Repeated writes of the same value send no event. Restoring through the API keeps the current page’s ancestor groups open, while a reader can still fold them.

The theme does not save individual branch preferences. A site that adds this should own the storage key’s language and navigation-version scope, tolerate unavailable storage, and ignore IDs absent from the current page. The sidebar contract defines the lifecycle.

3 - Page parameters

The full front matter table — active page keys and retained 1.x compatibility no-ops, grouped by sidebar, shell, search, output, page end, Book, Expo, landing and release pages.

This page lists all page-level parameters that OINK reads, including explicit 1.x compatibility no-ops. It omits keys that the theme reads only to warn about a rename or removal. Those keys are in Migration, and they are also kept out of the generated editor schema. Hugo’s own front matter fields (slug, url, build, sitemap, expiryDate and others) work as usual. For their meaning, see the Hugo documentation. Site parameters (params.* in hugo.yml) are in Configuration.

How to read the tables

Precedence, highest first:

  1. The page’s own front matter.
  2. The nearest cascade. If several cascade layers set the same key, the closest layer takes precedence.
  3. The site parameter in hugo.yml.

Keys whose Default column says “site value” fall back to the site parameter of the same name when unset.

Write page keys at the top level of front matter, without the site key’s ui. prefix. For example, the site’s params.ui.section_index becomes the page’s section_index. Do not nest these keys in a ui: block: the theme neither reads nor reports a ui: block there. If a setting has no effect, check its key name against this page.

content/docs/wide-reference.md
---
title: Compatibility matrix
weight: 40
page_width: wide
footer_style: slim
image_zoom: true
section_index: list
---

Inside a cascade, use the same key names one level deeper:

content/docs/reference/_index.md
cascade:
  pager: false
  section_index: list

An invalid value does not abort the build: the theme logs a warning naming the key, supplied value, and fallback, then renders the page with the default listed below so a single typo does not return HTTP 500 across hugo server.

When continuing with a default would publish misleading metadata—such as an incomplete upstream attribution—the theme logs a warning and omits the block entirely. Unresolved content references (ref / relref) still fail the build through Hugo.

Basics

title , string , default—
Page heading, browser title, search result title. Required on every page
linkTitle , string , defaulttitle
Short name in the sidebar, breadcrumbs, pager and cards
description , string , default—
One-sentence summary for section cards, search snippets, and meta description. Blog pages also show it as an introduction above the body
weight , integer , default0
Order among siblings. Use multiples of 10. 0 (unset) sorts after every page with a weight. See Organizing content
draft , boolean , defaultfalse
A draft never reaches build output. Use hugo server -D to preview it. See Writing pages
date , date , default—
Blog date and release-page sort key. A future date excludes the page by default
lastmod , date , defaultGit commit time
The page-end “last modified” time. No manual value is needed if the site enables enableGitInfo
aliases , string array , default—
Redirects an old path to this page. Use for page migration rather than everyday navigation
type , string , defaulttop-level directory name
Decides the template and the shell: docs, book, blog, swagger — see Organizing content
layout , string , default—
Picks a layout for one page: landing, releases
cascade , map , default—
Applies the keys below to the whole subtree

Sidebar and navigation

The guide is Organizing content.

icon , Font Awesome class pair , default—
Icon in the sidebar, section cards and search results, e.g. fa-solid fa-rocket
toc_hide , boolean , defaultfalse
Excludes this page and its subtree from sidebar navigation and the pager sequence, in both content-derived and explicit trees
hide_summary , boolean , defaultfalse
Absent from the section index
sidebar_divider , boolean , defaultfalse
A non-link group heading, excluded from pager destinations. The 1.1 implementation retains a section’s children. Use build.render: never for a group without its own page
sidebar_expanded , boolean , defaulttrue for blog sections, false otherwise
This section is expanded by default in the sidebar
sidebar_root_for , self / children , default—
Makes this section a sidebar tree root. self includes the section index. children covers descendants only. Any other value warns and is ignored
sidebar_root_link_self , boolean , defaulttrue
The root row links to itself. false links to the parent section instead. A non-boolean warns and uses true
sidebar_root_menu , boolean , defaulttrue
Includes a top-level section or nested self-root in global switcher choices. An excluded current root remains a location marker. The nested-root exclusion is fixed in 1.1
toc_root , boolean , defaultfalse
When the sidebar root is the site home, excludes this whole top-level section from the tree and the pager sequence
manual_link , URL , default—
The sidebar and section index row points elsewhere
manual_link_relref , content reference , default—
The same link, resolved with relref. A missing target fails the build
manual_link_title , string , defaulttitle
Hover title for the manual link
manual_link_target , string , default—
For example _blank. The theme adds noopener
no_list , boolean , defaultfalse
The section index generates no child list
simple_list , boolean , defaultfalse
The child index renders as a compact bulleted list
section_index , list / cards , defaultsite value (list)
Style of the child index. An invalid value warns and falls back
section_index_columns , integer , default2
Column count in the card style
notoc , boolean , defaultfalse
Hides the right-hand page outline
pager , boolean , defaultdecided by params.ui.pager_types
false turns off previous / next for this page. A non-boolean warns and is ignored
navbar_enabled , boolean , defaultsite value (true)
Whether this page renders the navbar
navbar_autohide , boolean , defaultsite value (false)
The navbar hides itself on pointer devices
breadcrumb , boolean , defaultshell default
Whether this page renders breadcrumbs. Docs/Book default on. Blog defaults off
theme_color , string , defaultsite value
#rgb/#rrggbb hex value for this page’s accent backgrounds. In a section root’s cascade, it gives the whole section an identity. See Brand and appearance
theme_color_dark , string , defaultderived
The dark-mode accent. If a page overrides theme_color under a cascade that sets this key, it inherits that dark value. Override both. theme_color: false opts the page out of an inherited section color entirely
page_context_menu , boolean , defaultsite value (true)
The page action menu on the title row (copy Markdown, edit this page, print, …)
page_context_menu.assistant_links , boolean , defaultsite value (false)
The ChatGPT / Claude link items, written page_context_menu: { assistant_links: false }. A page may only restrict the site policy. It may never enable these links alone

Page shell

Site-level defaults and what they do are in Layouts and page types.

page_width , normal / wide / full , defaultnormal
Width of the content column. An invalid value warns and falls back
reading_width , slim / normal / wide , defaultnormal
Reading width on Book pages. Applies only to type: book
footer_style , fat / slim / none , defaultsite value (fat)
Footer shape. An invalid value warns and falls back
body_class , string , default—
A class appended to <body> for the site’s own CSS
reading_time , boolean , defaultsite value
Whether this page shows a reading time. false hides it
sidebar_enabled , boolean , defaulttrue
Whether this page shows the left sidebar. false hides it
scroll_spy , boolean , defaultsite value
Silent 1.x compatibility no-op. The normal shell runtime always provides active-heading tracking
keyboard_nav , boolean , defaultsite value (true)
Single-key keyboard navigation — see Keyboard navigation. A non-boolean warns and falls back
lastmod_commit , subject / hash / none , defaultsubject
How the commit is shown after “last modified”. An invalid value warns and falls back
sidebar_expand_levels, sidebar_menu_compact, sidebar_menu_foldable, sidebar_item_overflow , as the site parameter , defaultsite value
Each page can override sidebar behavior. The values are in Configuration
sidebar_width_min, sidebar_width_max , positive integer , defaultsite value (220 / 480)
Per-page minimum and maximum for desktop sidebar resizing. A minimum above its maximum warns and restores the site pair
code_copy , boolean , defaultsite value (true)
Default copy control for code blocks on this page. An explicit fence copy= takes precedence
toc_style , fixed / flow , defaultsite value (fixed)
Fixed right-rail panel or a wider rail beginning in the content flow
toc_taxonomies , boolean , defaultsite value (true)
Whether taxonomy clouds join the right-rail outline
taxonomy_icons , map , defaultsite value
Per-taxonomy icon overrides for this page or section cascade

The guide is Search.

search_keywords , string or string array , default—
Extra search terms, including synonyms and other languages
search_boost , positive number , default1.0
Ranking multiplier. The final score is the text match score times this value. A non-numeric, non-finite, zero or negative value warns and falls back to 1.0
search_exclude , boolean , defaultfalse
Keeps the page out of the local index

Output formats

The guides are AI-agent support (.md and llms.txt) and Print.

outputs , string array , defaultsite outputs
The output formats this page generates. [HTML] disables the .md version
no_print , boolean , defaultfalse
Excluded from the whole-chapter and whole-book print aggregate

Page end: comments, feedback and provenance

The order is fixed: feedback → provenance → pager → comments. See Writing pages.

comments , boolean , defaultsite params.comments.enable (false)
Whether this page shows the giscus comment section — see Comments
feedback , boolean or map , defaultsite params.ui.feedback (off)
The map form takes enable and reasons. Anything else warns and falls back
annotation , boolean , defaultsite params.ui.annotation (on)
The “last modified / provenance” block at the page end. Only a boolean is accepted. Other values warn and fall back
backlinks , boolean , defaultsite params.ui.backlinks (off)
Whether the right rail shows the “Backlinks” group beside the table of contents. A section can cascade it. Only a boolean is accepted; anything else warns and falls back — see Navigation and menus
translation_notice , language code or false , defaultsite params.ui.translation_notice (off)
The language code of the authoritative version, so a translation can say so and link back. Write false on a page authored natively in this language

Upstream attribution

When a page is derived from material elsewhere, upstream_link declares the source and the page-end provenance line gives the work, the copyright holder, the license, and a link to the full notice. This family resolves site parameters → the data/upstreams entry named by upstream_source → this page’s front matter. The most specific declaration takes precedence.

upstream_link is read from front matter only (a cascade counts, site parameters do not). A site-wide value would make every page claim the same source. A companion key without upstream_link warns and the attribution is omitted.

upstream_link , URL , default—
The address of the material this page is derived from. An empty string opts out of an inherited cascade value
upstream_name , string , default—
The upstream work, as the attribution names it. Required once upstream_link is set
upstream_copyright , string , default—
The copyright notice, retained as upstream wrote it. Required
upstream_license , SPDX identifier , default—
Must be found in data/licenses, or it warns and the attribution is omitted. Required
upstream_notice , site path or URL , default—
The page carrying the full notice (licence text, warranty disclaimer, upstream NOTICE, snapshot pin). Required
upstream_ref , string , default—
The tag or commit the snapshot pins, shown in parentheses after the work
upstream_source , string , defaultsite parameter
The entry name in data/upstreams, for upstream facts shared by many pages. A missing entry warns and omits the attribution
upstream_modified , boolean , defaultfalse
Changes the credit verb to say the work was adapted. If the site has repository information, the same attribution sentence also includes a “view history” link. A non-boolean warns and the page is treated as unmodified

Missing any one of the four required keys (upstream_name, upstream_copyright, upstream_license, upstream_notice) warns and omits the attribution. A partial attribution can mislead readers more than an obvious omission. The theme ships an SPDX table at data/licenses.yaml, and a site adds to or overrides it with a file of the same name.

Image zoom

image_zoom , boolean , defaultsite value (false)
Whether images on this page open full size — see Images. A non-boolean warns and falls back

Blog posts

The guide is Blog posts.

See List layouts for the four presentation choices. gallery and blog_gallery are available in OINK v1.4.0; the supported layouts are list, cards, table, and gallery.

author , string , default—
Post byline. Inline Markdown is allowed. Ignored on a page that has authors
authors , string array , default—
Terms of the authors taxonomy, in byline order — see Authors and bylines. Needs author: authors under taxonomies:
series , string array , default—
Terms of the series taxonomy. The strip above the body uses the first one — see Series
series_weight , integer , default—
Place in the series. Weighted members come first in ascending order, the rest follow by ascending date
tags , string array , default—
Tags — see Taxonomies
categories , string array , default—
Categories, likewise
images , string array , default—
The first entry becomes the post’s featured image and share card. Put it in a section _index.md cascade for a section-wide default. images: [] opts the page out of an inherited cascade value. It does not suppress an image the page bundle already supplies under a featured, cover or thumbnail name
byline , string , default—
Credit shown with the resolved featured image when that image is rendered
featured_image , none / banner / wash / hero , defaultsite value (none)
How this article renders its own featured image. hero creates a full-width image shell. An invalid value warns and falls back
blog_index , list / cards / table / gallery , defaultsite value (list)
Blog section index layout. A standalone table with blog_index_toggle: false lists the whole section without pagination. An invalid value warns and falls back
blog_index_columns , positive integer , defaultsite value (3)
Card columns at wide breakpoints. Medium and narrow layouts retain their responsive limits
blog_index_size , positive integer , defaultsite value (12)
Posts per page for list, cards, gallery, and all four views when switching is enabled. A standalone table ignores it
blog_index_toggle , boolean , defaultsite value (false)
Publishes all four layouts and remembers the reader’s choice. When false, publishes only the configured layout and ignores saved layout choices
blog_gallery , map , defaultsite block
Replaces the whole site gallery block. Omitted fields use built-in defaults; invalid fields warn and fall back. Reader choices for mode and size take precedence
blog_gallery.mode , wall / cards / seamless , defaultwall within a page block
Justified rows with 6px gaps, masonry with visible captions, or rows without gaps. Independent of the outer blog_index layout
blog_gallery.size , integer 160–360 , default240 within a page block
Target gallery tile size in CSS pixels; independent of the posts-per-page setting
share , string array or false , defaultsite params.ui.share (empty)
The page-end share targets. Replaces any inherited list. false opts this page out. See Share. An unknown target warns and is dropped
summary , string , default—
Fallback excerpt for gallery entries and post rows on tag and category pages. description takes precedence

Book

The guide is Books. A whole book sets type: book through a section cascade.

book_number , string , default—
Chapter number, shown before the page title and the sidebar entry
book_status , draft , default—
Marks a draft chapter: flagged in the sidebar and contents, and left out of the indexes by default
sidebar_headings , false / true / integer 2–4 , defaultsite value (false)
Expands the h2–h4 branch under the current sidebar entry. Out of range warns and falls back
book_draft_banner , boolean , defaultsite value (false)
Adds a banner at the top of a draft chapter. A non-boolean warns and falls back

Expo albums

OINK 1.3.0 uses type: expo for album pages. See Expo albums for the authoring guide.

expo , map , defaultsite params.ui.expo
Replaces the site block; absent fields use the built-in defaults below
expo.images , string , defaultimages/*
Pattern for image resources in the page bundle
expo.mode , wall / cards / seamless , defaultwall
Initial mode when the reader has no stored choice
expo.size , integer , default240
Target size from 160 to 360 CSS pixels; a stored reader size takes precedence

Image titles, captions, credits, weights, explicit IDs, and separate originals use native Hugo resources metadata. See Image metadata for the fields and an example.

Landing

The guide is Home and landing pages. Any page with layout: landing uses the landing shell.

landing , string , default—
Data is taken from data/landing/<key>/<language>.yaml
sections , array , default—
Section definitions inlined in front matter, taking precedence over landing. A non-array value warns. No sections render

Release pages

The guide is Releases and downloads. A section with layout: releases ignores weight and sorts by release date and SemVer, newest first.

release_url , string , default—
One GitHub release URL, https://github.com/<owner>/<repo>/releases/tag/<tag>. The theme extracts the owner, project and tag and generates source archive links. The date comes from the page’s date. Download assets come from the release body’s checksums block (see Releases). Anything else warns and the release block is skipped

4 - Blog posts

Set up a blog section. Learn directory conventions, post front matter, featured images, the date-ordered list page, and RSS.

Write a blog post’s body like a documentation page. The shell differs. A post has a date, author, tags, and featured image. The list uses date order, newest first. The section has an RSS feed. This page covers creating the blog section, a post’s front matter, featured images, list layouts, pagination and feeds.

The blog directory

A blog is a section under content/, and type: blog gives it the blog shell. Subdirectories divide it by publisher and audience, with posts sitting flat inside. Year directories are unnecessary: the list orders posts by their date.

this site's content/blog/

  • content/
    • blog/
      • _index.mdtype: blog + cascade
      • _index.zh.md
      • oink/engineering notes and announcements
        • _index.mdcascade: images: [/images/oink.webp]
        • oink-announcement.md
        • oink-announcement.zh.md
      • release/versioned release notes
        • _index.mdcascade: images: [/images/releasenote.webp]
        • 0.4.0.md
        • 0.4.0.zh.md

The section root applies the type to the whole subtree. It sets the section’s shared behavior:

content/blog/_index.md
---
title: Blog
description: OINK engineering notes and release announcements
type: blog
icon: fa-solid fa-blog
sidebar_root_for: self      # the blog has its own sidebar tree
cascade:
  type: blog
  feedback: false           # posts do not ask "was this page helpful?"
  comments: true            # but they do take comments
---

params.ui.blog_section (default blog) names where the blog root is. Rename the directory and either change that parameter or use sidebar_root_for: self as above.

Blog sections are expanded by default in the sidebar and ordered by date, newest first. To place one post at the top, give it a weight.

A post’s front matter

content/blog/release/0.4.0.md
---
title: Oink 0.4.0 — scenario components for a complete release workflow
linkTitle: Oink v0.4.0        # short name in the sidebar and pager
date: 2026-08-14              # publication date; decides list order
lastmod: 2026-08-14
description: >-
  Oink 0.4.0 delivers sequential reading and release surfaces, reusable landing
  pages, book publishing with stable references, and a keyboard-first site shell.
author: The OINK maintainers
categories: [Release]
tags: [Oink, Release]
---

Where it differs from a documentation page:

  • date is required. It decides the post’s place in the list and its RSS timestamp. A future date excludes the post from the default build. Use hugo server -F to preview it.
  • description appears as an introduction above the body and as a search snippet. Write a sentence for the reader.
  • author accepts inline Markdown, so [Vonng](https://vonng.com) works. For more than one author, a portrait, or a profile page, use the authors taxonomy below. The two do not interfere. A post renders author if authors is absent.
  • The date display format comes from params.time_format_blog and can be set per language (this site uses Monday, January 02, 2006 in English and 2006年1月2日 in Chinese).

Bilingual posts are stored in pairs, keeping date, author, weight and aliases identical across the two. Titles, descriptions and tags are translated. Do not translate commit IDs, version numbers, commands, or URLs.

Each row on a list or tag page has a thumbnail on the left. The resolver uses the first match in this order:

  1. images in the post’s front matter, first entry;
  2. An image resource in the page bundle whose filename matches featured or feature, then cover or thumbnail (it is cropped to a thumbnail, and the resource’s own byline becomes its caption);
  3. An images value inherited from an ancestor section’s cascade, nearest first.

A section-wide default uses Hugo’s native cascade over the whole subtree. This site sets one for each of its two subsections:

content/blog/release/_index.md
cascade:
  images: [/images/releasenote.webp]

To clear an inherited image on one post, write images: [] in its front matter. To clear it for a whole subsection, put it in that level’s cascade. This does not suppress an image supplied by the page bundle. To hide the image on the article itself, use featured_image: none. List thumbnails and share cards use images separately. The site-level params.images feeds the share card only and is never rendered as a list thumbnail.

On the article itself

By default the resolved image appears on list rows and in the social card. Set params.ui.featured_image to use the same image on the article itself:

Mode What the article shows
none No article image. This is the theme default
banner The image above the title in a fixed 16:9 figure. Articles use a consistent layout
wash A faint image behind the article header, fading before the body
hero A full-width image header
hugo.yml
params:
  ui:
    featured_image: banner

The page key is featured_image. A subsection’s cascade enables it for that tree. An individual post can opt out. A post without an image shows none in any mode. A section can therefore enable it even if only some posts have images. These modes need no additional script.

content/blog/release/_index.md
cascade:
  featured_image: wash

List layouts and pagination

After the section _index.md body, the theme appends the post index, sorted by date, newest first, without year groups. Choose its layout with blog_index:

Value Layout What the reader sees
list Horizontal entries (default) Thumbnail, title, date, subsection, tags, and a summary
cards Regular card grid A cropped 16:9 cover above the title, metadata, and summary
table Compact table Date, title, and tags in one row per article
gallery Image gallery Proportional covers with titles and descriptions; click to open the article

OINK v1.4.0 includes list, cards, table, and gallery.

Set the site default with params.ui.blog_index in hugo.yml, or set blog_index in a blog section’s _index.md front matter to override it. Use a section’s cascade to apply it to descendant sections. These settings control native blog section indexes; term and taxonomy pages keep their own layouts, and custom homepages need their own template integration.

List, card, and gallery views show 12 posts per page by default. Set the theme’s blog_index_size in hugo.yml to change it:

hugo.yml
params:
  ui:
    blog_index_size: 20

The same key in a blog section’s front matter overrides the site value. The theme explicitly passes this size to Hugo’s paginator. pagination.pagerSize does not control these lists.

The card form

params.ui.blog_index: cards renders the same list as a grid of content cards instead of rows. Each card shows a 16:9 image crop above the title, a date and subsection line, and a three-line summary.

hugo.yml
params:
  ui:
    blog_index: cards
    blog_index_columns: 3

The column count applies above the xl breakpoint. Between md and xl, the grid has two columns. Below md, it has one. If a card image resource supports processing, Hugo applies .Fill, so readers download cropped previews.

Table and layout switching

A standalone blog_index: table with blog_index_toggle: false lists the entire section without pagination. Set blog_index_toggle: true to add the layout switch beside the title. In OINK 1.4.0, it cycles through list → cards → table → gallery → list:

content/blog/_index.md
blog_index: cards
blog_index_toggle: true

All layouts preserve date order and manual_link destinations. With switching enabled, all four views show the same current page of posts, using blog_index_size. Only the standalone table shows the entire section. The switch remembers the reader’s choice. Set blog_index_toggle: false to publish only the configured layout, regardless of a saved reader preference. Hidden views use lazy images, although their markup and generated thumbnails still contribute to build work. In v1.4.0, the switch cycles through all four layouts.

gallery makes each article a linked cover, using the existing images field or bundled featured image. The default wall joins images into rows while preserving their proportions. Hover or keyboard focus reveals the title and description; touch devices show them below the image. Clicking opens the article. Posts without a cover keep a title tile.

content/blog/_index.md
blog_index: gallery
blog_index_toggle: true
blog_gallery:
  mode: wall
  size: 240

The gallery toolbar offers three arrangements:

blog_gallery.mode Arrangement Captions
wall (default) Justified rows with 6px gaps On hover or keyboard focus; below images on touch devices
seamless The same rows without gaps On hover or keyboard focus; below images on touch devices
cards Masonry columns Always visible below images

blog_index: cards selects the regular card grid. blog_index: gallery with blog_gallery.mode: cards selects masonry inside the gallery. blog_gallery.size sets the target tile size, from 160 to 360 CSS pixels, with a default of 240. It is independent of blog_index_size, the number of posts per page. Readers can change the arrangement and size; their choices are remembered separately from Expo albums.

Site defaults use the same blog_gallery block under params.ui; a page or cascade block replaces it in full. Omitted fields use wall and 240; invalid values warn and use those defaults. These settings are available in v1.4.0. See the site parameters and page parameters for the reference tables.

RSS

outputs determines which pages produce a feed. Adding RSS to section gives every section its own feed:

hugo.yml
outputs:
  home: [HTML, markdown, LLMS]
  page: [HTML, markdown]
  section: [HTML, RSS, print, markdown]

Setting outputs replaces all Hugo defaults. Include RSS explicitly if you need feeds. If you omit it, that page kind has no feed. The build does not warn.

This site therefore has /blog/index.xml (the whole blog) and /blog/release/index.xml (release notes only). A section feed recursively includes every subsection’s posts. Subscribing to /blog/ covers the whole blog. An individual post has no .xml of its own.

Each language has its own feed at that language’s route plus index.xml. The item limit is Hugo’s services.rss.limit. On the blog root and its first-level subsection pages, the first action button beside the title row is the RSS link, so readers do not need to construct the address manually.

To drop feeds site-wide, turn the kind off with disableKinds, which is more thorough than removing RSS from each page kind:

hugo.yml
disableKinds: [RSS]

Components use their static form in a feed. Disclosures are expanded, and interactive controls are removed. The four-output rules are the same for blog posts as for documentation.

Categories and tags

tags and categories are Hugo’s taxonomies, and the theme renders them as chips in the post header, a tag cloud in the right column, and a filter menu in the navbar. Enabling them, bilingual term labels, and switching them per content type are covered in Taxonomies.

Release notes

A versioned release announcement is an ordinary post, conventionally under blog/release/, with the version in linkTitle (Oink v0.4.0). For a download page with release cards, asset tables and checksums, see Releases and downloads.

Components in a post

Callouts, tabs, code blocks, images and tables work exactly as on a documentation page. The syntax is in Components. Headings in a post body take explicit English {#id} anchors too.

The four blocks at the end of a post — feedback, last modified, pager, comments — behave as on a documentation page. See Writing pages. A blog usually turns feedback off and keeps comments.

Authors and bylines

Declare the taxonomy to enable this feature. The theme adds no parameter:

hugo.yml
taxonomies:
  category: categories
  tag: tags
  author: authors

A post then names its authors in order:

authors: [vonng, ada-example]

The article header renders portraits and linked names in that order. List rows show the names. The blog feed includes each author alongside the site-level managingEditor.

An author’s profile is the taxonomy term page. No data/authors file is needed:

content/authors/vonng/_index.md
---
title: Vonng
description: Maintainer of OINK and Pigsty.
images: [portrait.webp]
---

The long introduction, rendered on the profile page under the name.

The display name is the term page’s link title. It uses linkTitle if available, otherwise title. A profile can use a full name and the byline a short handle. description gives a one-line introduction. The body gives the long introduction. The featured-image resolver selects the avatar. images: and a bundled portrait follow the same rules as an article’s image. A bilingual profile is an _index.zh.md beside it. An author without a profile page still has a byline. It shows the link title, an initial, and an archive link.

The 0.4 author: string is untouched wherever authors is absent, and neither form warns about the other.

Series

A series is a reading path through articles that each stand alone. Numbering, cross-references, and aggregate output belong to Book. A series has less structure. Declare the taxonomy to enable it:

hugo.yml
taxonomies:
  series: series

An article names the series and may place itself in it:

series: [shell-internals]
series_weight: 20

The article then shows a strip above its body. It names the series, position, and next part. A <details> contains the full list. This requires no JavaScript or bundle member. The term page content/series/<name>/_index.md is the introduction, and an _index.zh.md beside it makes the pair bilingual.

Members with series_weight come first in ascending order. Other members follow from oldest to newest. The content path breaks ties. The series strip and term page use this same reading order. For implementation details, see Authors and series.

A member of several series shows one strip, for the first term it names. A series of one shows none.

Neither authors nor series appears in the generic taxonomy chip row on an article, because each has a surface of its own. Name one in params.taxonomy.page_header to put it back.

Share

params.ui.share puts a share bar at the top of the page end. It is empty by default, so nothing renders until a site names its targets, in the order it wants them:

hugo.yml
params:
  ui:
    share: [x, bluesky, mastodon, reddit, hackernews, email, copy]

Sixteen targets are available: x, bluesky, mastodon, facebook, linkedin, reddit, hackernews, telegram, whatsapp, line, pinterest, weibo, chatgpt, claude, email, and copy. An unknown name warns and is dropped. Discord is deliberately absent. It provides no share-intent URL. Use copy for Discord. The theme does not infer a private scheme.

The page key is share, so a cascade scopes the bar to one tree, a page’s own list replaces the inherited one, and share: false opts a single page out:

content/blog/_index.md
cascade:
  share: [x, bluesky, email, copy]

Only regular pages render the bar. Lists, term pages, and the home page have no single item to share. Print, Markdown, and RSS omit the bar.

Share targets are links carrying the page’s permalink and title, plus a local copy button. The bar loads no third-party scripts or stylesheets. It contacts a target only when the reader clicks its link. See the Share contract for the implementation rules.

chatgpt and claude hand that same build-time permalink to an assistant with a prompt asking it to read the page. They are not the “open in ChatGPT” / “open in Claude” entries of the page action menu, which the runtime rewrites at activation time to the live browser URL and which therefore stay behind page_context_menu.assistant_links.

The copy button is the built-in copy_link action, so the Command Palette includes it on every page of every site. This applies even if no bar is configured.

Verify

hugo --printPathWarnings

The build must complete with Total in … and no ERROR. Then confirm:

  1. The post appears in the right date order at /blog/, with the date in the expected format.
  2. public/blog/index.xml exists, contains the post, and its links are complete absolute addresses.
  3. The thumbnail shows in the list (a missing one means none of the three featured-image sources matched).
  4. Tag chips lead to the corresponding tag page.

5 - Books

Turn a directory tree into a book with type: book: chapter numbering, numbered figures and tables, cross-references, generated indexes and whole-book print.

A book is a content tree with type: book. The directory determines chapter order. Front matter determines chapter numbers. Each figure, table, equation, and example has a manually assigned number and stable anchor. Cross-references resolve in all four outputs. The book root can generate whole-book print HTML.

Two settings are required. Enable attribute lines and passthrough in the site’s markup.goldmark (see Components). Keep book in params.ui.shell_types. The theme default includes it.

For a new book, start with the directory below. For an existing manuscript, see Migrating an existing manuscript.

A book’s directory

The book root is an ordinary Hugo section. Chapters are its subdirectories. Sections are pages inside each chapter. There is no second chapter list. The sidebar, pager, and generated contents all read this tree.

content/handbook/, one book

  • content/handbook/
    • _index.mdbook home: type: book + cascade, holding book-toc and the indexes
    • ch01/
      • _index.mdchapter 1 front page: book_number: 1
      • install.mdsection 1.x
      • bootstrap.md
    • ch02/
      • _index.mdchapter 2: numbered with book_number, optionally marked draft
      • replication.md
      • failover.md
    • appendix.mdan unnumbered appendix, still in the sidebar and the reading order

Assign chapter numbers manually. book_number displays exactly what you write. The theme never numbers chapters by directory order. The num on a figure, table, equation, or example also uses an author-controlled string. 2-1, 5.3, and A-2 are valid. Rendering does not compute an index. Rearranging the tree never changes a number that has already been printed.

The book home and chapter pages

The book root declares the type, cascades it to descendants, and explicitly requests the print output. That aggregate is expensive to build, so the theme does not turn it on for a consuming site:

content/handbook/_index.md
---
title: The PostgreSQL operations handbook
type: book
book_number: B
cascade:
  type: book
outputs: [HTML, print, markdown]
---

A book section uses Hugo’s section output kind. home applies only when the book sits at the site root:

hugo.yml
outputs:
  section: [HTML, print, markdown]
params:
  ui:
    sidebar_headings: false # default; use 3 to add h2–h3 below the current entry
    book_draft_banner: true # draft chapters get a localized banner above the body

A chapter page needs only its number and its order:

content/handbook/ch02/_index.md
---
title: Replication and failover
book_number: 2
book_status: draft
weight: 20
---

book_number appears before the page title, in the sidebar and in the generated contents. book_status: draft is a visible editorial label and does not change Hugo’s publication state. A draft chapter builds and publishes as usual.

sidebar_headings defaults to false and accepts true (h2 only) or a maximum level from 2 to 4. A page or section cascade can override the site setting. The right outline remains available when this left branch is disabled. Give every heading that will be referenced an explicit ID, such as ## Synchronous replication {#sync-replication}. A generated slug works for navigation. Do not use it as a long-term reference target.

The full key definitions are in Configuration and Page parameters.

Numbering: the native form

Each of the four numbered kinds has a native form. Put an attribute line immediately after one Markdown block. Use num= for the number, #id for the anchor, and caption= for a plain-text caption.

Figures

An attribute line follows the image block. Omitting #id defaults it to fig-<num>.

Source
![The OINK release notes page](/images/releasenote.webp)
{#book-release-note num="2-1" caption="The release notes page is also the single source of release facts." width=600 height=300}
The OINK release notes page
Figure 2-1 The release notes page is also the single source of release facts.

The native figure form requires the site to set markup.goldmark.parser.wrapStandAloneImageWithinParagraph: false. Otherwise, the attribute line attaches to the paragraph and is ignored. The alternative text comes from the Markdown image itself and is never replaced by the caption.

Tables

An attribute line follows a pipe table, and the default ID is tbl-<num>.

Source
| Isolation level | Dirty read | Non-repeatable read | Phantom read |
| --- | --- | --- | --- |
| Read Committed | Not possible | Possible | Possible |
| Repeatable Read | Not possible | Not possible | Possible |
| Serializable | Not possible | Not possible | Not possible |
{#tbl-2-1 num="2-1" caption="Anomalies permitted at each PostgreSQL isolation level."}
Isolation level Dirty read Non-repeatable read Phantom read
Read Committed Not possible Possible Possible
Repeatable Read Not possible Not possible Possible
Serializable Not possible Not possible Not possible
Table 2-1 Anomalies permitted at each PostgreSQL isolation level.

Equations

An attribute line follows a $$ block, and the default ID is eq-<num>. The number and caption sit to the right of the formula on wider screens. On narrow screens, they move below it and wrap. A wide formula can scroll horizontally. Short captions keep the equation easy to scan.

Source
$$
A = \frac{\mathrm{MTBF}}{\mathrm{MTBF} + \mathrm{MTTR}}
$$
{#eq-2-1 num="2-1" caption="Availability from MTBF and MTTR."}
A=MTBFMTBF+MTTR A = \frac{\mathrm{MTBF}}{\mathrm{MTBF} + \mathrm{MTTR}}
Equation 2-1 Availability from MTBF and MTTR.

The native form depends on the site enabling Goldmark passthrough. Without it, use the eq shortcode below, which goes through local server-side KaTeX.

Examples

A code fence with num= and caption= is a numbered example, and the default ID is eg-<num>. An #id on the fence names the enclosing <figure>, which is the reference target. The caption is required: a caption without a number is ignored, and a number without a caption is dropped with a warning. A numbered example renders in one frame where the caption forms the header and the body sits inside; a single code block shares the frame border without adding a second border.

Source
```sql {num="2-1" caption="Daily write volume on the primary." #eg-2-1}
SELECT date_trunc('day', ts) AS day, count(*)
FROM pg_stat_statements_history
GROUP BY 1 ORDER BY 1 DESC LIMIT 7;
```
Example 2-1 Daily write volume on the primary.
SELECT date_trunc('day', ts) AS day, count(*)
FROM pg_stat_statements_history
GROUP BY 1 ORDER BY 1 DESC LIMIT 7;

Numbering: the shortcode form

The four shortcodes fig, tbl, eq and eg render a <figure> identical to the native form, register into the same target table, and sort by source position. Use them when the native form is insufficient. Examples include figures with several images or other Markdown, several tables under one number, sites without passthrough, and examples with several fences and prose. A single numbered image can use link in its native attribute line. It does not need fig just for an outbound link.

fig takes src= (it also accepts inner Markdown content, and the two are mutually exclusive) and additionally supports link, alt, width, height, class, and the migration alias title:

Source
{{< fig num="2-2" src="/images/docsy.webp" alt="The default Docsy shell"
    caption="OINK's upstream: the Docsy content model is still underneath." width="600" height="300" />}}
The default Docsy shell
Figure 2-2 OINK's upstream: the Docsy content model is still underneath.

tbl wraps the label, the table, the caption and the anchor in one semantic figure:

Source
{{< tbl num="2-2" caption="How a numbered component appears in each of the four outputs." >}}
| Output | Label | Anchor |
| --- | --- | --- |
| HTML | Visible | Stable |
| Print | Visible | Stable |
{{< /tbl >}}
Output Label Anchor
HTML Visible Stable
Print Visible Stable
Table 2-2 How a numbered component appears in each of the four outputs.

eq hands its content to local server-side KaTeX, so it does not depend on passthrough:

Source
{{< eq num="2-2" caption="Connection pool saturation." >}}U = \frac{\lambda}{\mu \cdot c}{{< /eq >}}
U=λμ⋅cU = \frac{\lambda}{\mu \cdot c}
Equation 2-2 Connection pool saturation.

Use a bare {{< eq >}} without parameters for unnumbered display math. It registers no target. xref cannot reference it. It does not appear in the equation index.

eg is a wrapping shortcode whose body renders under the page’s Markdown policy, usually holding one or more fences:

Source
{{< eg num="2-2" caption="Bringing up a new replica with pg_basebackup." >}}
```bash
pg_basebackup -h primary -U replicator -D /pg/data -Fp -Xs -P -R
```
{{< /eg >}}
Example 2-2 Bringing up a new replica with pg_basebackup.
pg_basebackup -h primary -U replicator -D /pg/data -Fp -Xs -P -R

IDs must be unique within a page, and within one kind a number maps to a single ID. A duplicate logs a warning with the first registration’s line number and keeps the first registration.

Footnotes cannot appear in a shortcode body

Hugo renders each shortcode body as a separate Goldmark document, whereas footnotes belong to the page. A [^label] inside the body of tbl, eg, fig, card, tab, field, or include logs a warning naming the file, line, and label: if the definition sits on the page, the reference would print literally as [^label]; if the definition sits inside the shortcode body, it would generate a second footnote list whose fn:N IDs collide with the page’s own footnotes.

If a table or code block needs footnotes, use the native form. A table, image, or fence with {num=… caption=…} keeps its content in the page document. Its footnotes then use normal numbering, links, and backlinks. The rendered figure is the same either way, so this is usually a one-line change. Text that resembles a footnote in code remains unchanged. This includes a [^0-9] character class in a listing or a code span.

Cross-references

A target on the same page can be reached with a plain Markdown link: Table 2-1 points at the isolation table above. You must write the label and number manually. If you change a number, you must find its references yourself.

xref combines the label, number, and anchor. It works across pages and languages:

Source
See {{< xref fig="2-2" />}} and {{< xref eg="2-1" />}};
with an explicit anchor: {{< xref fig="2-1" anchor="book-release-note" />}}.

See Figure 2-2 and Example 2-1; with an explicit anchor: Figure 2-1.

The rules:

  • At most one kind key (fig, tbl, eq, eg). The kind supplies the localized label (Figure / Table / Equation / Example) and derives the default anchor <kind>-<num>.
  • anchor= overrides the derived anchor, for a target that wrote an explicit #id.
  • page= references another page through Hugo’s page lookup in the current language, so the source never hard-codes a /zh/ prefix.
  • Without a kind, both anchor= and inner link text are required: {{< xref page="../ch01/install" anchor="sync-replication" >}}synchronous replication{{< /xref >}}.
  • A reference may precede its target. Nothing reads the registry at render time. Forward references are valid.

A plain cross-page Markdown link is still a site URL inside the whole-book print. A reference that must also jump within the aggregate document is written as an xref.

Indexes: contents and lists of figures

Five index shortcodes walk the same book tree, triggering descendant content and aggregating what it registered. They usually sit on the book home (_index.md) or on a dedicated “list of figures” page.

content/handbook/_index.md
{{< book-toc depth=3 >}}

## List of figures {#lof}
{{< book-figures >}}

## List of tables {#lot}
{{< book-tables >}}

## List of equations {#loe}
{{< book-equations >}}

## List of examples {#lox}
{{< book-examples >}}

These five appear here only as source. They start at the current page’s navigation root and process its descendants. In an ordinary documentation tree, one would list the whole docs tree as a book. For the real effect, read Write Beautiful Docs and inspect its content/book/_index.md source.

  • book-toc takes a depth of 1 to 3: 1 lists chapters, 2 adds nested sections, 3 also projects each page’s heading tree. drafts=false filters book_status: draft rows out of this generated list only, and does not affect publication.
  • book-figures, book-tables, book-equations and book-examples take no parameters. Each lists one kind, with entries like “Figure 2-1 — caption” linked to the stable ID.
  • In whole-book print, all of these links become in-document fragments.

Sequential reading and drafts

The pager is on by default for docs, book, and blog. It uses a pre-order walk of the sidebar tree. The section index comes first, followed by its children in weight order. Turn a whole type off with params.ui.pager_types, and a single page off with pager: false.

hugo.yml
params:
  ui:
    pager_types: [docs, book]

Entries hidden with toc_hide, manual_link link-only placeholders and sidebar_divider rows never become pager destinations.

Besides the “draft” label in the sidebar, a draft chapter can carry a banner above its body:

hugo.yml
params:
  ui:
    book_draft_banner: true

The banner appears only on pages that are both type: book and book_status: draft, and its wording comes from the localization key book_draft_notice.

Printing the whole book

Once the book root has the print output, it generates a cover, a local table of contents, the root page’s body and every descendant chapter in visible reading order, all inside one HTML document. Pages with no_print: true, link-only nodes, divider rows and hidden placeholders never become chapters.

Inside the aggregate, the IDs of numbered components are preserved byte for byte. Markdown heading and footnote IDs within a page are prefixed with their source page to avoid collisions when several chapters share an anchor such as summary or start with fn:1. Generated links are rewritten to match. A page rendered alone as Print keeps the same page-local IDs as ordinary HTML. Only a multi-page section or whole-Book aggregate adds the namespace.

The output is print-oriented HTML. An opt-in BookManifest output records that same reading order as JSON, and the theme ships bin/book-epub.py and bin/book-pdf.py, which turn the manifest and the print HTML into EPUB and PDF.

The switches themselves, and per-chapter print, are covered in Print.

Migrating an existing manuscript

An existing manuscript usually expresses figure and table numbering with the site’s own figure shortcode, bold pseudo-captions, and bare links to #fig_*. The theme repository ships a migration script that rewrites those legacy forms into fig, tbl and xref while preserving the public anchors already published. Pin the site to a released OINK version that includes the Book components first, then migrate the content.

Dry run: diff and report only, no files changed
python3 ~/pgsty/oink/bin/migrations/book_figures.py \
  --profile tpme \
  --root /path/to/your-book \
  --report /tmp/book-migrate.json > /tmp/book-migrate.diff

Four profiles cover the legacy conventions of three real manuscripts (DDIA contributes one each for v1 and v2), and each recognizes only the forms actually observed in them:

--profile Legacy form it recognizes
tpme A pseudo-h6 caption beside an image, a caption beside a table, and bare /en/...#fragment links
ddia-v2 The site’s own figure shortcode, classified by number into figure / table / code example
ddia-v1 A bare image with an adjacent bold numbered caption, with the ID derived from the image filename
pg-internal A bold or italic “Figure N” caption in Chinese or English next to an image, and a numbered table caption next to a table
--profile
Required; one of the four values above
--root
Required; the consuming repository’s root
--path
Restricts to a file or directory under --root; repeatable. The default scans the whole content tree
--write
Applies the rewrite. The default is a dry run that writes nothing
--no-diff
Suppresses the diff while keeping the summary and the report
--report
Writes the machine-readable JSON report

The diff goes to standard output, the summary to standard error, and the report carries files_scanned, files_changed, counts, skipped and idempotent. The script rewrites only targets it can identify uniquely. If the number is unclear, the caption is not unique, or the marker form is unrecognized, it preserves the text. It records the item in skipped for human review. Bold text, inline code and formulas inside a legacy caption degrade to plain text, because a Book caption is plain text by contract.

After reviewing the diff, apply it on a dedicated branch and run a second pass to confirm idempotency:

Apply, then verify idempotency
python3 ~/pgsty/oink/bin/migrations/book_figures.py \
  --profile tpme --root /path/to/your-book --write \
  --report /tmp/book-migrate-written.json

python3 ~/pgsty/oink/bin/migrations/book_figures.py \
  --profile tpme --root /path/to/your-book --no-diff \
  --report /tmp/book-migrate-second.json

The second report should show files_changed: 0, empty counts, and idempotent: true. The script signals idempotency with exit code 0.

The profiles recognize only the legacy forms actually observed in those three manuscripts. Where a manuscript’s conventions fall outside the four, the script does not apply and the rewrite is manual, following Numbering: the native form. The theme repository’s bin/check-book-migrations.py covers all four profiles with a dry-run and an idempotency check.

Verify

  1. Build with visible diagnostics: hugo --printPathWarnings. A malformed number, a duplicate ID and a missing caption all produce warnings that need review.
  2. The page should show a localized label such as “Figure 2-1”, clickable xref links, and anchors that land correctly.
  3. Compare the chapter order across all four places: sidebar, pager, book-toc and whole-book print.
  4. Check the Markdown output: curl -s http://localhost:1313/handbook/ch02/index.md. The shortcode form should degrade to **Figure 2-2.** caption plus the original body, and the native form should keep its source block and attribute line as they are.
  5. Run the anchor check from the theme repository against the build output:
python3 ~/pgsty/oink/bin/check-book.py --site-public public

It verifies that every reference’s target anchor exists, that kind and number agree, that page-local IDs are unique, and that a numbered image has alternative text appropriate for its caption.

Book shortcode parameters

num , string , default—
Required (except for the bare eq form). Matches [0-9A-Za-z.-]+ and must be quoted
id , string , defaultfig-<num> / tbl-<num> / eq-<num> / eg-<num>
Matches [A-Za-z][A-Za-z0-9_.:-]* and is preserved byte for byte
caption , plain text , defaultempty
Required for eg. Optional for fig, tbl, and eq. Not Markdown
class , class token , default—
Appended to the <figure>. Requires num
src , image path , default—
fig only. Mutually exclusive with inner content, and follows the shared image resolution order
link alt width height , — , default—
fig only. Width and height are positive integers
title , plain text , default—
fig only. A migration alias for caption, mutually exclusive with it

xref:

fig tbl eq eg , number string , default—
At most one. Supplies the localized label and derives the anchor
anchor , ID , defaultderived from kind and number
Required when no kind is given, together with inner link text
page , page reference , defaultcurrent page
Resolved through page lookup in the current language. A missing page warns and renders text without a link

book-toc:

depth , integer 1–3 , default2
1 chapters / 2 with nested sections / 3 with the heading tree
drafts , boolean , defaulttrue
false filters draft chapters out of the generated list

book-figures, book-tables, book-equations and book-examples take no parameters.

Limits

  • There is no automatic numbering. Assign chapter, figure, and table numbers manually. Only an explicit edit changes a number. A build does not change it.
  • The attribute line must touch its block, with no blank line between. If a tool such as Prettier moves an attribute line, it fails silently. The figure becomes a plain image.
  • book_kind and book_part are metadata keys the contract acknowledges but the current templates do not render. The ones with a visible effect are book_number and book_status.
  • The index shortcodes trigger descendant content rendering, which noticeably lengthens the build on a very large tree. The same reason is why whole-book print has to be requested explicitly.
  • A footnote reference cannot appear inside a shortcode body; the theme logs a warning and points to the native form instead (see Numbering: the shortcode form).
  • Packaging requires explicit selection and runs outside the build. BookManifest plus bin/book-epub.py / bin/book-pdf.py produce EPUB and PDF. Hugo alone emits neither file. Typeset pagination, font embedding, and index compilation remain outside the contract.
  • Organizing content — how the tree becomes the sidebar and the reading order
  • Images — captions, sizing, zoom and image processing
  • Tables — table attribute lines and full-width tables
  • Math — KaTeX and passthrough configuration
  • Print — per-chapter and whole-book print

6 - Image albums with Expo

Create an image album, add optional metadata, select a layout, and use the image viewer.

Expo displays image collections as albums. A sidebar groups the albums. The main area shows the images in the selected album. Each image opens in a viewer.

Available in OINK 1.3.0

Expo is included in OINK v1.3.0.

Open the example albums to try the controls. Use the Gallery component for an image grid inside a text page.

Create an album

Use one directory for each album. Put the images in that directory’s images/ folder. One index.md describes the album. Filenames supply the default image titles. Expo does not require a Markdown or YAML file for each image.

content/photos/
├── _index.md
├── nature/
│   ├── _index.md
│   └── field-notes/
│       ├── index.md
│       └── images/
│           ├── 01-fern.jpg
│           └── 02-river.gif
└── buildings/
    ├── index.md
    └── images/
        └── arch.jpg
  1. Create the section entry:

    content/photos/_index.md
    ---
    title: Photo albums
    type: expo
    cascade:
      type: expo
    ---
  2. Create a topic entry for each group of albums:

    content/photos/nature/_index.md
    ---
    title: Nature
    weight: 10
    ---
  3. Create the album page:

    content/photos/nature/field-notes/index.md
    ---
    title: Field notes
    description: Plants and water from a field visit.
    weight: 10
    ---
    
    Photographs from the north trail.
  4. Put the images in the album’s images/ folder.

The section lists its child topics and albums. The sidebar follows the same content tree. On narrow screens, open the navigation drawer to select an album. The album body is optional. If supplied, it appears above the images.

Split large collections into separate albums. Expo has no automatic image pagination. A section card uses the first sorted image as its cover. A topic without images uses the first available image from its descendant albums. The cover fills a 4:3 frame and can crop the preview.

Add image metadata

Add a resources entry to the album front matter when an image needs a title, description, credit, or fixed position. The src path is relative to the album directory.

Album front matter
resources:
  - src: images/01-fern.jpg
    title: Fern
    params:
      id: fern
      alt: A green fern frond seen from above
      caption: Branching leaves beside the north trail.
      byline: Alex Chen
      weight: 10
Field Use
title Image title. If omitted, Expo derives a title from the filename
params.alt Text that describes the image. If omitted or empty, it uses the title
params.caption Plain-text description
params.byline Plain-text credit
params.weight Numeric image order. Lower values come first. The default is 0
params.id Stable image ID within the album
params.original Optional path to another image in the same album bundle

Images with equal weights keep the resource name order. To set a complete order, give each image a weight. Images without a weight come before positive weights.

Use ASCII letters or digits for the first ID character. The remaining characters can also include _ and -. Keep IDs unique within an album. The example creates /photos/nature/field-notes/#img-fern. This link stays valid after a filename change if the album URL and explicit ID stay the same. Without an explicit ID, Expo uses a filename hash. Renaming that file changes the link.

To use a separate original, put it in originals/ and set params.original: originals/fern.jpg. Keep the preview and original at the same aspect ratio. Keep originals outside the expo.images pattern to avoid duplicate entries. Expo reads bundled images; it does not fetch remote files for an album.

Set the defaults

Set site defaults in hugo.yml:

hugo.yml
params:
  ui:
    expo:
      images: images/*
      mode: wall
      size: 240
Key Allowed value Built-in default
images A pattern for image resources in the album bundle images/*
mode wall, cards, or seamless wall
size An integer from 160 to 360, in CSS pixels 240

Use a top-level expo block in album front matter to replace the site block:

Album front matter
expo:
  images: images/*
  mode: cards
  size: 280

This override replaces the whole block. Omitted fields use built-in defaults, not values from the site block. A section can supply the block through cascade. The size is a layout target, not a fixed width and height for every image.

The browser saves the reader’s layout and size choices for the same site origin. These choices take precedence over author defaults. They remain in use after a reload, an album change, or an appearance change. If browser storage is unavailable, Expo uses the author defaults when the page loads.

Select a layout

Mode Display
wall Rows of image tiles with 6 CSS pixels between them
cards Columns of cards with visible titles, descriptions, and credits
seamless Rows of image tiles with no gaps between them

The toolbar has three layout icons, a play/pause button, and an image-size slider. On devices with a mouse, Wall and Seamless show captions on hover or keyboard focus. Images with extreme proportions can have space inside their tiles. The album tiles contain the whole image.

GIFs play by default. Select Pause to show still previews. If the system requests reduced motion, Expo starts with still previews. Select Play to start them. The play button is disabled when the album has no GIFs. Images load as they approach the visible area; large GIF files still require their full transfer size.

Use the image viewer

Select an image to open the viewer. A small image starts at its original size. A large image shrinks until both dimensions fit the available image area.

Control Action
Reset Restore the initial size and center the image
Expand to fit Enlarge or shrink the image until its limiting edge fits the image area
Zoom out / Zoom in Divide or multiply the current scale by 1.25
Open original Open the original image file in a new tab
Locate in album Close the viewer and move to this image in the album
Previous / Next Show the adjacent image in the same album
Close Close the viewer and restore focus to an image link

Expand to fit keeps the whole image visible. It does not switch the browser to fullscreen. Manual zoom can make the image larger than the viewing area. Hold the left mouse button and drag to move the enlarged image. Movement stops at the image bounds. On a touch screen, an enlarged image uses native scrolling. When the image fits, swipe horizontally with one finger to change images; pinching keeps native browser behavior. Double-click alternates between the initial fit and a closer view: a reduced image opens at 100% under the pointer, while an image already at its original size expands to fit.

Changing images resets the scale and position. Previous and Next stop at the ends of the album. The percentage uses CSS pixels: at 100%, one source pixel occupies one CSS pixel.

Use keyboard shortcuts

These shortcuts work while the viewer is open. They take precedence over the page’s single-key navigation. They do not handle text input, input method composition, or Ctrl/Command/Alt combinations.

Key Action
W / A / S / D Move the enlarged image up / left / down / right
Q or H Previous image
E or L Next image
J or − Zoom out
K or + Zoom in
R or 0 Reset the size and position
F Expand to fit
Escape Close the viewer

WASD moves the image by 80 CSS pixels per press, only along an axis that overflows. Left and Right arrow keys change images when horizontal scrolling is unnecessary. When the image is wider than the viewing area, the arrows retain native scrolling. The keyboard_nav setting controls page shortcuts; it does not disable the viewer controls.

Use the site appearance

Expo uses Paper, Slate, Ink, and Terminal with the site’s light or dark mode. Select these options in the shared navigation. The album body has its image toolbar and no article action menu.

To expose all four presets and keep the top navbar visible, use:

hugo.yml
params:
  ui:
    preset: paper
    preset_menu: [paper, slate, ink, terminal]
    navbar_enabled: true
    navbar_autohide: false

Expo uses the full available page width by default and has no right-hand outline. Set page_width in page front matter if the album needs a narrower body. If your site overrides params.ui.shell_types, include expo to retain its sidebar.

Translate and export an album

Add index.zh.md beside index.md for a Chinese album. Add _index.zh.md for each translated section. Both languages can share the image files. Translate the title, description, and resource metadata in each page. Keep image IDs the same when they refer to the same image.

HTML works without JavaScript: image links open the original files, and captions remain visible. When enabled, Print uses still previews. Markdown and LLMSFULL include image links and metadata. RSS includes static image descriptions. See Print and Agent outputs for output configuration.

Check an album

  1. Run hugo --printPathWarnings with a theme version that includes Expo.
  2. Open each album and confirm its image order, titles, and descriptions.
  3. Test a small image, a wide image, a long image, and a GIF if the album has one.
  4. Test Reset, Expand to fit, zoom, dragging, keyboard navigation, and Locate in album.
  5. Check both languages, narrow screens, the four presets, and light/dark mode.

If an album is empty, check its type, bundle structure, and expo.images pattern. If a default seems to have no effect, check the stored reader choice and the whole-block override rule. For required behavior and maintainer checks, see the Expo contract and design decision.

7 - Releases and downloads

Record versions, tags, archive links, checksums, and install commands locally. Release cards, asset tables, download blocks, and index pages use these records.

OINK stores release metadata in two local places: a page’s front matter release_url identifies its GitHub release, and data/download/<key>.yaml records installation instructions. Release cards, asset tables, download blocks, and index pages derive their links from those records without contacting GitHub at build time.

This page carries demonstration release facts

Its front matter holds a release_url (OINK v0.4.0), and the card, asset table and download block below are really rendered. The checksums and asset filenames are fabricated. The URLs are derived locally from the repository and tag. Their target files do not exist in any real release. Do not use these hashes to verify anything.

Components and where the facts come from

What you want What renders it Facts come from
A version summary card (tag, date, archives, repo) release-card The page’s release_url
A checksum asset table The checksums fence / release-assets sha*sum lines in the body
A multi-channel download block download data/download/<key>.yaml
A chronological release index layout: releases Each page’s release_url, or its title

The page owns the release facts

One front matter key contains the release record. It is the GitHub release URL for an exact tag:

content/blog/release/0.4.0.md
release_url: https://github.com/pgsty/oink/releases/tag/v0.4.0

The URL supplies the owner, project, and tag. The page’s date supplies the date. An invalid exact-tag GitHub release URL warns and skips the release block. The 0.5 release map (product / version / repo / tag / date / prev / checksums) and its string shorthand are removed. A page that still uses either gets a warning that names release_url.

Put a parameterless shortcode where you want the summary. The call accepts no release facts:

Source
{{< release-card >}}

The card shows four locally derived links: the release, both source archives, and the repository. Checksum files belong in the asset table below a note, and comparisons live on GitHub.

The release index page

A section can switch to the release index layout. It lists every regular page in the section, newest first by page date. Within one day, the tag’s version breaks ties. It uses SemVer precedence with a deterministic fallback for non-SemVer tags:

content/blog/release/_index.md
---
title: Releases
layout: releases
---

If release_url parses, the entry shows project tag, such as oink v0.4.0, above the page description. A page without that URL keeps its own title. A plain note between releases is therefore an ordinary entry and causes no warning. The 0.5 release_products filter and release_group_by_product grouping are gone; Using either warns.

This site’s Releases currently uses the ordinary blog list. Switch to layout: releases when a strict chronology is wanted.

Checksum assets

The checksums fence is the native form of a checksum table, holding the verbatim output of a sha*sum command:

Source
```checksums
1e2f4c8a9d05b7361f8ac25d0e7b4913a6c8df215047eb9c3a1d6b8250f9e7c4  oink-0.4.0-linux-amd64.tar.gz
7b3d9e0c145a8f26d0b7e93c48156aa2f0d9c7b31e846a5029df1b6c7a3e8250 *oink-0.4.0-darwin-arm64.tar.gz
```
Download asset
FileChecksum
oink-0.4.0-linux-amd64.tar.gz Linuxamd64SHA-256 1e2f4c8a9d05b7361f8ac25d0e7b4913a6c8df215047eb9c3a1d6b8250f9e7c4
oink-0.4.0-darwin-arm64.tar.gz macOSarm64SHA-256 7b3d9e0c145a8f26d0b7e93c48156aa2f0d9c7b31e846a5029df1b6c7a3e8250

Only two line shapes are accepted: <hex><two spaces><filename> and <hex><space>*<filename>. Blank lines and lines starting with # are ignored. The hash length determines the algorithm (MD5 / SHA-1 / SHA-256 / SHA-512), and each block holds a single algorithm. Malformed lines log a warning with the line number and are skipped. Each filename must be a single path segment; package type, OS, and architecture badges are inferred from the filename when recognized.

If the page has release_url front matter, the base for asset links is derived as https://github.com/<repo>/releases/download/<tag>/. A page without release facts must set base= explicitly. Having both is an error.

a page with no release front matter
```checksums {base="https://repo.pigsty.io/oink/v0.4.0/" algo="sha256"}
1e2f4c8a9d05b7361f8ac25d0e7b4913a6c8df215047eb9c3a1d6b8250f9e7c4  oink-0.4.0-linux-amd64.tar.gz
```

release-assets is the shortcode form of the same parser and renderer. It adds one parameter that the fence lacks, src=. Use it for a checksum file stored as a page resource or global asset. src and inner content are mutually exclusive. group="auto" groups by platform and architecture:

Source
{{< release-assets group="auto" >}}
5a0c7d1e93b4826f0ad35c9e17b6402d8f1c95ae63d70b28c4e19a5f38207db6  oink-0.4.0-1.el9.x86_64.rpm
c93f16a8d052b7e41ac68d3907b25fe0a41d8c7362b95e0187ac4d63f9520ea8  oink-0.4.0-1.el9.aarch64.rpm
{{< /release-assets >}}

.rpm

Download asset
FileChecksum
oink-0.4.0-1.el9.x86_64.rpm Linuxamd64SHA-256 5a0c7d1e93b4826f0ad35c9e17b6402d8f1c95ae63d70b28c4e19a5f38207db6
oink-0.4.0-1.el9.aarch64.rpm Linuxarm64SHA-256 c93f16a8d052b7e41ac68d3907b25fe0a41d8c7362b95e0187ac4d63f9520ea8

HTML shows a truncated hash. The accessible name and copied text retain the full value. The copy button uses a local runtime loaded on demand. With JavaScript disabled it is still a complete linked table. Print expands the full hash without controls, and Markdown and RSS emit a pipe table of full hashes.

Download channel data

Installation instructions belong to the product rather than one release. Store them in data/download/<key>.yaml. This site’s real record is data/download/prd5.yaml:

data/download/prd5.yaml
version: 0.4.0
repo: pgsty/oink
published: true
channels:
  - id: script
    kind: rolling
    title: Install script
    title_zh: 安装脚本
    icon: fa-solid fa-bolt
    note: The rolling channel deliberately contains no version interpolation.
    note_zh: 滚动渠道刻意不插入版本号。
    steps:
      - title: Install
        title_zh: 安装
        code: curl -fsSL https://repo.example.org/oink/install | bash
        lang: bash
  - id: source
    kind: pinned
    title: Source archive
    title_zh: 源码归档
    icon: fa-solid fa-code-branch
    url: https://github.com/pgsty/oink/archive/refs/tags/${tag}.tar.gz
    steps:
      - title: Clone the tag
        title_zh: 克隆标签
        code: git clone --branch ${tag} https://github.com/pgsty/oink.git
        lang: bash
  - id: assets
    kind: pinned
    title: Release assets
    title_zh: 发布资产
    icon: fa-solid fa-box-open
    checksums: |
      aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa  oink-0.4.0.tar.gz

The record has five top-level fields: version, repo, tag, published, and channels (any unknown top-level key logs a warning and skips the record). version may be omitted here and supplied by the site’s params.version instead.

version , string , defaultsite params.version
Missing in both places warns and skips the block
repo , owner/name , default—
Required once a pinned channel has a link or assets
tag , string , defaultv{version}
URL-safe characters only
published , boolean , defaulttrue
false means the immutable release does not exist yet
channels , array , default—
Must be non-empty

Each channel:

id , ^[a-z][a-z0-9-]*$ , default—
Unique within the record. Used as the anchor
kind , rolling | pinned , default—
Decides whether release facts may be interpolated
title , localized string , default—
Must resolve to a non-empty value
note , localized string , default—
One line of explanation under the channel
icon , Font Awesome class pair , default—
For example fa-solid fa-bolt
url , http(s) or a site path , default—
Interpolatable on pinned only
steps[] , title / code / lang , defaultlang: text
Code steps go through OINK’s enhanced code renderer
checksums , sha*sum text , default—
pinned only. Mutually exclusive with checksums_src
checksums_src , asset path , default—
Reads the checksum file as a Hugo asset

Two rules:

  • Localization resolves by suffix: <field>_<exact language> → <field>_<base language> → <field>. A Chinese site resolves title_zh_cn, then title_zh, then title. camelCase aliases are not accepted.
  • Only a pinned channel’s url and steps[].code interpolate ${version} and ${tag}. A rolling channel refuses interpolation, so a stable install command is never bound to one version. Titles and notes never interpolate.

Rendering the download block

download takes exactly one positional parameter, the data key:

Source
{{< download "prd5" >}}

Install script

The rolling channel deliberately contains no version interpolation.

Install
curl -fsSL https://repo.example.org/oink/install | bash

Source archive

Source archive
Clone the tag
git clone --branch v0.4.0 https://github.com/pgsty/oink.git

Release assets

Download asset
FileChecksum
oink-0.4.0.tar.gz SHA-256 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

HTML renders a row of anchor chips and one section per channel. Code steps reuse the enhanced code block and its on-demand copy runtime. A checksum channel reuses the asset table above. Print statically expands the same content, Markdown emits the titles, source fences and full hashes, and RSS omits the component.

Before you create the tag and upload assets, mark the record unpublished:

data/download/<key>.yaml
published: false

Rolling channels keep working. Pinned channels become an unclickable “pending release” state, omit the pinned commands, and disable asset links and copy controls. After the tag and assets resolve, change the publication state. Do not write a guessed link in the prose.

The same record can supply a landing page’s download section. No second version model is required. See Home and landing pages.

How this relates to blog release notes

The two have different jobs:

  • A release note in the blog (this site keeps them in content/blog/release/) explains what changed, how to upgrade, and what breaks. Its front matter carries release_url, and a release-card can sit at the top. For writing instructions, see Blog posts.
  • Download data identifies the channel, command, and hash. It is separate from the version number. An upgrade changes one place.

For a release, follow this order: update version in data/download/<key>.yaml → write a new content/blog/release/<version>.md with its release_url → set published to true after the tag and assets are in place.

Verify

  1. Build with visible diagnostics: hugo --printPathWarnings. A malformed hash line, mixed algorithms, a missing base and a misspelled channel field all produce warnings that need review.
  2. On the page: the card’s tag and date match the repository, and every asset row opens a real download URL.
  3. Check hashes against the actual artifacts manually. The component only displays them. It verifies nothing.
  4. Confirm the hashes are complete in non-HTML output:
curl -s http://localhost:1313/docs/write/releases/index.md | grep -c '^| '
  1. Test with published: false first. Set it to true only after the tag and assets exist. Test each language and a subpath deployment.

8 - API reference pages

Add an OpenAPI specification to the site. Use bundled Swagger UI or Redoc to render a browsable API reference without a CDN.

An API reference page is one OpenAPI specification plus one shortcode. Choose Swagger UI when readers need to try requests, or Redoc for browsing endpoint descriptions and schemas. Both runtimes ship with the theme and load only on pages that use them in HTML output, without a CDN. Swagger UI’s online validator is disabled. Remote specifications and API requests still contact their configured hosts.

Put the specification file under static/. Create a page with the shortcode. If the page needs the dedicated shell, change its type to swagger.

Where the specification file goes

Put the specification under static/. Hugo publishes it unchanged at the site root. Both shortcodes then receive a URL that the browser can fetch:

where the specification lives

  • static/
    • openapi/
      • docs-demo.yamlpublished as /openapi/docs-demo.yaml
  • content/
    • docs/
      • write/
        • openapi.mdthis page

Do not put the specification beside the page. Both shortcodes treat a local value as a path under static/. Neither resolves page resources. A .yaml file beside a content page is a page resource. A shortcode reference to its name does not publish it. The browser therefore receives a 404.

Both shortcodes accept a remote specification starting https://…. This creates a network dependency and exposes the reader’s metadata to that host. Intranet deployments and sites with a CSP should use a same-origin specification. Only http and https are accepted. Any other scheme, a protocol-relative //host, or an empty value warns. The shortcode then renders nothing.

To try the examples, download docs-demo.yaml and save it as static/openapi/docs-demo.yaml in your site. It describes a demonstration cluster-management API with no reachable server behind it.

Swagger UI

swagger has one named parameter, src, whose value is a URL from the site root. It passes through the theme’s URL validation, so a subpath deployment resolves correctly:

Source
{{< swagger src="/openapi/docs-demo.yaml" >}}

In your local preview, this displays expandable API operations, request parameters and response schemas. “Try it out” sends requests to the specification’s servers address. The sample has no working backend.

This page shows Swagger UI source and a live Redoc example below. Both widgets have known accessibility limitations. See Limits.

Redoc

redoc takes exactly one positional parameter, the specification path. A second parameter warns and the shortcode renders nothing.

Source
{{< redoc "openapi/docs-demo.yaml" >}}

OpenAPI specification — https://oink.pgsty.com/openapi/docs-demo.yaml

An http or https URL remains remote. Any other accepted value is a path under static/. Leading and non-leading slash forms are equivalent. For example, openapi/docs-demo.yaml and /openapi/docs-demo.yaml both become https://example.com/preview/openapi/docs-demo.yaml when the site baseURL is https://example.com/preview/. Unlike swagger, Redoc receives this absolute URL based on baseURL.

The theme pins five attributes — hide-hostname, hide-logo, suppress-warnings, lazy-rendering, native-scrollbars — and hides the Redocly brand mark with CSS. Redoc’s remaining attributes are not exposed to authors. If a site needs them, override layouts/_shortcodes/redoc.html.

The dedicated page shell

API reference pages are often wide and long. Use the swagger page type for this layout:

content/api/_index.md
---
title: Cluster management API
type: swagger
page_width: wide
cascade:
  type: swagger
---

swagger is one of the theme’s default shell types (params.ui.shell_types defaults to [docs, book, blog, swagger], and a site that overrides the list needs to keep it). It differs from the docs shell in exactly two ways. It adds a td-swagger class to <body> for styling hooks. It omits the version banner. Sidebar, table of contents, breadcrumbs, pager and page end all behave normally.

Shells and page width are covered fully in Layouts and page types.

Output

Output What appears
HTML The full interactive Swagger UI / Redoc. Only HTML loads the runtime, on demand from local files without a CDN
Print A labeled static link showing the specification’s address. Neither runtime loads
Markdown A plain Markdown link, [OpenAPI specification](/openapi/example.yaml). It does not become an endpoint list
RSS The same plain link

Outside HTML, the API reference contains only a link to the specification. To include endpoint information in print or agent output, describe key endpoints in prose on the same page. Body text outside the shortcode remains intact in all four outputs.

Limits

  • Both components derive their container ID from the page address and the shortcode’s ordinal, so several on one page never collide.
  • The two can coexist on one page, but the page becomes long and its HTML output loads both runtimes. Pick one for a production site.
  • Both embedded third-party widgets have upstream accessibility limitations: Swagger UI renders unnamed server controls and scrollable regions without keyboard access, and Redoc’s operation descriptions fall below AA contrast ratios. Evaluate these trade-offs against your site’s accessibility requirements, or document key endpoints directly in Markdown prose when strict conformance is required.
  • redoc accepts no attribute parameter. A second positional argument warns and the shortcode renders nothing.
  • A local redoc path starts under static/. A leading / is optional. Page resources are not resolved.
  • The browser must be able to fetch the specification. Put it in static/. After a build, confirm that the file exists under public/.
  • There is no mock server. Swagger UI’s “Try it out” sends a real request to the address in servers. The sample specification’s address is unreachable.

Verify

  1. Build with visible diagnostics: hugo --printPathWarnings.
  2. The specification really was published: ls public/openapi/docs-demo.yaml, or open http://localhost:1313/openapi/docs-demo.yaml.
  3. Expand endpoints on the page and confirm that their schemas appear. The browser console must show no 404 or cross-origin error.
  4. Disconnect from the external network while keeping the local preview server reachable, then reload. Local runtimes and a same-origin specification should still appear.