OINK Documentation

• 1: What is OINK
  • 1.1: Highlights
  • 1.2: Case Guide
  • 1.3: License and acknowledgements
• 2: Quick start
  • 2.1: Repository tour
  • 2.2: From scratch and other install methods
• 3: Authoring
  • 3.1: Writing pages
  • 3.2: Organizing content
  • 3.3: Page parameters
  • 3.4: Blog posts
  • 3.5: Books
  • 3.6: Releases and downloads
  • 3.7: API reference pages
• 4: Components
  • 4.1: Callouts
  • 4.2: Images
  • 4.3: Code Blocks
  • 4.4: Tabs
  • 4.5: Tables
  • 4.6: Fields
  • 4.7: Steps
  • 4.8: Cards
  • 4.9: FileTree
  • 4.10: Math
  • 4.11: Mermaid
  • 4.12: PlantUML
  • 4.13: Markmap
  • 4.14: Draw.io
  • 4.15: ECharts
  • 4.16: Infographic
  • 4.17: Gallery
  • 4.18: Badge
  • 4.19: Kbd
  • 4.20: Includes
  • 4.21: Asciinema
• 5: Customization
  • 5.1: Configuration
  • 5.2: Brand and appearance
  • 5.3: Home and landing pages
  • 5.4: Navigation and menus
  • 5.5: Layouts and page types
  • 5.6: Search
  • 5.7: Command palette
  • 5.8: Keyboard navigation
  • 5.9: Languages
  • 5.10: Versions
  • 5.11: Taxonomies
  • 5.12: Repository links and page info
  • 5.13: Print
  • 5.14: AI-agent support
• 6: Operations
  • 6.1: Local preview
  • 6.2: Deploy
  • 6.3: Comments
  • 6.4: Analytics and SEO
  • 6.5: Upgrade
  • 6.6: Troubleshooting
• 7: Design and development
  • 7.1: Architecture contract
  • 7.2: Component contract
  • 7.3: Shell and navigation contract
  • 7.4: Landing contract
  • 7.5: OINK migration boundary
  • 7.6: Design decisions
    • 7.6.1: Warnings and safe fallbacks
    • 7.6.2: Configuration model
    • 7.6.3: Markdown-first authoring
  • 7.7: Design research
    • 7.7.1: Goldmark block-attribute evidence
    • 7.7.2: Consumer and migration evidence
  • 7.8: Design proposals and PRDs
    • 7.8.1: Backlinks and knowledge graph
    • 7.8.2: Media convergence
    • 7.8.3: Bulk agent indexes

1 - What is OINK

OINK is a standalone Hugo theme for medium and large technical documentation sites. It evolved from Docsy: the content model and the multilingual behaviour are kept, while the shell, navigation, search and content components are replaced.

A consuming site’s only build dependency is one Hugo Extended binary. There is no Node.js, no npm, no PostCSS and no CDN request. Bootstrap, Font Awesome, the fonts, local search, the diagram runtimes and the API reference runtimes are all committed to the theme repository and shipped only to the pages that use them.

Components are not a second template language: > [!NOTE] is a callout, a table with a {.fields} line is a parameter list, and an image followed by {caption=} has a caption. Fourteen production sites run on it today, this one among them.

What the theme provides

• The documentation and blog shell: navigation, sidebar tree, table of contents, breadcrumbs, pager, dark mode, print view and accessible interaction.
• The multilingual frame: translation routing, fallback for untranslated pages, language weighting, RTL, and 32 interface language packs.
• Local runtimes: Mermaid, KaTeX, Markmap, Swagger UI, Redoc, Asciinema, ECharts, Infographic and local full-text search.
• Content components: callouts, tabs, steps, cards, field lists, file trees, galleries, badges, keys and more — most with a native Markdown form.
• Content types: beyond ordinary documentation, built-in book numbering and cross-references, release and download pages, data-driven landing pages, and OpenAPI reference pages.

The theme does not handle source hosting or deployment: a site can live on GitHub, GitLab or a private Git server, and the static files Hugo produces can be published anywhere. A site’s own content, brand and business components stay with the site; the theme supplies the shell and the reusable components.

Is OINK for me

How it differs from other documentation systems

The table below lists structural differences only, and only what can be confirmed from each project’s own documentation and repository. Versions change; check each project’s current documentation before choosing.

Two qualifications. Per-page Markdown output and llms.txt are not unique to OINK — Docsy and Hextra have them too, and all three need the site to opt in under outputs. Only the last row is exclusive to OINK, and it comes from PGSTY’s own production sites rather than from what a general documentation site needs. The theme’s interactive features are off by default: search, zoom, comments and feedback all require the site to turn them on.

OINK is not a skin layered over Docsy but a theme that forked and evolved separately. Docsy’s source history, its Apache-2.0 obligations and its attribution are kept intact; the details are in License and acknowledgements.

Start here

• Quick start — install Hugo, clone this site, replace the site details, publish to GitHub Pages.
• Components — one page per component, source first and rendered result after.
• Showcase — fourteen production sites and which part of OINK each one uses.

Highlights lists what the theme provides capability by capability, each entry linking to the guide that covers it.

1.1 - Highlights

This page lists what separates OINK from an ordinary Hugo theme, each item ending with the guide that covers it. To install straight away, see Quick start.

Components are written in Markdown

A callout is a > [!NOTE] blockquote (ten semantic types plus one neutral disclosure). A field list is a table with a {.fields} line. Steps and cards are lists with {.steps} / {.cards}. A caption is a {caption="…"} line under an image. Tabs are adjacent fences each carrying a {tab="…"}; file trees, galleries, Mermaid and ECharts are data fences named after their language. On GitHub or in any plain Markdown reader these degrade to blockquotes, tables, lists and code blocks, and nothing is lost.

29 shortcodes cover what the native forms cannot express: cards with icons and images, field entries whose body is several paragraphs of Markdown.

→ Components

One Hugo binary is enough

A consuming site’s entire build dependency is Hugo Extended 0.160.1 or newer. SCSS is compiled by Hugo’s embedded Sass transpiler; the theme never invokes postCSS. There is no npm, no webpack and no build-time download. Installing the theme as a Hugo Module needs Go on the machine to resolve the module; an offline archive or a submodule does not.

“Hugo only” refers to the build dependency. The interface still runs JavaScript in the browser: search, the command palette, diagrams and tabs are page scripts. The difference is that those scripts ship with the theme and are delivered per page according to what that page actually uses.

→ Quick start

Local-first

Everything the browser needs is committed to the theme repository: Bootstrap, Font Awesome, four fonts, Lunr, Mermaid, KaTeX, Markmap, Swagger UI, Redoc, Asciinema, ECharts, Infographic. VENDOR.json records the version, source, licence file and SHA-256 checksum of each of the 28 dependencies; updating a runtime means updating artifact, licence and checksum together.

Where a feature could cause a network request, the theme fails the build rather than reaching out silently: PlantUML without params.plantuml.svg_image_url, Diagrams.net without params.drawio.drawio_server, and Algolia without appId / apiKey / indexName all stop the build.

Local-first does not extend to what an author adds. All of these are explicit network choices: external links, remote images and video, iframes, remote API specifications; hosted search such as Algolia or Google Programmable Search; analytics, comments and other SaaS integrations; and PlantUML or Diagrams.net once the author configures a remote renderer. Pages using them are still valid pages, but a site should stop claiming those pages work fully offline.

→ License and acknowledgements · Configuration

One source, four outputs

Every component has a defined shape in all four outputs: interactive HTML; a print page with zoom and copy controls stripped and disclosures fully expanded; plain Markdown; and RSS. The print view is generated per section (this one is /_print/docs/about/), and the Markdown version is the same page address plus index.md.

A site chooses which of them it wants under outputs; the theme does not decide for it.

→ Print · AI-agent support

Two languages and 32 interface locales

Multilingual support uses Hugo’s own mechanism: translation routing, a language picker ordered by weight, fallback for untranslated pages, RTL, and canonical and alternate metadata. Interface strings come in 32 language packs sharing one key schema. English, Simplified Chinese (zh-cn and the generic zh) and Traditional Chinese (zh-tw) are human-reviewed; the other locales keep the translations inherited from Docsy, with English fallbacks for the keys OINK added.

→ Languages

Full-text search that stays on the site

With params.offline_search on, Hugo generates one index per language. The browser searches Latin text with a local Lunr index and falls back to substring matching for CJK text; no query leaves for a third party. A page can adjust its weight with search_boost and add synonyms with search_keywords.

→ Search

Command palette

Cmd/Ctrl + K opens the command palette; a bare / enters search mode and a bare \ enters command-only mode. The palette holds pages, commands and page actions (switch language, switch theme, copy Markdown) together, so searching and acting share one entry point.

→ Command palette

Keyboard navigation

On by default, and switchable off per site or per section. w and s move up and down the sidebar tree, a and d collapse and expand, q and e go to the previous and next page, j and k jump along the page’s table of contents, t toggles light and dark, l switches language, h hides the reading shell. Every single-key shortcut stands down while an input or textarea has focus or an input method is composing. The question-mark button in the footer’s bottom bar opens the cheatsheet.

→ Keyboard navigation

Four content types beyond documentation

The theme also has four kinds of page that need extra structure:

• Books: chapter numbering, figures / tables / equations / examples numbered with {#id num=} and cross-referenced with xref, indexes generated by book-toc and book-figures and friends, and a printable whole.
• Release and download pages: data/download/*.yaml produces release cards, asset tables and checksums, with a controlled publication state.
• Landing pages: data/home/<lang>.yaml assembles the home page sections; any page with layout: landing can use data under data/landing/.
• API references: Swagger UI and Redoc are both local runtimes, and the specification can live on the site.

→ Books · Releases and downloads · Home and landing pages · API reference pages

Output for AI assistants

Add markdown to outputs and every page gains a .md twin, the HTML <head> gains a rel="alternate" pointing at it, and the page actions gain “Copy Markdown” and “View source”. The LLMS output format writes an llms.txt inventory at the site root (this site’s is https://oink.pgsty.com/llms.txt).

“Open in ChatGPT / Claude” is off by default: clicking it hands the current URL to a third party, so the site must turn on params.ui.page_context_menu.assistant_links explicitly.

→ AI-agent support

Versions

Configure params.versions and a version menu appears in the navbar, while an archived version shows a banner at the top of the page pointing readers at the current one; whether the menu jumps page-for-page is the site’s choice. The versions are separately built and separately deployed static sites, so nothing is needed at runtime.

→ Versions

See for yourself

This site has most of the above enabled. Three checks:

1. Press Cmd/Ctrl + K on any page and type postgres to see local search results; press \ for command-only mode.
2. Append index.md to the current page address to get this page’s Markdown version.
3. Open https://oink.pgsty.com/llms.txt, the site inventory written for AI assistants.

Related

• What is OINK — scope, fit and comparisons
• Showcase — how production sites use these features
• Quick start — from clone to deploy
• Configuration — where to look up the parameters named above

1.2 - Case Guide

The canonical Case library turns fifteen production sites into short, reusable implementation patterns, and the home page mirrors the same fifteen. All of them run OINK, including this documentation site itself as a self-referential case.

Use this guide when you know the shape of the site you want to build. Follow a case for its architecture and trade-offs, then use the linked documentation for the exact configuration. Counts in individual cases describe the audited snapshot rather than a permanent property of a live site.

Distribution documentation

pigsty.io

A very large English site combining a distribution manual, editorial blog, extension catalogue, taxonomies, version navigation, and pricing landing pages.

pigsty.cc

The Chinese peer deployed as an independent single-language site—a useful trade-off when both language corpora have become products in their own right.

pgsty.pro

A bilingual version archive that renders many release pages from reusable, structured release data.

Product documentation

PIG

A compact bilingual CLI manual with a data-driven home page and a much larger companion blog.

SOW

A bilingual operations manual with a dedicated download content type fed by release metadata.

SILO

A large upstream migration whose checked manifest generates the bilingual documentation navigation.

PG Exporter

A metrics manual combining generated navigation, a structured catalogue, and a system-font presentation.

Books

Designing Data-Intensive Applications

A multilingual, multi-edition book and the strongest example of numbered figures, cross-references, chapter navigation, and indexes.

The Product-Minded Engineer

A focused bilingual publication that needs only OINK’s Book shell.

PG Internal

A finished Chinese translation published as a deliberately single-language Book, with no documentation tree and nothing to switch languages to.

Aggregate, landing, and custom sites

pgsql.cc

An aggregate operations library where several upstream manuals and partially translated language trees share one search and visual system.

pgsty.com

A small bilingual corporate site showing that OINK can primarily be a data-driven landing-page system.

Capslock

A two-page-per-language project whose custom shell hosts an interactive, data-driven configuration generator.

oink.pgsty.com

The full reference site: public documentation, live component examples, design contracts, multiple content shells, and regression coverage in one repository.

pgext.cloud

The PostgreSQL extension catalog: a queryable dataset as the primary object of a site, indexing 2,241 extensions and 576 packaged builds across 16 platforms.

Choosing a starting point

• For a conventional product manual, begin with PIG or SOW.
• For a large migration, compare SILO and pgsql.cc.
• For a book, compare TPME with the more elaborate DDIA implementation, or PG Internal for a single-language one.
• For a landing or interactive site, start with pgsty.com or Capslock.
• For the broadest reference, use OINK Docs.
• For a queryable dataset presented as the primary object of a site, see ext.pgsty.com.

The theme repository’s tests/site/ is an internal CI fixture, not a starter template. Its pages exist to exercise rendering behavior; the production cases above are the better design references.

→ Browse all cases · Quick start · Repository tour

1.3 - License and acknowledgements

OINK is three layers of material: the theme source, the documentation content, and the third-party assets shipped with the theme. None of them is relicensed into a single combined work. Every table below points at the authoritative file in the repository; where a summary and the licence text disagree, the file wins.

Which licence covers what

Two boundaries are worth keeping straight. CC BY 4.0 covers the original documentation content only, not the theme code, the trademarks, the screenshots or the third-party assets. And the theme being Apache-2.0 does not turn its bundled dependencies into Apache-licensed works.

Upstream: Docsy

What the theme’s NOTICE records:

• OINK is derived from Docsy, Copyright 2018 Google LLC and Docsy contributors.
• OINK’s own theme work is Copyright 2026 PGSTY contributors.
• The project and its upstream are both under Apache License 2.0. The licence, source, version and checksum of every third-party browser dependency are recorded in VENDOR.json, and each NOTICE file a dependency requires is distributed beside the asset it belongs to.
• The Docsy name and Google’s trademarks belong to their respective holders; naming them here identifies the upstream project and implies no endorsement.

This site is likewise derived from the Docsy project website, and that lineage is recorded in the site’s own NOTICE. Docsy is OINK’s only code upstream: the source history, the Apache-2.0 obligations and the copyright notices are kept intact, and as Apache-2.0 requires, modified files carry a modification notice.

Third-party runtimes shipped with the theme

The theme commits everything the browser needs to the repository (assets/third_party/, assets/js/third_party/, static/webfonts/), so a consuming site needs no npm and downloads nothing at build time. VENDOR.json is the machine-readable manifest for that material: for each entry it records the name, the pinned version, the source URL, the licence file path and the SHA-256 of every selected artifact, plus an aggregate checksum for each of the three asset trees.

The table below is a snapshot of that manifest (VENDOR.json generated 2026-08-17, schema 1, 26 entries). Versions change with each theme release, so the VENDOR.json in the repository is authoritative. Every source is the npm registry (https://registry.npmjs.org/…).

Licence texts sit beside the asset they belong to — for example assets/third_party/bootstrap/LICENSE and assets/third_party/katex/LICENSE — and Swagger UI, Redoc and ECharts also ship their own NOTICE or bundled-declaration files. Lunr is the one exception: its code is in assets/js/third_party/ while its licence is at assets/third_party/lunr/LICENSE.

Redistributing the theme means carrying all of this licence and notice material with it. Updating a runtime means updating the artifact, the licence file, the source and the checksum in the same change.

Fonts and icons

All three fonts (Inter, Chakra Petch, IBM Plex Mono) are under the SIL Open Font License 1.1, and the font files are committed to static/webfonts/: fourteen Inter subset files, four brand-font files, and Font Awesome’s three, twenty-one in all. Font Awesome Free 7.3.1 carries a composite licence — CC BY 4.0 for the icon artwork, SIL OFL 1.1 for the font files, MIT for the code — with the text in assets/third_party/Font-Awesome/LICENSE.txt.

The theme makes no request to a remote font service: there is no Google Fonts link in the repository, and fonts are always served from the site’s own baseURL. To change fonts or switch to the platform stack, see Brand and appearance.

Design references

Docsy is the only code upstream. The projects below are references for the design language. They are neither a source of code nor a runtime dependency, and OINK has ported no code from them:

Hugo is the build platform, and Go resolves modules when the theme is installed as a Hugo Module. Both are prerequisites, and the theme redistributes neither binary.

Naming these projects describes lineage, dependency or inspiration and implies no endorsement by them; project and product names belong to their respective holders.

Reusing this documentation

CC BY 4.0 permits sharing and adaptation for any purpose, provided you give attribution, link to the licence, state whether you made changes, and do not imply that OINK, PGSTY or any upstream project endorses your adaptation. A sufficient attribution reads:

Adapted from the OINK documentation by PGSTY contributors, licensed under CC BY 4.0, with modifications.

Images or quotations that carry their own attribution on a page keep their own credit and licence; removing the footer does not discharge the attribution obligation.

Reusing the theme

Apache-2.0 permits using, modifying and distributing the theme source and its build output under its terms, provided you keep the licence, copyright and attribution notices, keep the contents of NOTICE, and state which files you changed when distributing modified source. A theme distribution should include LICENSE, NOTICE, VENDOR.json, and every third-party licence file the manifest references.

Apache-2.0 grants no trademark rights, and it does not turn third-party assets into Apache-licensed works.

Related

• What is OINK — what the project is and where it came from
• Highlights — what local-first means in practice
• Configuration — which features bring in an external service
• Brand and appearance — changing fonts and icons

2 - Quick start

This path does not start from an empty directory. It starts by cloning the site you are reading, deleting what you do not need, and replacing the rest with your own details. This site is OINK’s regression site: it contains every component and every page type, and it tracks the theme version. Trimming it down is less writing than adding configuration and examples one at a time to an empty directory.

Prerequisites: a machine that can install Hugo Extended and Go, a GitHub account, and ten minutes. No Node.js and no other front-end toolchain.

What you end up with

A bilingual documentation site: your directory tree in the left sidebar, this page’s outline on the right, full-text search and a command palette in the navbar, and light or dark following the system. One Markdown source produces the web page, the print page, plain Markdown and RSS. Hosted on GitHub Pages.

Walkthrough

1. Install Hugo Extended and Go

   Besides Git you need two things. Hugo Extended must be 0.160.1 or newer: the standard Hugo build has no embedded Sass compiler, cannot compile the theme’s styles, and fails the build. Go resolves modules: OINK is published as a Hugo Module, and Hugo uses Go’s module machinery to download and verify github.com/pgsty/oink.

   macOS

   brew install hugo go git

   Linux

   # Distribution repositories often carry a Hugo that is too old; use the official deb (this site's CI does the same)
   curl -LO https://github.com/gohugoio/hugo/releases/download/v0.164.0/hugo_extended_0.164.0_linux-amd64.deb
   sudo dpkg -i hugo_extended_0.164.0_linux-amd64.deb
   sudo apt install -y golang-go git

   Windows

   winget install Hugo.Hugo.Extended
   winget install GoLang.Go
   winget install Git.Git

   Check once afterwards; the output must contain extended:

   $ hugo version
   hugo v0.164.0+extended+withdeploy darwin/arm64 BuildDate=2026-07-06T16:39:30Z
   $ go version
   go version go1.26.6 darwin/arm64
   

   On other platforms follow the Hugo installation guide and go.dev/dl, taking care to pick the extended build.

2. Clone the documentation site and preview it

   git clone https://github.com/pgsty/oink.pgsty.com my-docs
   cd my-docs
   hugo server

   Open http://localhost:1313/; the Chinese site is at http://localhost:1313/zh/. The first start downloads the theme module (a few seconds to a minute, depending on the network); after that, edits hot-reload in milliseconds.

   The committed go.mod pins the theme version, so the clone builds as it is, with no extra install script.

   Note

   The Makefile in the repository is only a set of command aliases. make dev and make check use a sibling ../oink theme checkout through HUGO_MODULE_REPLACEMENTS; make build and make serve always use the published version pinned in go.mod. For a new site, hugo server is enough.

3. Replace the site details

   Site identity lives entirely in hugo.yml. baseURL is a YAML anchor — the real address is written on params.productionURL, and that is the only place to change it:

   hugo.yml

   title: Product Docs # navbar site name and <title>
   
   params:
     productionURL: &productionURL https://docs.example.com/
     github_repo: https://github.com/example/product-docs # where "Edit this page" points
     copyright:
       authors: '[Example Inc.](https://example.com/)'
       from_year: 2026
     footer_center_info: ''
   
   baseURL: *productionURL

   languages.en.title and languages.zh.title override the top-level title, so change both. Every parameter’s meaning and default is in Configuration.

   Delete the configuration specific to this site. Keeping it points your site at OINK’s repositories and accounts.

   Key in hugo.yml	What to do
   services.googleAnalytics.id	OINK’s analytics ID. Delete it, or replace it with your own when you want analytics
   params.comments	giscus pointing at discussions in pgsty/oink.pgsty.com. Delete the block or point it at your repository
   params.tdVersion params.version params.version_menu params.versions	OINK’s version menu. Delete
   params.github_project_repo	A link to the theme repository. Delete
   languages.<lang>.menus.main	Navbar entries pointing at this site’s sections such as /docs/tutorial. Rewrite for your tree

   Replace the logo and icons. Replace these three files, keeping the filenames — the theme mounts them by name:

   static/

   static/favicon.svg           # browser tab icon
   static/favicon.ico
   static/apple-touch-icon.png  # iOS add-to-home-screen

   static/logo.svg is this site’s own brand lockup and no parameter points at it. Delete it, or replace it with a horizontal wordmark and set params.wordmark.

   Replace the content. content/docs/ is OINK’s own theme documentation; delete the whole tree and write your first page:

   rm -rf content/docs && mkdir -p content/docs

   content/docs/_index.md

   ---
   title: Docs
   linkTitle: Docs
   description: Product documentation.
   weight: 20
   ---
   
   Everything about running Product in production.

   content/blog/ can keep one post as a template or be deleted entirely (if you delete it, remove the blog entry from menus.main as well). Which directories must stay and which belong to the documentation site itself is in Repository tour.

   For an English-only site, delete the whole languages.zh block and every .zh.md file, leaving one language:

   hugo.yml

   defaultContentLanguage: en
   languages:
     en:
       label: English
       locale: en-US
       weight: 1
       title: Product Docs
       menus:
         main:
           - { name: Docs, pageRef: /docs, weight: 20 }

   find content -name '*.zh.md' -delete

   To keep both languages or swap in a different pair, see Languages.

4. Deploy

   Create an empty repository on GitHub and replace the local history with your own:

   rm -rf .git && git init -b main
   git add . && git commit -m "Initial documentation site"
   git remote add origin [email protected]:example/product-docs.git
   git push -u origin main

   The repository ships with .github/workflows/pages.yml: a push to main builds and publishes, and it can also be triggered by hand from the Actions page (workflow_dispatch). It pins the Hugo Extended and Go versions, builds with --printPathWarnings --panicOnWarning, and takes baseURL from GitHub Pages, so publishing to a subpath such as example.github.io/product-docs/ needs no configuration change.

   In the repository, go to Settings → Pages → Build and deployment → Source and choose GitHub Actions. The default is Deploy from a branch, and leaving it will make the workflow fail at the deploy step.

   Deleting scripts/ means editing the workflow

   The Verify advertised and pinned release match step in pages.yml runs node scripts/check-release-pin.mjs to check that the version the site advertises matches the one pinned in go.mod. Once scripts/ is gone, remove that step and Set up Node.js from pages.yml.

   For Cloudflare Pages, Netlify, Nginx and offline packaging, see Deploy: the build command is always hugo --gc --minify, and only baseURL and the environment variables differ.

Verify

Run a production build locally. It is stricter than the development server, and path warnings fail the build:

hugo --gc --minify --printPathWarnings --panicOnWarning

It passes when it prints Total in … with no WARN or ERROR. Then check against the preview:

• The navbar shows your site name and logo, and the browser tab shows your favicon
• The sidebar is your own tree, and every page opens
• Ctrl+ with K (or ⌘+ with K on macOS) opens the command palette and finds the page you just wrote
• In the menu beside the page title, “Edit this page” points at your repository, not pgsty/oink.pgsty.com
• After deploying, Deploy Oink site to GitHub Pages is green on the repository’s Actions page

For build errors, see Troubleshooting.

Next steps

• Repository tour — what each cloned directory is, and what can go.
• Writing pages — what a documentation page is made of: front matter, heading anchors, links and images.
• Components — callouts, tabs, field lists, file trees and the rest, one page each.
• Brand and appearance — accent colour, font preset, page width and custom styles.
• Deploy — hosting beyond GitHub Pages, and the acceptance checklist.

Instructions for a coding assistant

The four steps above can be handed to a coding assistant (Claude Code, Codex and the like). Copy the block below and replace the three bracketed items with your own details:

Please set up a documentation site for me with the OINK theme, following the process
below. Where something is unclear, apply "only ask when information is missing".

1. Check the environment: run `hugo version` and require the output to contain `extended`
   with a version >= 0.160.1; run `go version` and require a version number. If either
   fails, install it per the official documentation first — `brew install hugo go` on
   macOS, the hugo_extended deb from GitHub Releases on Debian/Ubuntu.
2. Clone the site template: `git clone https://github.com/pgsty/oink.pgsty.com [target directory]`
   and change into it.
3. Change three things in hugo.yml: the top-level `title` and `languages.<lang>.title` to
   [site name]; `params.productionURL` to [site domain] (baseURL is a YAML anchor pointing
   at it, so do not change baseURL separately); `params.github_repo` to the repository this
   site will live in. Also delete this site-specific configuration:
   `services.googleAnalytics`, `params.comments`, `params.tdVersion`, `params.version`,
   `params.version_menu`, `params.versions`, `params.github_project_repo`, and reduce
   `menus.main` to /docs and /blog only.
4. Clear the example content: delete the whole `content/docs/` tree and create a new
   `content/docs/_index.md` (front matter with at least title / description / weight);
   keep one post under `content/blog/` as a template. Delete the scaffolding that belongs
   to the documentation site itself: `tests/`, `scripts/`, `playwright.config.mjs`,
   `package.json`, `package-lock.json`, `AGENTS.md`, `TRANSLATION.md`, `CONTRIBUTING.md`,
   `agent-docs.config.yml`; delete every workflow under `.github/workflows/` except
   `pages.yml`; and remove the `Set up Node.js` and
   `Verify advertised and pinned release match` steps from `pages.yml`.
5. Start `hugo server` in the background and confirm http://localhost:1313/ returns 200
   and the page title is the new site name.
6. Validate: run `hugo --gc --minify --printPathWarnings --panicOnWarning` and require it
   to end with `Total in ...` and no WARN/ERROR. Fix any error rather than working around
   it by suppressing warnings.
7. Only ask me when [site name], [site domain] or the repository address is missing;
   otherwise proceed with the defaults above.

The resulting site is easy for an assistant to read: every page has a .md plain-text output, the site root has llms.txt, and the menu beside the page title offers “Copy as Markdown” and “Open in Claude”. See AI-agent support.

To start from an empty directory instead of this repository, see From scratch and other install methods.

Related

• Repository tour — what each directory is, and the order to delete in
• From scratch and other install methods — starting with hugo mod init, submodules and offline installation
• Local preview — the hugo server switches worth knowing, and previewing drafts
• Deploy — configuration per host, and the acceptance checklist
• Troubleshooting — the four common classes of error: build, language, search, platform

2.1 - Repository tour

This page goes through every file and directory of a pgsty/oink.pgsty.com clone: what must stay, what to replace with your own details, what belongs to the documentation site and can be deleted whole — plus a safe order to delete in.

The theme’s code is not in this repository. It is a Hugo Module pinned by go.mod and stored in Go’s module cache. This repository holds content, configuration, and a small number of site-level overrides.

Top-level structure

Not listed above: .gitignore, .gitattributes, .nvmrc, .npmrc, and the generated output excluded by .gitignore — public/ (build output), resources/ (Hugo’s resource cache) and node_modules/. That last group never enters version control.

There is no i18n/ in the repository: interface strings (“Previous”, “On this page” and the like) come from the theme’s 32 language files. To change one of them, create i18n/zh.yaml at the site root and write only the keys you override.

What to do with each entry

Deletion order

Delete the periphery first, then the content, then the data. Build after each step so a problem points back at one step.

1. Drop the scaffolding

   None of this takes part in rendering, and removing it affects no page.

   rm -rf tests scripts node_modules
   rm -f package.json package-lock.json playwright.config.mjs .nvmrc .npmrc
   rm -f AGENTS.md TRANSLATION.md CONTRIBUTING.md agent-docs.config.yml Makefile
   rm -f .github/workflows/site-checks.yml .github/workflows/browser-quality.yml

   After deleting scripts/ you must edit .github/workflows/pages.yml: remove the Set up Node.js and Verify advertised and pinned release match steps, or the deploy fails there.

2. Drop the example content

   content/docs/ is OINK’s own theme documentation and content/blog/ its engineering blog; neither has anything to do with your product.

   rm -rf content/docs
   mkdir -p content/docs
   rm -rf content/blog        # if you want no blog; otherwise keep one post as a template

   Edit menus.main under each language in hugo.yml at the same time: those entries point at paths such as /docs/tutorial and /blog/release that no longer exist. content/_index.md is the home page — keep it and replace the body with yours.

3. Trim the data

   The three groups under data/ feed the home page, landing pages and release pages. Keep the home page data and edit it; delete the other two if unused.

   rm -rf data/landing data/download

   data/home/en.yaml and data/home/zh.yaml decide which sections the home page has; each entry is explained in Home and landing pages. Deleting data/home/ entirely still builds, and the home page falls back to an ordinary content page.

4. Swap the identity

   Finally, change the site name, params.productionURL, params.github_repo and the brand parameters in hugo.yml to yours, replace the logo and favicon under static/, and delete the OINK-specific configuration: services.googleAnalytics, params.comments and the params.version* keys. The itemized list is in step 3 of Quick start.

Where the theme lives

The theme is referenced as a Hugo Module, and two places point at it:

module:
  imports:
    - path: github.com/pgsty/oink
  hugoVersion:
    extended: true
    min: '0.160.1'

require github.com/pgsty/oink v0.6.0

hugo.yml declares which theme to use, go.mod pins which version of it, and go.sum records that version’s checksums. All three files are committed. The theme source never enters your repository: Hugo downloads it into Go’s module cache, and hugo mod graph shows what actually resolved.

Upgrade to the newest version:

hugo mod get -u github.com/pgsty/oink

Pin to one version:

hugo mod get github.com/pgsty/[email protected]

Both commands rewrite go.mod and go.sum. A production site pins a release tag rather than following main. What to check before and after an upgrade, and how to roll back, is in Upgrade.

Site overrides

Files under layouts/ shadow the theme’s files of the same name, following Hugo’s template lookup order. This site has only one kind:

• layouts/_shortcodes/*.html — the site’s own shortcodes. Product documentation that needs a shortcode with business meaning puts it here too.

Self-linking heading anchors come from the theme’s own _markup/render-heading.html; a site does not need to build that hook.

To change the shell (sidebar, footer, page end), override the narrowest partial rather than copying baseof.html wholesale — a copy has to be merged by hand at every theme upgrade.

Verify

Build after each deletion step so an error points at what you just removed:

hugo --gc --minify --printPathWarnings --panicOnWarning

Once the deleting is done, all of this should hold:

• The build ends with Total in … and no WARN or ERROR
• No navbar entry links to a deleted directory
• Headings still have their self-link anchors (the theme’s own heading render hook; the site needs no override)
• git status shows no public/ or resources/

Related

• Quick start — the full clone, configure and deploy path
• From scratch and other install methods — building from an empty directory instead of trimming
• Organizing content — how the content/ tree becomes the sidebar
• Configuration — every hugo.yml key and its default
• Upgrade — upgrading the theme module, and the migration toolkit

2.2 - From scratch and other install methods

This page builds a minimal OINK site in an empty directory: a dozen lines of hugo.yml plus one hugo mod get gives a single-language site you can preview. The cost is that the home page, the example content and any component usage to copy from are all yours to write.

An existing Hugo site needs no scaffolding: install the theme module, add the three Goldmark prerequisites (see Writing hugo.yml), and leave the content alone. For an existing Docsy site, see Upgrade.

The second half weighs four install methods: Hugo Module, Git submodule, offline archive, pinned clone.

From an empty directory to the first page

1. Create the skeleton and fetch the theme

   hugo new site --format yaml my-docs
   cd my-docs
   hugo mod init github.com/example/my-docs
   hugo mod get github.com/pgsty/[email protected]

   What follows hugo mod init is your own site’s module path, usually the repository address. hugo mod get writes go.mod and go.sum, and both are committed.

   The newest version number is on GitHub Releases; the v0.6.0 on this page is what this site currently pins. A production site pins a release tag rather than following main: @latest is a one-off resolution, not a version policy.

2. Writing hugo.yml

   Rename the hugo.yaml that hugo new site generated to hugo.yml (Hugo accepts both; this documentation uses the latter throughout) and replace its contents with the following, which builds as it stands:

   hugo.yml

   title: Product Docs
   baseURL: https://docs.example.com/
   defaultContentLanguage: en
   # enableGitInfo: true        # the "last modified" time comes from git; run git init before enabling
   
   languages:
     en:
       label: English
       locale: en-US
       weight: 1
       title: Product Docs
       params:
         description: Everything about running Product in production
       menus:
         main:
           - { name: Docs, pageRef: /docs, weight: 20 }
           - { name: Blog, pageRef: /blog, weight: 50 }
   
   # The three Goldmark prerequisites: OINK's native Markdown components depend on them
   markup:
     goldmark:
       renderer:
         unsafe: true # allow inline HTML in content
       parser:
         attribute:
           block: true # attribute lines such as {.steps} {.cards} {caption=}
         wrapStandAloneImageWithinParagraph: false # only a block-level image can carry an attribute line
     highlight:
       noClasses: false # code colours follow light and dark mode
   
   params:
     offline_search: true
     github_repo: https://github.com/example/product-docs
     copyright:
       authors: '[Example Inc.](https://example.com/)'
       from_year: 2026
     ui:
       dark_mode: true
       sidebar_menu_foldable: true
       section_index: cards
   
   outputs:
     home: [HTML, markdown, LLMS]
     page: [HTML, markdown]
     section: [HTML, RSS, print, markdown]
   
   module:
     imports:
       - path: github.com/pgsty/oink
     hugoVersion:
       extended: true
       min: '0.160.1'

   What each of the five blocks governs:

   Block	Governs	Consequence of omitting it
   Top level + languages	Site name, domain, languages and navbar menu	A wrong baseURL sends every absolute link astray in production
   markup.goldmark	The three component prerequisites	An attribute line becomes a literal {.steps} in the prose
   params	Search, repository links, shell switches	Interactive features stay off; the theme does not decide for the site
   outputs	The per-page .md, llms.txt and print pages	No “Copy as Markdown” in the page menu, and no print view
   module	References the theme and declares the Hugo floor	The build cannot find the theme

   Mathematics additionally needs Goldmark’s passthrough extension; see Math. Every key’s full meaning and default is in Configuration.

3. Write the first page

   Every top-level directory under content/ is a section, and the directory structure is the sidebar structure. A documentation section needs at least an _index.md:

   content/docs/_index.md

   ---
   title: Docs
   linkTitle: Docs
   description: Everything about running Product in production.
   weight: 20
   ---
   
   Start with [Install](/docs/install/).

   content/docs/install.md

   ---
   title: Install
   description: Install Product on a fresh machine.
   weight: 10
   ---
   
   ## Prerequisites {#prerequisites}
   
   > [!IMPORTANT]
   > Product needs PostgreSQL 18 or newer.
   
   ## Install {#install}
   
   ```bash
   curl -fsSL https://get.example.com | bash
   ```

   Write explicit {#id} anchors on headings: when a translation is added later, the two languages’ anchors have to correspond. How to write a page is in Writing pages.

4. Preview

   hugo server

   Open http://localhost:1313/ and the sidebar shows Docs → Install. Edits hot-reload in milliseconds.

Other install methods

The steps above use a Hugo Module. The other three address particular constraints: network isolation, a platform that requires the build input to contain the whole theme tree, or an organization that reviews its own copy of the theme. Apart from hugo mod vendor, none of them creates a Go module, and the site references the theme with theme: oink rather than module.imports. The shared cost is that version resolution and integrity checking become your responsibility.

Hugo Module (recommended)

hugo mod init github.com/example/product-docs
hugo mod get github.com/pgsty/[email protected]

module:
  imports:
    - path: github.com/pgsty/oink

The only method where Hugo resolves the version itself, verifies the checksum, and leaves an audit record in go.sum. hugo mod graph shows what actually resolved and hugo mod get -u upgrades. It needs Go on the machine.

Git submodule

Record an exact theme commit in the site repository:

git submodule add https://github.com/pgsty/oink.git themes/oink
git -C themes/oink fetch --tags
git -C themes/oink checkout v0.6.0
git add .gitmodules themes/oink

theme: oink

CI must initialize the submodule before running Hugo, or themes/oink is an empty directory:

git submodule update --init --recursive

Offline archive

For network-isolated environments. Two paths, both prepared on a connected machine and carried in whole.

With hugo mod vendor, the resolved theme source is frozen into the site directory, and later builds need neither the network nor Go.

hugo mod vendor          # writes _vendor/, holding the theme's full source tree
tar czf my-docs.tgz .    # carry _vendor/ into the isolated environment with everything else

When _vendor/ exists Hugo prefers it (hugo mod graph prints +vendor), and module.imports in hugo.yml stays as it is. This step needs Go; the builds after it do not. Upgrading the theme means returning to a connected environment and running hugo mod get and hugo mod vendor again.

_vendor/ collects only the directories the theme mounts (assets, data, i18n, layouts, static) plus hugo.yaml and theme.toml. It does not include LICENSE, NOTICE or VENDOR.json. To redistribute that archive, take those three files from the theme repository as well.

With a tag source archive, no Go module is created; a version of the theme is simply unpacked into themes/oink/.

curl -L -o oink.tar.gz \
  https://github.com/pgsty/oink/archive/refs/tags/v0.6.0.tar.gz
mkdir -p themes/oink
tar xzf oink.tar.gz -C themes/oink --strip-components=1

theme: oink

The theme repository’s root is the module root, so unpacking lands directly on layouts/, assets/, i18n/ and static/ with no further level to descend into. Redistribution must keep LICENSE, NOTICE and VENDOR.json; the last records each third-party runtime’s version, source, licence path and SHA-256, and is what an offline audit rests on.

When moving between machines, generate the archive and its checksum from an immutable tag on the connected side:

git clone --branch v0.6.0 --depth 1 \
  https://github.com/pgsty/oink.git oink
git -C oink archive --format=tar.gz --prefix=oink/ \
  --output=../oink-v0.6.0.tar.gz v0.6.0
shasum -a 256 oink-v0.6.0.tar.gz \
  > oink-v0.6.0.tar.gz.sha256

Carry the archive and its .sha256 into the isolated environment, verify, then unpack:

shasum -a 256 -c oink-v0.6.0.tar.gz.sha256
mkdir -p themes
tar -xzf oink-v0.6.0.tar.gz -C themes

An archive produced this way is your own artifact, not a project release. Whether a given tag’s release page carries an archive and a checksum file varies by release; verify the checksum independently when using a public attachment.

Before building offline, confirm the archive is complete. All eleven of these must be present:

Pinned clone

For a hosting platform that requires the build input to contain the whole theme tree:

git clone https://github.com/pgsty/oink.git themes/oink
git -C themes/oink checkout v0.6.0

The difference from a submodule is that the theme files enter your repository history directly, without the .gitmodules indirection. Record the commit that was finally resolved and the procedure for restoring it.

The four methods compared

Developing against a local theme checkout

This section applies only when changing the theme and the site together. Clone the two repositories as siblings:

~/pgsty/
├── oink/            # the theme
└── product-docs/    # your site

Use the HUGO_MODULE_REPLACEMENTS environment variable to substitute the local checkout temporarily, leaving go.mod untouched:

cd ~/pgsty/product-docs
HUGO_MODULE_REPLACEMENTS='github.com/pgsty/oink -> ../oink' hugo server

The documentation site’s Makefile is an alias for exactly these commands, and make dev and make check expect the theme checkout at the sibling ../oink:

build:
	hugo --cleanDestinationDir --minify

check:
	HUGO_MODULE_REPLACEMENTS='github.com/pgsty/oink -> $(abspath ../oink)' npm test

dev:
	HUGO_MODULE_REPLACEMENTS='github.com/pgsty/oink -> $(abspath ../oink)' hugo server --renderToMemory

A Go workspace (go work init plus HUGO_MODULE_WORKSPACE=go.work) is an equivalent alternative. Both apply to the local machine only: CI and production builds use the version in go.mod, and go.work is never committed.

Verify

hugo mod graph                                       # which theme version actually resolved
hugo --gc --minify --printPathWarnings --panicOnWarning

It passes when the build ends with Total in … and no WARN or ERROR. Then confirm:

• /docs/ opens and the sidebar holds the page you wrote
• The navbar has a search box that finds the heading you just wrote
• The light/dark toggle is present, and code block colours follow it (which shows markup.highlight.noClasses: false took effect)
• git status shows go.mod and go.sum, and no public/ or resources/

Related

• Quick start — the other path: clone the documentation site and trim it
• Repository tour — what each directory of the documentation site is
• Configuration — every hugo.yml key and its default
• Writing pages — how to keep writing after the first page
• Upgrade — upgrading the theme module, and migrating from Docsy

3 - Authoring

This section covers the content types OINK supports: documentation pages, blog posts, books, release and download pages, and OpenAPI references. They share one Markdown dialect and one front matter schema, and each adds its own conventions.

What a documentation page is made of

A documentation page is one Markdown file. Between the two --- lines at the top is the front matter — the page’s metadata: title, short sidebar name, description, ordering. The rest is the body: ordinary Markdown plus OINK’s native components. Here is a complete page:

---
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 it as content/docs/install.md, run hugo server, and the page appears at /docs/install/ with an “Install” entry in the sidebar.

Content types and where they are covered

3.1 - Writing pages

This page covers writing a documentation page end to end: where the file goes, the front matter, heading anchors, links, images, drafts, and the page end. It assumes the site already builds locally; if it does not yet, start with Quick start.

Creating a page

A page is a Markdown file under content/, and its URL follows its position there: 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.

A page with no attached resources is a single file. When a page carries images, cast files or example configuration, make it a directory instead, name the page itself index.md, and put the resources beside it — Hugo calls this a page bundle:

hugo new content docs/install.md generates an empty file with front matter from an archetype — see the Hugo documentation — and writing the file by hand works just as well.

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:

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

Let description say in one sentence what the page lets the reader accomplish. It appears on the section index cards, in search results and on social cards. weight decides the sidebar order, and only equal weights fall back to alphabetical order.

The remaining keys are optional — icon, draft, search weight, comment switch, page shell and so on. The full table is in Page parameters.

Heading levels and stable anchors

Start sections at ## in the body and leave # to title. The theme already renders the page heading, so another # in the body produces two top-level headings. The outline in the right column starts at ##, and how deep it goes is decided by Hugo’s markup.tableOfContents — #### on this site.

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

## Prerequisites {#prerequisites}

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

There are two reasons:

• Cross-language alignment. Hugo derives an ID from the heading text, so a Chinese heading yields a Chinese ID: /docs/install/#prerequisites and /zh/docs/install/#前提条件 point at the same semantic place through two different anchors, which no translation audit can compare. Give the translated heading the English page’s ID and both sides share one fragment.
• Link stability. Heading text changes as wording is revised, and a public link should not break with it. An explicit ID is a public route once published; when a rename is needed, leave an empty anchor for the old ID:

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

Writing links

Three forms, for different purposes:

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: links go to Goldmark untouched. External links get no automatic target="_blank"; write HTML where a new tab is needed, or handle it in the site’s own layouts/_markup/render-link.html.

Plain Markdown links are not checked for existence. So:

• Prefer absolute paths for internal links, and grep to replace them site-wide after a restructure;
• When moving a page, add aliases for the old path and update internal links to the new route — do not let an alias carry navigation indefinitely;
• Use ref for a target you are unsure of, and let the build check it for you.

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

A page’s own screenshots go in its page bundle, images shared by several pages go in assets/images/, and large files that need no processing go in static/. All three are written ![alt text](source) in the source, and an attribute line controls caption, size, zoom and numbering — see Images.

Drafts and publishing

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

---
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 excluded too; -F shows those. A production build uses neither switch, and plain hugo publishes only finished content.

OINK’s Markdown extensions at a glance

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:

The few remaining components — badges, keys, file includes, terminal recordings, the Book figure and table family — are shortcodes, with syntax and parameters in Components.

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

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

1. Install Hugo Extended, 0.160.1 at the oldest:

   brew install hugo

2. Clone the documentation site and preview it:

   git clone https://github.com/pgsty/oink.pgsty.com my-docs
   cd my-docs && hugo server

   Tip

   Add -D to preview drafts as well.

What appears at the end of a page

Four blocks are generated by the theme in a fixed order, and none is written in the body:

The action menu beside the title (copy Markdown, edit this page, view history, open an issue, print) is automatic too, and is configured in the same place, Repository links and page info.

To turn one of them off for a single page, use front matter: feedback: false, annotation: false, pager: false, comments: false. The keys are described in Page parameters.

Verify

After writing a page, run a strict build:

hugo --printPathWarnings --panicOnWarning

• The output must end with Total in … and no ERROR and no WARN. A disallowed key on an attribute line, an invalid component parameter, or a ref whose target is missing all fail here naming the file and the line; the theme never degrades silently.
• --printPathWarnings reports two pages resolving to the same output path, which turns up most often in multilingual sites or after changing permalinks.

Then confirm three things in the browser:

1. The page is in the sidebar, in the position weight implies;
2. The right-hand outline lists the ## headings you wrote, and clicking one puts an English anchor in 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).

Related

• Organizing content — how the directory structure decides the sidebar
• Page parameters — the full front matter table
• Components — each component’s syntax and parameters
• Languages — paired bilingual files and fallback for untranslated pages
• Local preview — the hugo server switches worth knowing

3.2 - Organizing content

OINK needs no separate navigation configuration: the directory structure under content/ is 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

A directory is a section (Hugo’s term), the Markdown files inside it are its pages, and a nested directory is a subsection. The sidebar renders that tree level by level, ordered by weight, labelled with linkTitle and falling back to title. The tree on the left comes from this source:

Every directory needs an _index.md

A section index is the _index.md inside the directory (_index.zh.md for Chinese). Without one Hugo still creates the section, but it has no title, description, icon or weight: the sidebar row shows the directory name and the ordering is out of your control.

---
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 has one further power: cascade pushes shared settings down the whole subtree once, instead of repeating them on every page.

---
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 are sorted by ascending weight, and only equal weights fall back to date and linkTitle. Always use multiples of 10 (10, 20, 30) so a page can be inserted between two others without touching the rest. 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 drifts as content changes, so give every page a weight.

Single file or page bundle

A page with no resources of its own is a single slug.md. A page carrying images, cast files or example files becomes a directory with an index.md and the resources beside it. 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:

params:
  ui:
    section_index: cards # list | cards

list is the theme default — 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:

section_index: list
cascade:
  section_index: list   # and its descendant sections too

Two page-level switches are independent of the style: simple_list: true renders a compact bulleted list, and no_list: true generates no index at all, for a page whose body writes its own navigation.

Sidebar icons

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

icon: fa-solid fa-cloud-arrow-up

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

params:
  ui:
    sidebar_icon_policy: groups # all | groups | none

A new site is better off writing groups explicitly: the semantic markers on groups stay and the leaf-level icons go. This site uses that setting, so only the six sections on the left carry icons.

Expanding and folding

A section with children carries a fold arrow in the sidebar, and the reader’s expansion state is kept locally. The default behaviour: the path containing the current page is expanded and everything else is collapsed; blog-type sections are expanded by default.

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

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

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:

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:

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

Multiple sidebar roots

By default the sidebar tree roots at the top-level section the reader is in, and a row above the tree names the current root. A large subtree can become a root of its own — a versioned API reference, say, or a self-contained handbook:

---
title: API reference v2
sidebar_root_for: self   # self | children
---

The switcher above the root is site-wide: it lists every top-level section plus every section anywhere that declares sidebar_root_for: self. With only one entry it degrades to a plain link; two or more make it a dropdown. To keep a top-level section out of the switcher, write sidebar_root_menu: false in its _index.md.

Below the switcher, the section index remains the first link in the tree: the switcher picks a tree and the root link points at a document. sidebar_root_link_self: false makes that row point at the parent section instead.

Verify

hugo --printPathWarnings --panicOnWarning

It must reach Total in … with no ERROR and no WARN. --printPathWarnings reports two pages resolving to the same output path, which happens most often while changing the directory structure.

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. That warning cannot be ignored: truncated entries never appear in the sidebar.

Related

• Writing pages — how to write a single page
• Page parameters — the full definition of every front matter key used here
• Layouts and page types — site-level shell, sidebar and table-of-contents settings
• Navigation and menus — the navbar menu, breadcrumbs and pager
• Languages — keeping a bilingual tree consistent

3.3 - Page parameters

This page is the complete table of page-level parameters, listing only the keys the OINK theme reads. Hugo’s own front matter fields (slug, url, build, sitemap, expiryDate and the rest) work as usual; their meaning is in 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 (when several cascade layers set the same key, the one closest to the page wins);
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.

Page keys are written at the top level of the front matter, and the key name is the site key with its ui. prefix dropped: the site’s params.ui.section_index is the page’s section_index. Front matter never carries a ui: block; the keys sit at the top level. A ui: block written there is not read and not reported, so check the key name against this page when a setting seems to have no effect.

---
title: Compatibility matrix
weight: 40
page_width: wide
footer_style: slim
image_zoom: true
section_index: list
---

Inside a cascade the key names are unchanged, just one level deeper:

cascade:
  pager: false
  section_index: list

An invalid value does not stop the build. The theme warns — naming the key, the value it got and the fallback it used — and renders the page with the default in the table, so one typo degrades one setting instead of serving HTTP 500 on every URL under hugo server. It still never ships: every publishing gate builds with --panicOnWarning, which turns that warning back into a hard failure where it counts.

A few keys do stop the build, and their rows say so. They are the ones where carrying on would publish something wrong rather than merely plain: an incomplete upstream attribution (a partial notice reads exactly like a complete one), translation_notice, the release facts, landing sections, and any reference that cannot resolve.

Basics

Sidebar and navigation

The guide is Organizing content.

Page shell

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

Search

The guide is Search.

Output formats

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

Page end: comments, feedback and provenance

The order is fixed as feedback → provenance → pager → comments; see Writing pages.

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 licence 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, so the most specific declaration wins.

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. Any companion key without upstream_link fails the build.

Missing any one of the four required keys (upstream_name, upstream_copyright, upstream_license, upstream_notice) fails the build: a partial attribution is worse 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

Blog posts

The guide is Blog posts.

Book

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

Landing

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

Release pages

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

Related

• Writing pages — the handful of keys every page needs
• Organizing content — what the sidebar and navigation keys actually do
• Configuration — the full table of site parameters in hugo.yml

3.4 - Blog posts

A blog post’s body is written exactly like a documentation page; the shell is what differs. A post carries a date, an author, tags and a featured image, the list is grouped by year newest first, and the section has an RSS feed. This page covers creating the blog section, a post’s front matter, featured images, list 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. Do not create year directories: the year grouping is generated by the list page.

The section root pushes the type down the whole subtree and sets the behaviour that section shares:

---
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; giving one post a weight pins it to the top.

A post’s front matter

---
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 ordering and grouping
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, its year group and its RSS timestamp. A date in the future is not built by default; hugo server -F previews it.
• description is rendered as a standfirst above the body, not only as a search snippet, so write it as 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 instead; the two do not interfere, and a post keeps rendering author wherever 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; commit IDs, version numbers, commands and URLs are not.

Featured image

Each row on a list page or a tag page has a thumbnail on the left, resolved in this order, first match winning:

1. images in the post’s front matter, first entry;
2. An image resource in the page bundle whose filename contains featured (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:

cascade:
  images: [/images/releasenote.webp]

To drop the image on one post, write images: [] in its front matter; to drop it for a whole subsection, put images: [] in that level’s cascade. The site-level params.images is unaffected — it 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, and the article itself shows nothing — write the hero by hand and it will disagree with the card sooner or later. params.ui.featured_image renders it from the same resolver instead:

params:
  ui:
    featured_image: banner

The page key is featured_image, so a cascade on one subsection turns it on for that tree and a single post can opt out. A post with no image renders nothing in either mode, which is why a section can carry the switch for a run of posts that do not all have art. Neither mode adds a script or a bundle member.

cascade:
  featured_image: wash

List pages and pagination

After the body of the section _index.md, the theme appends the post list: grouped by year (“Posted in 2026”), years newest first, each row showing the title, date, subsection, tags, thumbnail and the first 250 characters of the body as a summary.

Pagination uses Hugo’s native paginator, ten posts per page by default, adjusted in hugo.yml:

pagination:
  pagerSize: 20

The values and the remaining pagination options are in the Hugo documentation.

The card form

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

params:
  ui:
    blog_index: cards
    blog_index_columns: 3

The choice is presentational only — year grouping, pagination and manual_link behave identically, and the row output is unchanged to the byte. The column count applies above the xl breakpoint; between md and xl the grid is two columns and below md it is one. Front matter blog_index on a blog root, or its cascade, sets it per section. Term and taxonomy pages keep the row list, and there is no reader-side switch between the two forms.

Card images go through Hugo’s .Fill whenever the resource can be processed, so a grid of posts does not download a full-size original per card.

RSS

Which pages produce a feed is decided by outputs. Adding RSS to section gives every section its own feed:

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

Writing outputs at all replaces Hugo’s defaults wholesale, so RSS has to be written back explicitly. Omitting it turns off the feed for that page kind, and the build does not complain.

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, so subscribing to /blog/ covers everything. 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 a reader need not assemble the address by hand.

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

disableKinds: [RSS]

Components degrade to their static shape 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

Declaring the taxonomy is the entire switch; the theme adds no parameter:

taxonomies:
  category: categories
  tag: tags
  author: authors

A post then names its authors in order:

authors: [vonng, ada-example]

The article head renders portraits and linked names in exactly that order — the front matter sequence is both the set and the order — a list row renders the names, and the blog feed emits one <dc:creator> per author per item beside the site-level managingEditor. Names are separated by a CSS gap rather than a connector word, because “and” is a per-locale decision and there are 32 locales.

An author’s profile is simply the term page, so there is no data/authors file to disagree with it:

---
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 — linkTitle when it has one, title otherwise — so a profile can carry a full name and byline a short handle. description is the one-line introduction, the body the long one, and the avatar is whatever the featured-image resolver selects for that page — so images: and a bundled portrait follow the same rules an article’s own image follows. A bilingual profile is an _index.zh.md beside it. A name a post uses but nobody gave a profile page still bylines: the link title, an initial, and a link to its archive.

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; this is the lighter thing. Declaring the taxonomy is again the whole switch:

taxonomies:
  series: series

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

series: [shell-internals]
series_weight: 20

It then carries a strip above its body naming the series, its position, the next part, and the whole list behind a <details> — no JavaScript, no bundle member. The term page content/series/<name>/_index.md is the introduction, and an _index.zh.md beside it makes the pair bilingual.

Reading order is the theme’s own, because a term page cannot supply one: Hugo’s taxonomy weight reaches neither Page.Weight nor GroupByParam. Weighted members come first in ascending series_weight, the rest follow by ascending date, and Path breaks a tie. The strip and the term page read the same resolver, so they can never disagree about which article is part 2 — which also means a series term page lists oldest-first rather than newest-first, unlike every other term page. That is the feature.

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:

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 absent on purpose: it publishes no share-intent URL at all, so copy stands in for it rather than the theme guessing at 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:

cascade:
  share: [x, bluesky, email, copy]

Only a regular page renders the bar — a list, a term page and the home page have no single thing being shared — and print, Markdown and RSS carry none of it.

What the bar does not do is why it can ship in this theme at all. There is no share count, no platform SDK, no iframe, and no third-party script or stylesheet, which is what those three usually arrive as: one request per page to a company the reader never chose. Every target is a plain <a href> intent link carrying only the page’s own permalink and title, with no campaign parameters, plus one local copy button. Nothing is fetched when the site builds or when the page loads; the only request a share can cause is the navigation the reader starts by clicking. A build with every target enabled passes bin/check-output-security.py with no --third-party allowance.

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, which means the Command Palette carries it on every page of every site whether or not a bar is configured.

Verify

hugo --printPathWarnings --panicOnWarning

It must reach Total in … with no ERROR and no WARN. Then confirm:

1. The post appears under the right year group 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.

Related

• Writing pages — how to write the body
• Page parameters — the full definition of author, images and the rest
• Organizing content — directories and the sidebar
• Taxonomies — tags and categories
• Releases and downloads — version cards and asset tables

3.5 - Books

A book is a content tree of type: book: the directory decides chapter order, front matter decides chapter numbers, and figures, tables, equations and examples each carry a hand-written number and a stable anchor. Cross-references resolve in all four outputs, and the book’s root page can generate a whole-book print HTML.

Two prerequisites: the site’s markup.goldmark has attribute lines and passthrough enabled (see Components); and params.ui.shell_types still contains book (the theme default includes it).

A book’s directory

The book root is an ordinary Hugo section, chapters are its subdirectories, and sections are the pages inside a chapter. There is no second chapter list: the sidebar, the pager and the generated contents all read this one tree.

Chapter numbers are written by hand: book_number displays exactly what you write, and the theme never numbers by directory order. The num on a figure, table, equation or example works the same way — a string the author controls (2-1, 5.3 and A-2 are all valid), not an index computed at render time. Rearranging the tree therefore never shifts 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:

---
title: The PostgreSQL operations handbook
type: book
book_number: B
cascade:
  type: book
outputs: [HTML, print, markdown]
---

A book that is a section maps to Hugo’s section output kind; home applies only when the book sits at the site root:

outputs:
  section: [HTML, print, markdown]
params:
  ui:
    sidebar_headings: 3     # project an h2–h3 heading tree under 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:

---
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 accepts false, true (h2 only) or a maximum level from 2 to 4. Give every heading that will be referenced an explicit ID, such as ## Synchronous replication {#sync-replication}: a generated slug is fine for navigation and unfit as a long-lived 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: one Markdown block followed immediately by an attribute line. On that line num= is the number, #id is the anchor, and caption= is a plain-text caption.

Figures

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

![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 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>.

| 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."}

Equations

An attribute line follows a $$ block, and the default ID is eq-<num>. The number and caption sit on one non-wrapping line to the right of the formula, so a long caption squeezes the formula column until it becomes a horizontally scrolling region. Keep an equation caption short.

$$
A = \frac{\mathrm{MTBF}}{\mathrm{MTBF} + \mathrm{MTTR}}
$$
{#eq-2-1 num="2-1" caption="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 written on the fence names the enclosing <figure> — the reference target — rather than the code block itself. The caption is required: writing only num or only caption fails the build. A numbered example renders as one framed unit: the caption is the frame’s header and the body sits inside it, and a body that is exactly one code block sits flush against the frame instead of drawing a second border.

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

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 only where the native form cannot reach: an image that needs an outbound link, several tables under one number, a site without passthrough, or an example body made of several fences and prose.

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:

{{< 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" />}}

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

{{< 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 >}}

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

{{< eq num="2-2" caption="Connection pool saturation." >}}U = \frac{\lambda}{\mu \cdot c}{{< /eq >}}

A bare {{< eq >}} with no parameters is the unnumbered display-maths escape hatch: it registers no target, cannot be reached by xref, and 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:

{{< 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 >}}

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 exactly one ID. A duplicate fails the build, and the error names the line that claimed it first.

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. The cost is that the label and the number are hand-written, so changing a number means finding them yourself.

xref composes the label, the number and the anchor in one place, and works across pages and languages:

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, so 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.

{{< 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 as source only. They walk down from the navigation root the current page belongs to, so placing one in an ordinary documentation tree 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 the docs, book and blog types, and its order is a pre-order walk of the sidebar tree: a section index first, then its children by weight. Turn a whole type off with params.ui.pager_types, and a single page off with pager: false.

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:

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 IDs within a page are prefixed with their source page to avoid collisions when several chapters share an anchor such as summary, and the generated heading links are rewritten to match. The output is print-oriented HTML; PDF and EPUB are the site’s own business.

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.

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:

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 determine uniquely: where the number is unclear, the caption is not unique, or the marker form is unrecognized, the text is left as it stands and recorded in skipped for a human. 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:

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 read files_changed: 0, an 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. The build is warning-free: hugo --printPathWarnings --panicOnWarning. A malformed number, a duplicate ID and a missing caption all fail here.
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 worthy of its caption.

Book shortcode parameters

xref: