OINK Documentation

• 1: What is OINK
  • 1.1: Highlights
  • 1.2: Case Guide
  • 1.3: License and acknowledgements
  • 1.4: Contributing to OINK
• 2: Get started
  • 2.1: Use OINK Starter
  • 2.2: Starter repository tour
  • 2.3: 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: Image albums with Expo
  • 3.7: Releases and downloads
  • 3.8: 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: Component presentation
  • 4.13: PlantUML
  • 4.14: Markmap
  • 4.15: Draw.io
  • 4.16: ECharts
  • 4.17: Infographic
  • 4.18: Gallery
  • 4.19: Badge
  • 4.20: Kbd
  • 4.21: Includes
  • 4.22: 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: Expo layout contract
  • 7.6: OINK migration boundary
  • 7.7: Design decisions
    • 7.7.1: Warnings and safe fallbacks
    • 7.7.2: Configuration model
    • 7.7.3: Markdown-first authoring
    • 7.7.4: Generated configuration schema
    • 7.7.5: Optional CLI and result contract
    • 7.7.6: Component refinement across four visual presets
    • 7.7.7: Paper and Slate visual presets
    • 7.7.8: Expo image collections
    • 7.7.9: Blog posts as a gallery
    • 7.7.10: Explicit table reading
    • 7.7.11: Translation comparison
    • 7.7.12: Unified diagram reading
    • 7.7.13: Local search refinement
  • 7.8: Design research
    • 7.8.1: Goldmark block-attribute evidence
    • 7.8.2: OINK 1.3.2 and Hugo 0.168 consumer inventory
    • 7.8.3: Ink and Terminal experiment, 2026-10-05
    • 7.8.4: OINK 1.2 pre-release review, 2026-10-05
    • 7.8.5: Visual preset acceptance, 2026-10-05
    • 7.8.6: Consumer and migration evidence
    • 7.8.7: OINK comprehensive review, 2026-08-26
    • 7.8.8: Community issue and PR review, 2026-09-19
    • 7.8.9: OINK 1.1 release review, 2026-09-20
    • 7.8.10: CLI maintenance acceptance on 2026-10-03
    • 7.8.11: CLI maintenance acceptance on 2026-10-03: R1–R5
    • 7.8.12: CLI maintenance acceptance on 2026-10-03: R6–R8 and A18
    • 7.8.13: Document comparison research, 2026-10-29
    • 7.8.14: CLI acceptance snapshot, 2026-09-29
    • 7.8.15: Component refinement, 2026-10-25
    • 7.8.16: Review repairs, 2026-11-06
    • 7.8.17: Ink and Terminal need reading acceptance
    • 7.8.18: OINK 1.5.1 readiness review, 2026-11-06
    • 7.8.19: Theme review, 2026-10-13
    • 7.8.20: Give large tables room to read
  • 7.9: Design proposals and PRDs
    • 7.9.1: Backlinks and knowledge graph
    • 7.9.2: Media convergence
    • 7.9.3: OINK CLI and the next product stage
    • 7.9.4: OINK CLI maintenance roadmap
    • 7.9.5: Visual presets and appearance switching
    • 7.9.6: Stabilizing Ink and Terminal for reading
• 8: OINK CLI

1 - What is OINK

OINK is a standalone Hugo theme for medium and large technical documentation sites. It evolved from Docsy, retaining the content model and multilingual behavior while replacing the shell, navigation, search, and content components.

The current release is OINK v1.5.1, built with Hugo Extended 0.168.0 (with its built-in Sass compiler), plus Go when resolving the theme as a Hugo Module. No Node.js, npm, PostCSS, or CDN requests are needed: Bootstrap, Font Awesome, fonts, local search, diagram runtimes, and API reference runtimes all ship in the theme repository and load only on pages that use them.

Components are written in clean Markdown rather than a custom template language: > [!NOTE] creates a callout, a table followed by {.fields} renders as a parameter list, and an image followed by {caption="..."} becomes a captioned figure. Fifteen production sites run on OINK today, including this one.

What the theme provides

• The documentation and blog shell provides navigation, a sidebar tree, a table of contents, breadcrumbs, a pager, dark mode, print view, and accessible interaction.
• The multilingual structure provides translation routing, fallback for untranslated pages, language weighting, RTL, 32 complete interface catalogs, and an opt-in duo view (params.ui.compare: true) for side-by-side reading.
• Local browser features include Mermaid, Markmap, Swagger UI, Redoc, Asciinema, ECharts, Infographic, and full-text search. Mathematics is rendered by Hugo at build time and uses local KaTeX styles.
• Content components include callouts, tabs, steps, cards, field lists, file trees, galleries, badges, keys, and more. Most have a native Markdown form.
• Additional content types provide 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 use GitHub, GitLab, or a private Git server. You can publish Hugo’s static output anywhere. The site owns its content, brand, and business components. The theme supplies the shell and reusable components.

Is OINK for me

How it differs from other documentation systems

Choose a toolchain and authoring model before comparing individual features. Different systems can suit the same project. The choice depends on who maintains it:

Check each candidate’s current installation and extension documentation. OINK’s search, image zoom, comments, and feedback require explicit configuration. The site also selects Markdown and agent outputs under outputs.

OINK forked from Docsy and evolved as a separate theme. It retains Docsy’s source history, Apache-2.0 obligations, and attribution. For details, see License and acknowledgements.

Start here

• Get started — Use the official Starter. Customize one part at a time, then publish it.
• Components — Each component has one page. The source appears first, followed by the rendered result.
• Showcase — See fifteen production sites and the OINK features each site uses.

Highlights lists each theme capability. Each entry links to its guide.

To report a problem or submit a correction, follow the contribution guide. The 1.5.1 release notes cover Duo View repairs, output correctness, responsive reading, and the current build requirements.

1.1 - Highlights

This page lists the differences between OINK and an ordinary Hugo theme. Each item links to its guide. To install OINK now, 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 use adjacent fences, each with a {tab="…"} attribute. File trees, galleries, Mermaid, and ECharts use data fences named after their language. On GitHub or in a plain Markdown reader, these appear as blockquotes, tables, lists, and code blocks. They retain all content.

29 shortcodes provide forms that native Markdown cannot express. These include cards with icons and images, and field entries with several Markdown paragraphs.

→ Components

Build with Hugo

Hugo Extended 0.168.0 or newer compiles the site’s assets. SCSS is compiled by Hugo’s embedded Sass transpiler. The theme never invokes postCSS. It requires neither npm nor webpack. Installing the theme as a Hugo Module also needs Go and access to the module dependencies, either over the network or from a local cache. With an offline archive or a submodule already prepared, Hugo Extended builds the site without Go or an external Sass compiler.

The interface runs JavaScript in the browser: search, the command palette, diagrams and tabs are page scripts. The theme includes those scripts. Each page receives only the scripts it 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, and the local PlantUML engine. VENDOR.json records the version, source, license file and SHA-256 checksum of each dependency. When you update a runtime, update its artifact, license, and checksum together.

Features that could make network requests require explicit configuration. OINK 1.4.0 renders PlantUML in the browser when enabled without an endpoint; an explicit endpoint keeps server mode. Without params.drawio.drawio_server, Diagrams.net warns and stays disabled. Without appId / apiKey / indexName, Algolia warns and stays disabled.

Local-first does not cover content that an author adds. Explicit network choices include external links, remote images and video, iframes, and remote API specifications. They also include hosted search, such as Algolia or Google Programmable Search, and analytics, comments, or other SaaS integrations. PlantUML and Diagrams.net use the network if the author configures a remote renderer. Pages that enable these features require network access at runtime.

→ License and acknowledgements · Configuration

One source, four outputs

Every component has a defined form in four outputs: interactive HTML, print, plain Markdown, and RSS. Print pages omit zoom and copy controls and fully expand disclosures. 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.

Select the site’s output formats under outputs. The theme does not select them for the site.

→ 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 235-message schema. These include all 31 locale filenames that Docsy supports, plus generic zh. Every pack contains native OINK interface text instead of English placeholder blocks. zh and zh-cn use Simplified Chinese. zh-tw uses Traditional Chinese. Setting params.ui.compare: true adds an opt-in duo view so readers can open an existing translation beside the current page and scroll both versions together.

→ Languages · Duo view

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. It sends no query to 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. A bare \ enters command-only mode. The palette contains pages, commands, and page actions, such as switching language, switching theme, and copying Markdown. Use the same entry point to search and run actions.

→ Command palette

Keyboard navigation

Keyboard navigation is on by default. You can turn it off per site or section. w and s move up and down the sidebar tree. a and d collapse and expand it. q and e go to the previous and next page. j and k move through the page’s table of contents. t toggles light and dark mode. l switches language. b opens or closes the duo view when a translation is available. h hides the reading shell. Single-key shortcuts are inactive while an input or textarea has focus, or while an input method is composing. The question-mark button in the footer’s bottom bar opens the cheatsheet.

→ Keyboard navigation

Backlinks

Turn on params.ui.backlinks to list the pages that link to each page. Hugo derives the list at build time from ordinary links. This requires no new syntax and no JavaScript. This site enables backlinks site-wide. See the “Linked from” group in this page’s right rail. More references produce a longer list. The list collapses when it has more than eight entries.

→ Backlinks

Four content types beyond documentation

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

• Books provide chapter numbering. Use {#id num=} to number figures / tables / equations / examples and xref to reference them. book-toc, book-figures, and related shortcodes generate indexes. You can print the whole book.
• Release and download pages use data/download/*.yaml to produce release cards, asset tables, and checksums. The data controls publication state.
• Landing pages use data/home/<lang>.yaml to assemble home-page sections. Any page with layout: landing can use data under data/landing/.
• API references use the local Swagger UI and Redoc runtimes. The specification can reside on the site.

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

Output for AI assistants

Add markdown to outputs. Each page then has a .md version. Its HTML <head> has a rel="alternate" reference to that version. Page actions include “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).

0.8.0 adds two more outputs. A section that enables LLMSFULL produces one llms-full.txt file. An agent can fetch it in a single request. A site that enables NAVJSON publishes navigation.json per language. This file represents the sidebar tree as data. Both are live on this site: https://oink.pgsty.com/docs/llms-full.txt and https://oink.pgsty.com/navigation.json are the real artifacts.

“Open in ChatGPT / Claude” is off by default. Clicking it sends the current URL to a third party. The site must turn on params.ui.page_context_menu.assistant_links explicitly.

→ AI-agent support

Versions

Configure params.versions to add a version menu to the navbar. An archived version shows a banner that links to the current version. The site chooses whether the menu links to corresponding pages. Each version is a separately built and deployed static site. No runtime service is required.

→ Versions

See for yourself

This site enables most of these features. Use these four checks:

1. Press Cmd/Ctrl + K on any page. 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 for AI assistants. It links to the docs section’s llms-full.txt and to navigation.json.
4. Look at this page’s right rail. “Backlinks” lists the pages that link here.

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 Case library describes fifteen OINK site projects and their implementation patterns, including this documentation site. Case pages link to the live result or project source. Where a pattern needs custom implementation, they distinguish site-owned code from theme features.

If you know the type of site you want to build, use this guide. Read a case to understand its architecture and trade-offs. Then use the linked documentation for exact configuration. Counts in each case reflect the audited snapshot.

Distribution documentation

pigsty.io

This very large English site combines a distribution manual, editorial blog, extension catalog, taxonomies, version navigation, and pricing landing pages.

pigsty.cc

This Chinese peer is deployed as an independent single-language site. This approach is useful when each language corpus has become a separate product.

pgsty.pro

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

Product documentation

PIG

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

SOW

This bilingual operations manual has a dedicated download content type that uses release metadata.

SILO

This large upstream migration uses a checked manifest to generate bilingual documentation navigation.

PG Exporter

This metrics manual combines generated navigation, a structured catalog, and system fonts.

Books

Designing Data-Intensive Applications

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

The Product-Minded Engineer

This focused bilingual publication needs only OINK’s Book shell.

PG Internal

This finished Chinese translation is deliberately published as a single-language Book. It has no documentation tree or other language to select.

Aggregate, landing, and custom sites

PostgreSQL ecosystem library

This aggregate operations library combines several upstream manuals and partially translated language trees. They share one search and visual system.

pgsty.com

This small bilingual corporate site shows how OINK can primarily serve as a data-driven landing-page system.

Capslock

This project has two pages per language. Its custom shell hosts an interactive, data-driven configuration generator.

oink.pgsty.com

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

pgext.cloud

This PostgreSQL extension catalog uses a queryable dataset as its primary object. It indexes 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 PostgreSQL ecosystem library.
• 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. Do not use it as a starter template. Its pages test rendering behavior. Use the production cases above as design references.

→ Browse all cases · Quick start · Repository tour

1.3 - License and acknowledgements

OINK contains three types of material: theme source, documentation content, and bundled third-party assets. These materials are not relicensed as a single combined work. Each table below links to the authoritative repository file. If a summary disagrees with the license text, the file is authoritative.

Which licence covers what

CC BY 4.0 covers only the original documentation content. It does not cover theme code, trademarks, screenshots, or third-party assets. The theme’s Apache-2.0 license does not change the licenses of its bundled dependencies.

Community contributors

OINK is maintained by PGSTY. Thank you to @imbajin for reporting and contributing the following reading repairs, with fixtures, regression tests, and bilingual docs. Introduced in 1.3.1, these fixes remain included in 1.5.1.

The release notes record the integration details. To contribute a correction, translation, or fix, follow the contribution guide.

Upstream: Docsy

The theme’s NOTICE records these facts:

• 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 both use Apache License 2.0. VENDOR.json records each third-party browser dependency’s license, source, version, and checksum. Each required NOTICE file accompanies its asset.
• The Docsy name and Google’s trademarks belong to their respective holders. These names identify the upstream project and imply no endorsement.

This site also derives from the Docsy project website. The site’s NOTICE records that origin. Docsy is OINK’s only code upstream. OINK retains its source history, Apache-2.0 obligations, and copyright notices. Modified files carry a modification notice, as Apache-2.0 requires.

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/). These assets need no npm step or build-time download. Hugo Module resolution still needs Go and an available module source. VENDOR.json is the machine-readable manifest for these assets. Each entry records the name, pinned version, source URL, license file path, and SHA-256 of every selected artifact. It also records an aggregate checksum for each of the three asset trees.

The table below matches the OINK v1.5.1 manifest (VENDOR.json generated 2026-10-25, schema 1, 29 entries). Versions change with each theme release. Use the manifest from your pinned theme version. Every source is the npm registry (https://registry.npmjs.org/…).

License texts accompany their assets. Examples include assets/third_party/bootstrap/LICENSE and assets/third_party/katex/LICENSE. Swagger UI, Redoc, and ECharts also include their own NOTICE or bundled-declaration files. Lunr is the only exception. Its code is in assets/js/third_party/. Its license is at assets/third_party/lunr/LICENSE.

The OINK 1.4.0 local PlantUML integration adds @plantuml/core 1.2026.9 (MIT) and Viz.js 3.24.0 (MIT), including Graphviz 14.1.1 (EPL-1.0) and Expat (MIT). Their notices and upstream source links accompany the two scripts in assets/third_party/plantuml/; VENDOR.json records the exact artifacts.

When you redistribute the theme, include all this license and notice material. When you update a runtime, update its artifact, license file, source, and checksum in the same change.

Fonts and icons

Inter, IBM Plex Sans, Chakra Petch, and IBM Plex Mono use the SIL Open Font License 1.1. OINK 1.5.1 includes 33 files under static/webfonts/: fourteen Inter subsets, twelve IBM Plex Sans subsets, four brand-font files, and three Font Awesome files. Font Awesome Free 7.3.1 uses a composite license. Its icon artwork uses CC BY 4.0, its font files use SIL OFL 1.1, and its code uses MIT. The text is in assets/third_party/Font-Awesome/LICENSE.txt.

The theme makes no request to a remote font service. The repository has no Google Fonts link. The site always serves fonts from its 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 supply no code or runtime dependencies. 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.

These names describe origin, dependency, or design references. They imply no endorsement by these projects. Project and product names belong to their respective holders.

Reusing this documentation

CC BY 4.0 permits sharing and adaptation for any purpose under these conditions. Give attribution, link to the license, and state whether you made changes. Do not imply endorsement by OINK, PGSTY, or any upstream project. This attribution is sufficient:

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

Images or quotations with their own attribution keep their own credit and license. Removing the footer does not remove the attribution obligation.

Reusing the theme

Apache-2.0 permits using, modifying, and distributing the theme source and build output under its terms. Keep the license, copyright, and attribution notices. Keep the contents of NOTICE. When you distribute modified source, state which files you changed. 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. It does not change third-party assets into Apache-licensed works.

Related

• Contributing — report problems, improve docs, and submit fixes
• 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

1.4 - Contributing to OINK

Corrections, translations, bug reports, and focused pull requests are welcome. OINK v1.5.1 is the current theme release. Its release notes describe Duo View repairs, publishing correctness, responsive reading, and accessibility.

Where to contribute

The CLI has its own version and release cycle. Ordinary Hugo consumers do not need it. Report a problem in the repository that owns the affected behavior.

Report a reproducible problem

Include the OINK version, hugo version, Go version for module builds, relevant configuration, and a minimal content example. For display problems, include the page, viewport width, browser, visual preset, and light/dark setting. Describe what you expected and what happened. Remove credentials and private content from reports and reproductions.

Build and check

The maintained baseline is OINK v1.5.1, Hugo Extended 0.168.0, and Go 1.27.3; the module’s Go minimum is 1.27.3. Hugo uses its built-in LibSass. Ordinary site builds require no external Sass compiler, Node.js, or npm.

Never enable --panicOnWarning or HUGO_PANICONWARNING. Keep warnings visible and review them; the upstream LibSass deprecation warning is accepted. Development and CI use the pinned Hugo baseline, without a legacy-version matrix.

For theme work, clone the theme and this site as siblings. Read each repository’s AGENTS.md, this site’s TRANSLATION.md, and the relevant Design contract. This site’s regression tests need Node >= 24 and npm >= 11.16.0:

npm ci
make check
make browser

Run the smallest owning checker first. make check runs the non-browser suite against the sibling theme; use make browser for changed rendering or interaction. Review affected English and Chinese pages at desktop and mobile widths in light and dark mode. The repository README also explains how to verify the published pin separately.

Prepare a pull request

Keep the change focused and describe the problem, resulting behavior, and validation. Update English and Chinese peers together and preserve stable heading IDs. Public theme changes need the implementation, owning checker, and both language versions of the affected contract. New design proposals belong in the bilingual Design proposals section.

Preserve unrelated changes in shared worktrees. Commit source and reviewed test expectations; keep generated output, caches, binaries, and filesystem module replacements out of Git. Keep historical release notes and dated research faithful to their original evidence.

Credit and licences

The acknowledgements link community fixes to their authors and pull requests. The 1.3.1 notes record the recent reading repairs; 1.5.1 keeps those fixes and the Hugo-only build restored in 1.3.2.

Theme code and site tooling use Apache-2.0; original documentation uses CC BY 4.0. Retain third-party licence and notice files. See License and acknowledgements for the full scope.

2 - Get started

For a new site, start from pgsty/oink-starter, a public GitHub template that pins a published OINK release, builds out of the box, and includes neutral project content and deployment workflows without this repository’s regression test harness.

Choose a path

Five-minute baseline

1. Install the tools

   Install Git, Go 1.27.3 or newer, and Hugo Extended 0.168.0 or newer. The Hugo output must contain extended:

   $ go version
   go version go1.27.3 darwin/arm64
   $ hugo version
   hugo v0.168.0+extended+withdeploy darwin/arm64
   

   On macOS, brew install git go hugo supplies them. On Linux and Windows, use the official Hugo installation guide and Go downloads. Choose Hugo Extended.

2. Create or clone the site

   If you intend to keep the repository, open the Starter and select Use this template. Then clone the repository that GitHub creates. To evaluate the original without changes, use these commands:

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

3. Open the baseline

   Open http://localhost:1313/. The default Starter also publishes Chinese at /zh/ and French at /fr/. Confirm that Docs, Blog, Book, search, language switching, and light/dark mode all work before editing anything.

4. Make one visible change

   Change the title and canonical URL at the top of hugo.yaml, then edit one sentence in data/home/en.yaml. Reload the browser. If both changes appear, configuration, content, and the pinned theme are connected correctly.

Customize from shallow to deep

• Use OINK Starter — choose languages first, then identity, home page, content, navigation, brand, integrations, and deployment.
• Starter repository tour — which file owns each part of the site, what to replace, and what can be removed.
• Writing pages — front matter, headings, links, images, drafts, and the page-end controls.
• Components — add expression only after the content tree is stable.
• Brand and appearance — logo, accent, typography, width, and CSS extension points.
• Deploy — use the supplied GitHub Pages or Cloudflare Pages workflow, then verify the real public routes.

Verify the build and content tree before customizing languages, navigation, CSS, analytics, and hosting; changing one layer at a time makes failures easy to isolate.

Publication gate

Before your first push, run the same production build command used by the Starter workflows:

hugo --cleanDestinationDir --gc --minify --environment production \
  --printPathWarnings

Confirm that the build exits cleanly with Total in … and that public/ contains the language roots along with representative Docs, Blog, and Book routes. Keep warnings visible for review and do not enable --panicOnWarning or HUGO_PANICONWARNING (Hugo’s built-in LibSass deprecation notice is expected). After pushing, check the CI workflow and the live URL as well.

Build with an AI agent

OINK publishes an agent skill, Oink 建站 (oink-site): one Markdown file that packages the site-building workflow, the review standards of OINK’s own sites, and lessons from the case library. It defers to this documentation for syntax and asks the agent to verify its work in a browser.

• English: https://oink.pgsty.com/skill.md
• 简体中文: https://oink.pgsty.com/skill.zh.md

Save it as a skill, then start a new agent session:

mkdir -p ~/.claude/skills/oink-site
curl -fsSL https://oink.pgsty.com/skill.md -o ~/.claude/skills/oink-site/SKILL.md

mkdir -p ~/.codex/skills/oink-site
curl -fsSL https://oink.pgsty.com/skill.md -o ~/.codex/skills/oink-site/SKILL.md

Then describe the site you want, for example “Use the oink-site skill to build a bilingual documentation site for this project.” An agent without a skills directory can follow the file directly when you give it the URL. Run the download again to update; the file states the OINK release it was written for.

Next

Start with the complete Starter tutorial. If the template has more structure than your project needs, use the repository tour to remove it safely. Use From scratch only when adding OINK to an existing site or when you explicitly want to assemble every file yourself.

2.1 - Use OINK Starter

pgsty/oink-starter is the official template for new OINK sites. It stays lean and clean, without this site’s theme reference docs, analytics IDs, comment repo settings, browser test harness, or PGSTY branding.

You only need Git, Go 1.27.3+, and Hugo Extended 0.168.0+ (which includes its built-in Sass compiler — no Node.js or external Sass installation required).

What the template contains

The Starter’s own Book at /book/ is a four-chapter tour from preview to deployment. This page gives maintainers more detail. It explains the order of changes, their boundaries, and the checks after each group of changes.

Create your repository

GitHub template, recommended

Open the Starter repository, select Use this template → Create a new repository, then clone the repository created under your account or organization:

git clone https://github.com/OWNER/PROJECT-DOCS.git
cd PROJECT-DOCS
hugo server

This creates your site’s own Git history. The original Starter remains an upstream reference rather than a remote for pushes.

Clone the original to evaluate it

For a disposable local evaluation:

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

Do not start a real project by deleting this clone’s .git directory. GitHub’s template operation already creates a separate project and preserves an auditable first commit.

Preview before changing anything

Open these routes:

• /, /zh/, /fr/ — the three home pages;
• /docs/, /blog/, /book/ — the three content surfaces;
• one translated page, then the language switcher;
• search and the light/dark control at a narrow viewport.

Also record the resolved module:

hugo mod graph | grep github.com/pgsty/oink

Check the version supplied by your Starter snapshot in go.mod. To use the current release, update it to github.com/pgsty/[email protected] before customizing content:

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

Customize in layers

Layer 1: language profile

The root configuration enables English, Chinese, and French. Before making other configuration edits, choose one of the supplied profiles when that is not your intended language set. Choose one of these commands:

cp examples/hugo.single.yaml hugo.yaml     # English only
cp examples/hugo.bilingual.yaml hugo.yaml  # English + Chinese

These are complete minimal configurations. Copying one replaces the commented integration examples in the root file. Copy it before other changes. If hugo.yaml already contains project changes, merge the languages and disableLanguages sections. Do not overwrite the file.

If you already changed the title and URL in Get started, keep that file. To change the default three-language setup to English and Chinese, add only disableLanguages: [fr] at the top level. For English only, use [zh, fr]. This preserves the identity and integration settings you have already changed.

Disabled languages stay declared so Hugo recognizes .zh.md and .fr.md as translations and safely ignores them. If you remove a language permanently, remove its content and home data only after the selected profile builds.

Layer 2: identity

Change the two marked values at the top of hugo.yaml:

title: &siteTitle Project Name
baseURL: https://example.org/

The YAML anchor carries the title to all enabled languages. Then change the copyright holder and, after the new repository exists, uncomment its links:

params:
  copyright:
    authors: '[Project contributors](https://example.org/community/)'
    from_year: 2026
  github_repo: https://github.com/OWNER/PROJECT-DOCS
  github_branch: main

Run hugo server again and check the browser title, footer, edit/history links, and canonical URL. Change the logo only if the project has final artwork. Review the text identity first.

Layer 3: home page

Home-page content lives in language data files under data/home/:

data/home/en.yaml
data/home/zh.yaml
data/home/fr.yaml

Edit one language first. In each file, sections sets the section order while hero, cards, and cta supply the content. Replace the tagline, destination URLs, and sample card text while keeping the structure intact, then translate the updated copy into each enabled language.

For additional section types, see Home and landing pages. The theme renders these data files directly—no layout override is needed.

Layer 4: content and navigation

Rewrite or remove sample leaf pages under content/. Keep section roots until you decide whether that whole surface belongs in your project:

content/docs/  reference and task documentation
content/blog/  posts, design records, and release announcements
content/book/  a sequential long-form guide

The content tree becomes the sidebar. menus.main on the translated _index roots controls top navigation. Rename Docs, Blog, or Book beside its content. There is no second global menu tree. Keep translated files side by side and give corresponding headings the same explicit IDs:

page.md
page.zh.md
page.fr.md

Follow Organizing content before creating a custom navigation data file. The generated tree is enough for most sites.

Layer 5: brand and reader features

Replace assets/icons/logo.svg and static/favicon.svg when real assets are ready. Then enable the smallest useful configuration changes, one at a time:

params:
  ui:
    theme_color: '#245f94'
    typography: system
    image_zoom: true
    share: [mastodon, linkedin, email, copy]

For custom local fonts, use params.ui.fonts for family names or declare font files in site CSS. For layout, sidebar, search, and component settings, consult the Configuration reference rather than copying the much larger configuration of oink.pgsty.com.

Layer 6: integrations

The Starter leaves repository actions, Giscus, Google Analytics, feedback, and sharing off or commented. Enable an integration only after all of its required facts are known:

• Repository links need the real owner, repository, and branch.
• Giscus needs its repository/category names and immutable IDs.
• Google Analytics needs a project-owned measurement ID.
• Feedback records structured gtag events only if analytics is present.
• Assistant links send the current URL to a third party. They require an explicit policy choice.

An incomplete optional block should remain commented. See Comments, Analytics and SEO, and Repository links for the operating boundary of each integration.

Build and deploy

Local production build

Before enabling a hosting workflow:

hugo --cleanDestinationDir --gc --minify --environment production \
  --printPathWarnings

Keep build warnings visible for review and do not enable --panicOnWarning or HUGO_PANICONWARNING (the upstream LibSass deprecation warning is expected). Commit hugo.yaml, go.mod, and go.sum. Never commit generated public/, resources/, module caches, or a local module replacement.

GitHub Pages

The Starter already contains .github/workflows/github-pages.yaml. In Settings → Pages, select GitHub Actions as the source. A push to main builds with the pinned toolchain, asks GitHub for the correct project subpath, and publishes public/ through the Pages deployment API.

Cloudflare Pages

The supplied .github/workflows/cloudflare-pages.yaml uses Direct Upload. Create a Pages Direct Upload project, add CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN, then run the workflow manually once. Set the repository variable CLOUDFLARE_PAGES_ENABLED=true for automatic deploys, and CLOUDFLARE_SITE_URL when the canonical address is not the default pages.dev domain.

For one project, choose either Direct Upload or Cloudflare Git integration. Do not use both. The complete host comparison and baseURL rules are in Deploy.

Verify and remove samples

Before you declare the site ready, complete these checks:

1. Search for placeholders such as Project Name, example.org, OWNER, and PROJECT, then decide whether each remaining occurrence is intentional.
2. Open every enabled language root and representative Docs, Blog, and Book pages on desktop and mobile.
3. Confirm that language switching opens peer pages rather than the home page.
4. Test search, dark mode, one component, Markdown output, print, 404, canonical URLs, and repository actions.
5. Check the deployed workflow and the public URL separately from the local build.

Delete the sample Book or Blog only after removing its top-menu root and any home-page card that links to it. After you remove each whole surface, rebuild and review the diagnostics. This lets you identify which change caused a failure.

Next

Use the Starter repository tour as a file-level map, then continue with Writing pages and Configuration. For an existing site that should not inherit the Starter’s content model, use From scratch.

2.2 - Starter repository tour

This page walks through the repository layout created from pgsty/oink-starter. go.mod pins the OINK theme as a Hugo Module, and Hugo caches the resolved theme source in the Go module cache rather than copying it into your repository.

Top-level map

Generated public/, resources/, .hugo_build.lock, and module caches contain build state. Git ignores them. They are not source files.

What to change first

What to keep

• go.mod and go.sum pin and verify the template’s selected OINK release. Commit both. Record a later upgrade separately from this baseline.
• The three Goldmark settings in hugo.yaml: native Steps, Cards, Fields, image attributes, and Book targets depend on them.
• outputs: if you remove markdown, LLMS, or print, you remove the corresponding Markdown, agent-index, or print output.
• fetch-depth: 0 in workflows if enableGitInfo stays on. Last-modified and contributor facts require repository history.
• GOWORK: off and HUGO_MODULE_WORKSPACE: off in CI. A developer’s local workspace must not replace the published release under verification.

Optional surfaces

Docs, Blog, and Book are independent top-level surfaces. To remove one safely:

1. Delete its content/<surface>/ tree.
2. Remove any home-page card or link that targets it.
3. Confirm that no other page links to it.
4. Run a build that keeps warnings visible for review. Inspect the remaining top navigation.

Do not delete only translated section roots. This creates language-specific navigation and fallback behavior that can appear to be an error. Remove a surface in all enabled languages or document the asymmetry.

The two configuration profiles under examples/ are optional after the language decision. They are useful references, but the root hugo.yaml is the only active site configuration.

Content and navigation

Under Docs and Book, directory structure and weight form the sidebar and pager sequence. Top navigation comes from menus.main on section roots. A translated root repeats the same identifier, parent, and weight while translating visible labels.

The Starter intentionally demonstrates the Documentation System model:

• Introduction explains what the project does and why.
• Get Started helps a new user achieve a result.
• Tutorial teaches a complete task.
• Reference records exact supported behavior.

Rename or restructure these sections for your project. Keep the learning paths separate. Do not combine every type of answer in one tree.

Language model

English source files end in .md; Chinese and French peers end in .zh.md and .fr.md. Home data uses language keys under data/home/. The root profile declares the languages, their locale, order, and site description.

The single and bilingual profiles keep disabled languages declared. Hugo then recognizes unused suffixes as translations. It does not render several files to one English URL. Copy a profile only before you start project-specific configuration. After that, merge changes manually.

Where OINK lives

Two files establish the module boundary:

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

module github.com/OWNER/PROJECT-DOCS

go 1.27.3

require github.com/pgsty/oink v1.5.1

This example pins the current release, v1.5.1. Check the pin in your Starter snapshot and follow the upgrade guide if it is older.

hugo mod graph displays the resolved version. Production builds use the exact tag in go.mod, while HUGO_MODULE_REPLACEMENTS can point to a local checkout during theme development. Keep local module replacements out of Git.

Deployment files

The GitHub Pages workflow runs automatically on pushes to main. In repository settings, select GitHub Actions as the Pages source. The Cloudflare workflow runs manually, or automatically only after the repository variable CLOUDFLARE_PAGES_ENABLED=true is set. Its required account ID and API token remain repository secrets.

Keep only the workflows for deployment paths you use. For one project, choose either Cloudflare Direct Upload or Cloudflare Git integration. Do not run both as deployment checks.

Safe customization order

1. Prove the untouched preview.
2. Select languages, then change identity.
3. Replace one home page and then its translations.
4. Replace content and verify navigation.
5. Change brand and reader features one group at a time.
6. Enable complete external integrations.
7. Run the production build.
8. Deploy, then verify production independently.

If you own the repository, commit after each group of changes. This lets you identify the decision that caused a regression or needs a rollback.

Verify

hugo mod graph | grep github.com/pgsty/oink
hugo --cleanDestinationDir --gc --minify --environment production \
  --printPathWarnings
git status --short

Confirm that the module graph names the pinned release. The build must succeed and its diagnostics must be reviewed; the upstream LibSass warning is accepted. Git status must contain source edits but no public/ or cache files. Before deployment, open each enabled language root and one route from each of Docs, Blog, and Book.

Related

• Use OINK Starter — the complete layered workflow
• From scratch — add OINK without adopting this content model
• Organizing content — sidebar, pager, and menu authority
• Configuration — every current site parameter
• Deploy — host-specific setup and production checks

2.3 - From scratch and other install methods

This is the manual alternative to the recommended OINK Starter. It builds a minimal site in an empty directory. A small hugo.yml and one hugo mod get command create a single-language site you can preview. You must assemble the home page, example content, deployment workflow, and all component usage yourself.

For an existing Hugo site, use the short integration path below. For an existing Docsy site, see Upgrade.

The second half compares four install methods: Hugo Module, Git submodule, offline archive, and pinned source copy. Current development and builds use Go 1.27.3 and Hugo Extended 0.168.0 (with built-in Sass — no external Sass needed).

Add OINK to an existing site

Work on a branch with the site’s current configuration and content preserved. Skip hugo new site and keep the existing configuration filename.

1. If the site has no go.mod, run hugo mod init with your repository’s module path. Otherwise keep the existing module declaration.
2. Run hugo mod get github.com/pgsty/[email protected].
3. Replace the old theme selection with the OINK module.imports entry shown below. Preserve unrelated imports and configuration. Merge the three markup.goldmark settings and markup.highlight.noClasses: false from the example. Do not replace your whole configuration with it.
4. Review site-owned layouts/ and assets, old theme shortcodes, and page type/layout values. These overrides and conventions may still select the previous theme’s behavior. Keep content. Make only the necessary adaptations.
5. Run hugo, then open an existing representative page with hugo server. Check its navigation, images, and code blocks before applying optional OINK features. Continue with verification.

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
   git init
   hugo mod init github.com/example/my-docs
   hugo mod get github.com/pgsty/[email protected]

   After hugo mod init, specify your site’s module path. This is usually its repository address. hugo mod get writes go.mod and go.sum. Commit both.

   Before building, create .gitignore so generated files stay out of Git. Leave enableGitInfo off until you have made the first commit:

   .gitignore

   /public/
   /resources/
   /.hugo_build.lock
   /.hugo_cache/

   Find the latest release tag on GitHub Releases; v1.5.1 on this page reflects this site’s current pin. Production sites should pin an explicit release tag in go.mod rather than tracking main.

2. Writing hugo.yml

   For this new site only, rename the generated hugo.yaml to hugo.yml (Hugo accepts both) and replace its contents with the following. Existing sites should merge the relevant settings instead:

   hugo.yml

   title: Product Docs
   baseURL: https://docs.example.com/
   defaultContentLanguage: en
   # enableGitInfo: true        # the "last modified" time comes from git; make the first Git commit 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.168.0'

   These five blocks control different parts of the site:

   Block	Governs	Consequence of omitting it
   Top level + languages	Site name, domain, languages and navbar menu	An incorrect baseURL makes every absolute production link incorrect
   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 select them 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. For each key’s meaning and default, see Configuration.

3. Write the first page

   Every top-level directory under content/ is a section. The directory structure determines 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 you add a translation, the anchors in both languages must correspond. For page-writing instructions, see Writing pages.

4. Preview

   hugo server

   Open http://localhost:1313/docs/. The Docs section lists Install. The home page is still empty until you add home content. Edit the Install page and confirm that the preview updates.

Other install methods

The steps above use a Hugo Module. The other three address specific constraints. These include network isolation, platforms that require the full theme tree as build input, and organizations that review their own theme copy. 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. For these methods, you must manage version resolution and integrity checks.

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

This is the only method in which Hugo resolves the version, verifies the checksum, and records it in go.sum. hugo mod graph shows the resolved version. hugo mod get -u upgrades it. This method requires 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 v1.5.1
git add .gitmodules themes/oink

theme: oink

Before CI runs Hugo, it must initialize the submodule. Otherwise, themes/oink is an empty directory:

git submodule update --init --recursive

Offline archive

For network-isolated environments, choose one of two paths. Prepare either archive on a connected machine. Transfer the complete archive.

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 . # put the archive outside the directory being archived

If _vendor/ exists, Hugo prefers it. hugo mod graph prints +vendor. Keep module.imports in hugo.yml unchanged. This step requires Go. Later builds 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. Unpack the selected theme version into themes/oink/.

curl -L -o oink.tar.gz \
  https://github.com/pgsty/oink/archive/refs/tags/v1.5.1.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. Unpacking places layouts/, assets/, i18n/, and static/ directly under the target. There is no additional directory level. Redistribution must keep LICENSE, NOTICE, and VENDOR.json. The manifest records each third-party runtime’s version, source, license path, and SHA-256. Use it for an offline audit.

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

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

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

shasum -a 256 -c oink-v1.5.1.tar.gz.sha256
mkdir -p themes
tar -xzf oink-v1.5.1.tar.gz -C themes

Before building offline, confirm that all eleven top-level entries are present:

Pinned source copy

When a hosting platform needs the theme files in the site repository, use the tag archive procedure above and unpack it into themes/oink/. Set theme: oink and commit the extracted files together with the tag and checksum you verified.

A plain git clone ... themes/oink leaves a nested .git directory. Adding it to the parent repository records a Git link rather than the theme files. This does not provide a self-contained source copy. Use a submodule if you want Git to track the theme by reference.

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 runs these commands. 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 only to the local machine. CI and production builds use the version in go.mod. Never commit go.work.

Verify

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

It passes when the build ends with Total in … and no unexpected WARN or ERROR (the upstream LibSass deprecation warning is expected; keep warnings visible for review and do not enable --panicOnWarning or HUGO_PANICONWARNING). 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. Code block colors change with it, which confirms markup.highlight.noClasses: false took effect
• git status --short lists only source changes. Git ignores generated output. For the Module path, commit both go.mod and go.sum. Other install methods keep their own theme source or submodule record.

Related

• Get started — choose between Starter, an existing Hugo site, and migration
• OINK Starter — the recommended new-site path
• Starter repository tour — what each template directory owns
• 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 all content types supported by OINK: documentation pages, blog posts, books, Expo image albums, release and download pages, and OpenAPI references. They share a single Markdown dialect and front matter schema, while each content type adds its own layout conventions.

What a documentation page is made of

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

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

## Prerequisites {#prerequisites}

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

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

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

Common Markdown patterns

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

Content types and where they are covered

3.1 - Writing pages

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

Creating a page

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

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

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

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

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

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

Heading levels and stable anchors

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

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

## Prerequisites {#prerequisites}

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

There are two reasons:

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

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

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

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

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

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

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

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

Where images go

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

Drafts and publishing

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

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

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

OINK’s Markdown extensions

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

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

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

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

1. Install Hugo Extended, 0.168.0 at the oldest:

   brew install hugo

2. Clone OINK Starter and preview it:

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

   Tip

   Add -D to preview drafts as well.

What appears at the end of a page

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

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

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

Verify

After writing a page, run a production build:

hugo --printPathWarnings

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

Then confirm three things in the browser:

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

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 requires no separate navigation configuration. The directory structure under content/ creates the sidebar tree. This page covers how directories and files are arranged, section indexes, ordering, icons, folding, hiding, and multiple sidebar roots.

Directories are the sidebar

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

Every directory needs an _index.md

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

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

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

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

Ordering: use multiples of 10 for weight

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

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

Single file or page bundle

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

List or cards on a section index

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

params:
  ui:
    section_index: cards # list | cards

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

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

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

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

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

Expanding and folding

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

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.

Groups without a landing page

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

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

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

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

The shell follows type, not the path

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

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

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

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

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

Verify

hugo --printPathWarnings

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

Then confirm each of these in the browser:

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

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

Controlling a branch from site code

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

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

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

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

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

How to read the tables

Precedence, highest first:

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

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

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

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

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

cascade:
  pager: false
  section_index: list

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

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

Basics

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: 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 license, and a link to the full notice. This family resolves site parameters → the data/upstreams entry named by upstream_source → this page’s front matter. The most specific declaration takes precedence.

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

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

Image zoom

Blog posts

The guide is Blog posts.

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

Book

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

Expo albums

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

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

Landing

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

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

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

The blog directory

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

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

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

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

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

A post’s front matter

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

Where it differs from a documentation page:

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

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

Featured image

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

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

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

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

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

On the article itself

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

params:
  ui:
    featured_image: banner

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

cascade:
  featured_image: wash

List layouts and pagination

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

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

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

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

params:
  ui:
    blog_index_size: 20

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

The card form

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

params:
  ui:
    blog_index: cards
    blog_index_columns: 3

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

Table and layout switching

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

blog_index: cards
blog_index_toggle: true

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

Gallery form

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

blog_index: gallery
blog_index_toggle: true
blog_gallery:
  mode: wall
  size: 240

The gallery toolbar offers three arrangements:

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

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

RSS

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

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

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

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

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

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

disableKinds: [RSS]

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

Categories and tags

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

Release notes

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

Components in a post

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

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

Authors and bylines

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

taxonomies:
  category: categories
  tag: tags
  author: authors

A post then names its authors in order:

authors: [vonng, ada-example]

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

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

---
title: Vonng
description: Maintainer of OINK and Pigsty.
images: [portrait.webp]
---

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

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

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

Series

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

taxonomies:
  series: series

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

series: [shell-internals]
series_weight: 20

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

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

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

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

Share

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

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

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

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

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

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

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

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

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

Verify

hugo --printPathWarnings

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

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

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 with type: book. The directory determines chapter order. Front matter determines chapter numbers. Each figure, table, equation, and example has a manually assigned number and stable anchor. Cross-references resolve in all four outputs. The book root can generate whole-book print HTML.

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

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

A book’s directory

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

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

The book home and chapter pages

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

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

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

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

A chapter page needs only its number and its order:

---
title: Replication and failover
book_number: 2
book_status: draft
weight: 20
---

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

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

The full key definitions are in Configuration and Page parameters.

Numbering: the native form

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

Figures

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

![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 to the right of the formula on wider screens. On narrow screens, they move below it and wrap. A wide formula can scroll horizontally. Short captions keep the equation easy to scan.

$$
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 on the fence names the enclosing <figure>, which is the reference target. The caption is required: a caption without a number is ignored, and a number without a caption is dropped with a warning. A numbered example renders in one frame where the caption forms the header and the body sits inside; a single code block shares the frame border without adding a second border.

```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 when the native form is insufficient. Examples include figures with several images or other Markdown, several tables under one number, sites without passthrough, and examples with several fences and prose. A single numbered image can use link in its native attribute line. It does not need fig just for an outbound link.

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

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

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

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

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