OINK Documentation

• 1: What is OINK
  • 1.1: Highlights
  • 1.2: Case Guide
  • 1.3: License and acknowledgements
• 2: Get started
  • 2.1: Use OINK Starter
  • 2.2: Starter repository tour
  • 2.3: From scratch and other install methods
  • 2.4: OINK CLI capabilities and next steps
  • 2.5: Use the OINK CLI
• 3: Authoring
  • 3.1: Writing pages
  • 3.2: Organizing content
  • 3.3: Page parameters
  • 3.4: Blog posts
  • 3.5: Books
  • 3.6: Releases and downloads
  • 3.7: API reference pages
• 4: Components
  • 4.1: Callouts
  • 4.2: Images
  • 4.3: Code Blocks
  • 4.4: Tabs
  • 4.5: Tables
  • 4.6: Fields
  • 4.7: Steps
  • 4.8: Cards
  • 4.9: FileTree
  • 4.10: Math
  • 4.11: Mermaid
  • 4.12: PlantUML
  • 4.13: Markmap
  • 4.14: Draw.io
  • 4.15: ECharts
  • 4.16: Infographic
  • 4.17: Gallery
  • 4.18: Badge
  • 4.19: Kbd
  • 4.20: Includes
  • 4.21: Asciinema
• 5: Customization
  • 5.1: Configuration
  • 5.2: Brand and appearance
  • 5.3: Home and landing pages
  • 5.4: Navigation and menus
  • 5.5: Layouts and page types
  • 5.6: Search
  • 5.7: Command palette
  • 5.8: Keyboard navigation
  • 5.9: Languages
  • 5.10: Versions
  • 5.11: Taxonomies
  • 5.12: Repository links and page info
  • 5.13: Print
  • 5.14: AI-agent support
• 6: Operations
  • 6.1: Local preview
  • 6.2: Deploy
  • 6.3: Comments
  • 6.4: Analytics and SEO
  • 6.5: Upgrade
  • 6.6: Troubleshooting
• 7: Design and development
  • 7.1: Architecture contract
  • 7.2: Component contract
  • 7.3: Shell and navigation contract
  • 7.4: Landing contract
  • 7.5: OINK migration boundary
  • 7.6: Design decisions
    • 7.6.1: Warnings and safe fallbacks
    • 7.6.2: Configuration model
    • 7.6.3: Markdown-first authoring
    • 7.6.4: Generated configuration schema
    • 7.6.5: Optional CLI and result contract
    • 7.6.6: Paper and Slate visual presets
  • 7.7: Design research
    • 7.7.1: Goldmark block-attribute evidence
    • 7.7.2: Ink and Terminal experiment, 2026-10-05
    • 7.7.3: OINK 1.2 pre-release review, 2026-10-05
    • 7.7.4: Visual preset acceptance, 2026-10-05
    • 7.7.5: Consumer and migration evidence
    • 7.7.6: OINK comprehensive review, 2026-08-26
    • 7.7.7: Community issue and PR review, 2026-09-19
    • 7.7.8: OINK 1.1 release review, 2026-09-20
    • 7.7.9: CLI maintenance acceptance on 2026-10-03
    • 7.7.10: CLI acceptance snapshot, 2026-09-29
  • 7.8: Design proposals and PRDs
    • 7.8.1: Backlinks and knowledge graph
    • 7.8.2: Media convergence
    • 7.8.3: OINK CLI and the next product stage
    • 7.8.4: OINK CLI maintenance roadmap
    • 7.8.5: Visual presets and appearance switching
• 8: OINK CLI

1 - What is OINK

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

A consuming site builds with Hugo Extended. Hugo Module installations also need Go to resolve modules; the initial download needs access to the module source. Theme assets need no Node.js, npm, PostCSS, or CDN request. Bootstrap, Font Awesome, the fonts, local search, the diagram runtimes and the API reference runtimes are all committed to the theme repository and shipped only to the pages that use them.

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

What the theme provides

• The documentation and blog shell: navigation, sidebar tree, table of contents, breadcrumbs, pager, dark mode, print view and accessible interaction.
• The multilingual frame: translation routing, fallback for untranslated pages, language weighting, RTL, and 32 complete interface catalogs.
• Local browser features: 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: callouts, tabs, steps, cards, field lists, file trees, galleries, badges, keys and more — most with a native Markdown form.
• Content types: beyond ordinary documentation, built-in book numbering and cross-references, release and download pages, data-driven landing pages, and OpenAPI reference pages.

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

Is OINK for me

How it differs from other documentation systems

Choose a toolchain and authoring model before comparing individual features. The same project can be a good fit for different systems depending on who maintains it:

Check each candidate’s current installation and extension documentation. OINK’s search, image zoom, comments, and feedback are opt-in; the site also chooses Markdown and agent outputs under outputs.

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

Start here

• Get started — use the official Starter, customize it in layers, and publish it.
• Components — one page per component, source first and rendered result after.
• Showcase — fifteen production sites and which part of OINK each one uses.

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

1.1 - Highlights

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

Components are written in Markdown

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

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

→ Components

Build with Hugo

Hugo Extended 0.160.1 or newer compiles the site’s assets. SCSS is compiled by Hugo’s embedded Sass transpiler; the theme never invokes postCSS and needs 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 is enough to build the site.

The interface runs JavaScript in the browser: search, the command palette, diagrams and tabs are page scripts. Those scripts ship with the theme and are delivered per page according to what that page actually uses.

→ Quick start

Local-first

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

Where a feature could cause a network request, the theme leaves it off rather than reaching out silently: PlantUML without params.plantuml.svg_image_url, Diagrams.net without params.drawio.drawio_server, and Algolia without appId / apiKey / indexName each warn and stay disabled, and a publishing gate built with --panicOnWarning turns that warning into a failure.

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

→ License and acknowledgements · Configuration

One source, four outputs

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

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

→ Print · AI-agent support

Two languages and 32 interface locales

Multilingual support uses Hugo’s own mechanism: translation routing, a language picker ordered by weight, fallback for untranslated pages, RTL, and canonical and alternate metadata. Interface strings come in 32 language packs sharing one 194-message schema: all 31 locale filenames supported by Docsy, plus generic zh. Every pack now contains native OINK interface text rather than English placeholder blocks; zh and zh-cn use Simplified Chinese and zh-tw uses Traditional Chinese.

→ Languages

Full-text search that stays on the site

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

→ Search

Command palette

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

→ Command palette

Keyboard navigation

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

→ Keyboard navigation

Backlinks

Turn on params.ui.backlinks and every page lists the pages that link to it — derived at build time from the ordinary links you already write, with no new syntax and no JavaScript. This site enables it site-wide: look at the “Linked from” group in this page’s right rail, and the more a page is referenced, the longer its list — past eight entries it folds.

→ Backlinks

Four content types beyond documentation

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

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

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

Output for AI assistants

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

0.8.0 adds two more: a section that enables LLMSFULL becomes one llms-full.txt an agent fetches in a single request, and a site that enables NAVJSON publishes navigation.json per language — the sidebar’s tree readable 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 hands the current URL to a third party, so the site must turn on params.ui.page_context_menu.assistant_links explicitly.

→ AI-agent support

Versions

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

→ Versions

See for yourself

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

1. Press Cmd/Ctrl + K on any page and type postgres to see local search results; press \ for command-only mode.
2. Append index.md to the current page address to get this page’s Markdown version.
3. Open https://oink.pgsty.com/llms.txt, the site inventory written for AI assistants; it leads 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 and distinguish site-owned code from theme features where a pattern needs custom implementation.

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

Distribution documentation

pigsty.io

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

pigsty.cc

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

pgsty.pro

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

Product documentation

PIG

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

SOW

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

SILO

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

PG Exporter

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

Books

Designing Data-Intensive Applications

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

The Product-Minded Engineer

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

PG Internal

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

Aggregate, landing, and custom sites

PostgreSQL ecosystem library

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

pgsty.com

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

Capslock

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

oink.pgsty.com

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

pgext.cloud

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

Choosing a starting point

• For a conventional product manual, begin with PIG or SOW.
• For a large migration, compare SILO and 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, not a starter template. Its pages exist to exercise rendering behavior; the production cases above are the better design references.

→ Browse all cases · Quick start · Repository tour

1.3 - License and acknowledgements

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

Which licence covers what

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

Upstream: Docsy

What the theme’s NOTICE records:

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

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

Third-party runtimes shipped with the theme

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

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

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

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

Fonts and icons

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

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

Design references

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

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

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

Reusing this documentation

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

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

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

Reusing the theme

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

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

Related

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

2 - Get started

The recommended path for a new site starts from pgsty/oink-starter, not from a copy of this documentation and regression repository. The Starter is a public GitHub template: it pins a published OINK release, builds as-is, and contains only neutral project content and deployment workflows.

Choose a path

Five-minute baseline

1. Install the tools

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

   $ go version
   go version go1.27.0 darwin/arm64
   $ hugo version
   hugo v0.165.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

   For a repository you intend to keep, open the Starter and select Use this template, then clone the repository GitHub created for you. To evaluate the untouched original locally:

   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. A browser reload that shows both changes is the first useful proof that 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.

This order is deliberate. A site that first proves its build and content tree is easier to debug than one that changes languages, navigation, CSS, analytics, and hosting at the same time.

Publication gate

Before the first push, run the same warning-strict production build the Starter workflows use:

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

Success means the command ends with Total in …, prints no warning or error, and public/ contains the language roots and representative Docs, Blog, and Book routes. It does not yet prove deployment: a local build, a commit, a push, a green workflow, and correct public rendering are separate gates.

Next

Start with the complete Starter tutorial. If the template deliberately carries 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 supported starting point for a new OINK site. It is deliberately smaller than oink.pgsty.com: no theme documentation, analytics account, comment repository, browser regression suite, or PGSTY-specific brand is copied into your project.

As of 2026-09-20, the template pins OINK v1.0.0, Go 1.27, and Hugo Extended 0.165.0. Its default three-language, English-only, and English–Chinese profiles have all been built warning-strictly against that release.

What the template contains

The Starter’s own Book at /book/ is a four-chapter tour from preview to deployment. This page is the maintainer-grade version: it explains the order of changes, the boundaries between them, and the checks after each layer.

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 gives your site its own Git history and keeps the original Starter as an upstream reference rather than as a remote you might accidentally push to.

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 the clean project boundary 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

The template snapshot 137843b documented here pins github.com/pgsty/oink@v1.0.0; if the template has since changed, use the version in your clone’s go.mod. This unchanged preview is your baseline. After that first success, upgrade a site still using 1.0 as a separate step with the 1.0-to-1.1 checklist, before customizing content.

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, not fragments: copying one replaces the commented integration examples in the root file. Do it at the beginning; if hugo.yaml already contains project changes, merge the languages and disableLanguages sections instead of overwriting it.

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; use [zh, fr] for English only. 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. Do not change the logo yet unless the project has final artwork; text identity is easier to review first.

Layer 3: home page

The home page is data rather than an opaque layout override:

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

Edit one language first. In each file, sections fixes the order; hero, cards, and cta provide the content. Replace the promise, destination URLs, and sample card copy while keeping the structure. After the first language is right, translate the same information into the enabled peers.

For another composition, use the full registry in Home and landing pages; do not copy the Starter home partial, because there is no site-specific template to copy.

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. Top navigation lives in menus.main on the translated _index roots, so renaming Docs, Blog, or Book happens beside the content it names rather than in a 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 when analytics is present;
• assistant links send the current URL to a third party and therefore 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

Strict local build

Before enabling a hosting workflow:

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

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.

Use either Direct Upload or Cloudflare Git integration for one project, not both. The complete host comparison and baseURL rules are in Deploy.

Verify and remove samples

Before calling the site ready:

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 language switching lands on peers, not 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. A warning-strict rebuild after each whole surface is removed keeps failures attributable to one change.

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 describes the repository created from pgsty/oink-starter. It is not a tour of the much larger oink.pgsty.com documentation and regression repository. The theme source is not copied into either site: go.mod pins it as a Hugo Module, and Hugo stores the resolved source in the Go module cache.

Top-level map

Generated public/, resources/, .hugo_build.lock, and module caches are ignored build state, not source.

What to change first

What to keep

• go.mod and go.sum: together they pin and verify the template’s selected OINK release. Commit both; keep that baseline distinct from a later upgrade.
• The three Goldmark settings in hugo.yaml: native Steps, Cards, Fields, image attributes, and Book targets depend on them.
• outputs: removing markdown, LLMS, or print intentionally removes the corresponding Markdown, agent-index, or print surfaces.
• fetch-depth: 0 in workflows when enableGitInfo stays on: last-modified and contributor facts need repository history.
• GOWORK: off and HUGO_MODULE_WORKSPACE: off in CI: a developer’s local workspace must not replace the published release being verified.

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 no other page links to it;
4. run a warning-strict build and inspect the remaining top navigation.

Do not delete only translated section roots: that creates language-specific navigation and fallback behaviour that is difficult to distinguish from a mistake. 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 and why;
• Get Started gets a new user to a result;
• Tutorial teaches an end-to-end task;
• Reference records exact supported behaviour.

Rename or reshape those sections for the project, but preserve the separation between learning paths rather than mixing every kind of answer into 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. This is intentional: Hugo then recognizes the unused suffixes as translations instead of rendering several files onto one English URL. Copy a profile only before project-specific configuration begins; afterwards merge changes by hand.

Where OINK lives

Two files establish the module boundary:

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

module github.com/OWNER/PROJECT-DOCS

go 1.27.0

require github.com/pgsty/oink v1.0.0

This is the 137843b Starter snapshot used by the tutorial, not the latest OINK release. For a newer template, read its own go.mod.

hugo mod graph shows the resolved version. Production follows the exact tag in go.mod; a local HUGO_MODULE_REPLACEMENTS value is a development override and must never be committed or treated as release proof.

Deployment files

The GitHub Pages workflow runs automatically on pushes to main; repository settings must 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 operate. Cloudflare Direct Upload and Cloudflare Git integration are alternative ownership models for the same project, not two gates to run together.

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 strict production build.
8. Deploy, then verify production independently.

Commit between layers when the repository is already yours. Small boundaries make a later regression or rollback attributable to one decision.

Verify

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

The module graph names the pinned release, the build emits no warning or error, and Git status contains source edits but no public/ or cache files. Then open the enabled language roots and one Docs, Blog, and Book route before moving to deployment.

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 plus one hugo mod get gives a single-language site you can preview. The cost is that the home page, example content, deployment workflow, and every component usage are yours to assemble.

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

The second half weighs four install methods: Hugo Module, Git submodule, offline archive, and pinned source copy. OINK 1.1.0 uses Go 1.27 and Hugo Extended 0.165.0 for release validation. The theme’s lower declared compatibility floor is for existing sites that deliberately retain an older toolchain.

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/oink@v1.2.0.
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: those overrides and conventions may still select the previous theme’s behavior. Keep content and make only the adaptations needed.
5. Run hugo --panicOnWarning, 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/oink@v1.2.0

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

   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/

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

2. Writing hugo.yml

   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.160.1'

   What each of the five blocks governs:

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

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

3. Write the first page

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

   content/docs/_index.md

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

   content/docs/install.md

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

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

4. Preview

   hugo server

   Open http://localhost:1313/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 particular constraints: network isolation, a platform that requires the build input to contain the whole theme tree, or an organization that reviews its own copy of the theme. Apart from hugo mod vendor, none of them creates a Go module, and the site references the theme with theme: oink rather than module.imports. The shared cost is that version resolution and integrity checking become your responsibility.

Hugo Module (recommended)

hugo mod init github.com/example/product-docs
hugo mod get github.com/pgsty/oink@v1.2.0

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

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

Git submodule

Record an exact theme commit in the site repository:

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

theme: oink

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

git submodule update --init --recursive

Offline archive

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

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

hugo mod vendor          # writes _vendor/, holding the theme's full source tree
tar czf ../my-docs.tgz . # put the archive outside the directory being archived

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

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

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

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

theme: oink

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

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

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

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

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

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

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

Pinned 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, not the theme files; it therefore does not provide this 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 is an alias for exactly these commands, and make dev and make check expect the theme checkout at the sibling ../oink:

build:
	hugo --cleanDestinationDir --minify

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

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

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

Verify

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

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

• /docs/ opens and the sidebar holds the page you wrote
• The navbar has a search box that finds the heading you just wrote
• The light/dark toggle is present, and code block colours follow it (which shows markup.highlight.noClasses: false took effect)
• git status --short lists only source changes; generated output is ignored. 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

2.4 - OINK CLI capabilities and next steps

oink is a command-line tool for OINK site maintainers. It brings site creation, environment diagnosis, output validation, local preview, and theme upgrades into one interface. Its six commands already form a usable local workflow. The next useful investment is to help more users install it, understand failures, and repeat routine maintenance. Migration, documentation version management, and API reference generation can follow one capability at a time.

This page explains current capabilities and possible next steps. For complete installation instructions, see Using OINK CLI. Executed tests are recorded in the first-stage acceptance report.

Purpose and audience

The OINK theme owns presentation, navigation, search, content components, and output formats. Hugo loads configuration and renders the site. The CLI connects those inputs and results into repeatable maintenance: configuration mistakes, the actual theme source, broken references, and proposed upgrade changes should all have inspectable evidence.

The CLI is a standalone Go executable that calls external Hugo. It requires no Python, Node.js, account, or background service. Initialized sites retain normal Hugo configuration and content. Once dependencies are available, ordinary Hugo can build them without the CLI. Theme and CLI version numbers serve different purposes.

It serves three audiences: new maintainers establishing a working baseline, existing maintainers diagnosing and upgrading sites, and CI or automation programs consuming stable JSON results and exit codes.

The six implemented commands

doctor inspects readiness; check also builds and validates artifacts. build produces the site’s normal publishing output, while check validates in an isolated copy. dev and build can write normal Hugo output and caches; read-only diagnosis and upgrade preview preserve site sources.

Checks follow rendered output

check asks Hugo to enumerate the output formats and URLs declared by each page in each language, then verifies the generated files. It handles multiple languages, root URLs and subpaths, URL encoding, and external-link boundaries. It does not derive a second routing system from Markdown filenames. Page-level output overrides, statically mounted unlisted pages, and intentional link-only pages follow Hugo’s actual semantics.

Supported machine outputs include NAVJSON v1 navigation trees, BookManifest v1 book manifests, offline search indexes, LLMS indexes, and LLMSFULL content bundles. Disabled outputs are optional. A valid artifact in one language cannot hide a missing required artifact in another. An unknown required contract is reported as incomplete coverage.

check --release verifies a build intended to use a public theme version. It disables both Go and Hugo workspaces and Hugo replacements in the isolated copy. A conflicting theme go.mod replace is reported, never silently removed. Ordinary check can validate a selected vendor build; --release explicitly reports that verification of its public-source byte identity is incomplete.

Upgrades validate the candidate first

An upgrade plan identifies the target version, selected files, and before/after state. --expect-plan can bind a write to a reviewed plan; the command also checks whether target files changed after planning. Dirty target module files are protected, unrelated dependencies and edits survive, and write failures provide backup and recovery evidence. Recovery must preserve concurrent user edits instead of overwriting them to undo the CLI’s own work.

Current upgrades handle go.mod and go.sum. They do not refresh _vendor or rewrite arbitrary content or configuration. Vendor refresh requires a separate, explicit, reviewable workflow. The CLI does not commit, push, or deploy.

Automation and offline use

Every command is non-interactive. With --json, stdout contains exactly one oink.result/v1 result; tool logs go to stderr. Results include rule IDs, severity, known locations, explanations, actions, coverage, and raw Hugo evidence. A source line number is never invented when the available evidence cannot establish it.

The default process policy is offline. Only explicit --network allows network use for that invocation. The CLI does not download Go toolchains, install system packages, change global configuration, or add telemetry. Supported workflows can run offline after module preparation; a missing cache entry fails explicitly.

Isolated commands use disposable caches. A successful init --network does not establish a persistent cache for subsequent commands. Only prepared module download artifacts are reused; Hugo’s global remote-resource cache is not. Required remote content must be materialized locally or fetched during an invocation that explicitly permits network access.

A complete working path

After installing locally and installing the Go, Git, and Hugo Extended versions required by Starter, use the following sequence. The first command is an explicit dependency-preparation step that may use the network:

GOWORK=off GOTOOLCHAIN=local go mod download github.com/pgsty/oink@v1.1.0
export GOMODCACHE="$(go env GOMODCACHE)"

oink init my-docs --languages en,zh
oink doctor --site my-docs
oink dev --site my-docs -- --bind 127.0.0.1 --port 1313

Edit the site title, baseURL, and content during preview. After stopping the preview process, run:

oink check --site my-docs --release --json > check.json 2> check.log
oink build --site my-docs -- --minify

For an existing site’s upgrade, preview first, then review and explicitly apply the plan using the upgrade guide. OINK v1.1.0 here is the tested initialization baseline, not a claim that it is always the latest theme version.

Verified scope and current limits

First-stage acceptance covers Go tests, vet, race checks, ordinary Hugo builds for all three Starter profiles at root URLs and subpaths, and three real consumer repositories: the OINK documentation site, the PIG site, and repository documentation. It also includes initialization and checking with OS-level network denial, real upgrade write protection, thin-wrapper process checks, and archive reproduction.

The exercised runtime platform is macOS arm64, with Go 1.27.1 and Hugo Extended 0.166.0. Darwin amd64 and Linux amd64/arm64 were cross-compiled but have not completed runtime qualification on those systems. Windows is outside the first-stage support scope. Source installation is available; public downloads, tag-based installation, and Homebrew distribution are not delivered yet.

Isolated checks currently support materialized, single-host sites. Linked Git worktree metadata, mounted symlinks, mounts outside the isolated inputs, custom configuration directories, dynamic content adapters, multihost language output, and render segments that suppress verification probes have explicit boundaries in the input scope table. Unsupported required inputs cannot receive a complete passing result.

Static checking does not certify browser interaction, accessibility, external URL availability, hosting redirects, translation completeness, or content semantics. Browser and deployment acceptance remain separate workflows.

Improvements to prioritize next

First reduce friction in the six existing commands. These are suggested capabilities based on current limitations, not implemented features. New flags and contracts still belong in the formal proposal process.

These directions should not all start at once. Use independent installation and maintenance sessions to identify recurring obstacles, then choose one measurable improvement at a time. Future ignore rules or lint baselines must not hide Hugo build failures or missing required coverage.

Later product capabilities

The following directions are discussed in the CLI roadmap and remain proposals. They preserve the boundary that generated site sources are ordinary files and rendering does not depend on the CLI.

The recommended sequence is a publicly usable maintenance tool, followed by assessment for one migration path. For the next content capability, prefer documentation version lifecycle unless real API users demonstrate stronger repeated demand for static OpenAPI. Choose one foundation per stage to avoid maintaining several models before users have validated them.

Further reading

• Using OINK CLI: builds, installation, flags, and complete workflows.
• CLI and result contract: stable behavior, JSON, exit codes, and file protection.
• First-stage acceptance: executed tests, real sites, and platform boundaries.
• CLI and the next product stage: rationale, priorities, and acceptance conditions for future work.

2.5 - Use the OINK CLI

oink is an optional Go CLI for Hugo sites. The local 0.1.0-dev candidate focuses on diagnosis, real output checks, initialization, builds, theme upgrades, and guarded maintenance plans. Hugo remains the renderer. Sites continue to work with ordinary Hugo.

The current cached-module move integration failed once and passed a targeted rerun; the intermittent failure remains open. For the recorded scope, see the verification limits.

Build and install locally

From an available oink-cli source checkout, use Go 1.26 or newer and Make:

make deps                    # explicit network preparation of Go dependencies
make build                   # local toolchain, offline build into bin/oink
./bin/oink --version
./bin/oink --help
make install                 # defaults to $HOME/.local/bin
export PATH="$HOME/.local/bin:$PATH"

The export affects this shell only. The CLI does not install system tools or change a shell profile. make install PREFIX=/your/prefix chooses another prefix; BINDIR=/your/bin selects the exact directory. A source build needs the dependencies in go.sum; make deps explicitly prepares them when network access is available. The build and install targets then use the local toolchain without downloading dependencies or another Go compiler.

The dated runtime acceptance record exercised its identified historical candidate on macOS arm64, native Linux arm64 and Linux amd64 emulated through QEMU TCG, with Go 1.27.1, Hugo Extended 0.166.0 and the public OINK v1.1.0 module. The Hugo version gate accepts Extended 0.160.1 or newer; this is not a claim that every accepted version has been tested. The embedded Starter documents Hugo Extended 0.165.0 or newer and requires Go 1.27. Those Linux tests ran as nonroot users on ext4 with provisioned offline dependencies; required filesystem/signal and selected actual-Hugo cases execute. Optional tools absent from a guest stay explicit skips; they have separate host protocol evidence. Two fresh builds reproduced all five archives, and the three declared runtime archives were extracted and executed outside a checkout without Node. Darwin amd64 is an experimental archive and remains unverified after actual Bad CPU type; cross-compilation does not prove runtime support. Windows is outside the declared scope. These results remain bound to the recorded source and archives; they do not qualify the later reduced CLI or a newly built executable automatically.

make release VERSION=0.1.0-dev DIST=dist prepares four binary archives, a source archive, and SHA256SUMS in a new or empty directory. It does not publish them. See the archive acceptance and reproduction steps for the exercised platform and reproducibility limits.

Create a site from the fixed Starter

Prepare the public theme once if it is not already cached. This explicit provisioning command may use the network:

GOWORK=off GOTOOLCHAIN=local go mod download github.com/pgsty/oink@v1.1.0
export GOMODCACHE="$(go env GOMODCACHE)"
oink init my-docs --profile docs --languages en,zh

init accepts a new directory or an existing empty directory. Its parent must exist. It refuses existing files, including dotfiles, and refuses a symbolic link as the target. It validates a temporary candidate before creating any target file and detects target changes during that operation.

Choose --profile project (the default), docs, blog, or book. project keeps the complete previous Starter projection. The other choices retain their archived content section and adapt the existing localized site title, home cards/actions and navigation to that section. Selected content and shared assets/examples/workflows/license retain their archived bytes; generated configuration and homepage YAML are the only serialized profile projections. The archived workflow examples remain unchanged and are not the checksum-bound CI plans from ci init.

Language choices remain en (default), en,zh, and all (English, Chinese and French), independently of the selected profile. Every composition uses the same MIT-licensed Starter commit 137843b25bacd76ddd1f7ce71330bf2e3155b954 embedded in the executable, pins OINK v1.1.0 with recorded Go checksums and disables enableGitInfo before the first Git commit. No runtime template fetch, Git initialization or commit occurs. Unknown profiles fail before writing; unavailable or failed required Hugo validation leaves the new/empty target unchanged.

Edit the title and baseURL in my-docs/hugo.yaml, then edit the home data and sample content using the Starter tutorial. After creating Git history yourself, you can enable enableGitInfo if wanted. Ordinary Hugo can build the generated site without the CLI:

cd my-docs
GOWORK=off HUGO_MODULE_WORKSPACE=off GOPROXY=off HUGO_MODULE_PROXY=off \
  GOTOOLCHAIN=local hugo --environment production --panicOnWarning
cd ..

This uses the GOMODCACHE exported above and provisioned dependencies. All 12 profile/language combinations passed ordinary warning-strict Hugo at both root and /manual/ URLs (24 builds). Rendered local references were checked, and complete source bytes/modes/file inventories compared equal before/after. Public init/check tests separately cover all four profiles in English and bilingual configurations, default-project byte/mode parity and failure paths.

Create ordinary content

Start from the initialized bilingual site above. Preview a new bundle and its Chinese draft, inspect the diff and candidate result, then apply the saved plan:

oink new content/docs/guide --site ./my-docs --title "Getting started" --translations zh --kind docs --plan new-guide.json
oink plans apply new-guide.json --site ./my-docs

--language defaults to the effective default language; --kind defaults to page and also accepts docs, blog, or book. The site-relative bundle path must map unambiguously through actual content mounts and their language-site matrix. Language directories retain distinct physical indexes; shared filenames use the actual language relationships. Existing bundles or same-page sibling files are preserved. The primary file is an ordinary page; selected translation files are drafts with the supplied title as placeholder. They remain unreviewed until explicit human review. Each proposed file must be recognized as one actual site-owned Hugo page with actual rendered outputs; link-only/no-output, ignored or build-never new files cannot pass merely because existing content builds cleanly. Saving a plan does not write those site files. Apply rechecks the bound fresh directory and source state and preserves later editor attachments on failure.

Configure editor hints and snippets with the ordinary site editor. The CLI no longer generates these settings.

Inspect pages and committed impact

Use an actual page ID, Hugo Path, permalink or captured source path. The language:path ID removes multilingual selector ambiguity:

oink inspect 'en:/docs/old' --site my-docs --offline --json
oink impact --since HEAD --site my-docs --offline --json
oink check links --since HEAD --site my-docs --offline --json

Choose IDs from the actual captured page facts; these example pages must exist in your site. inspect exposes observed references, actual outputs, translation peers and physical bundle inputs. impact renders the selected committed Git tree and the current site, including old deleted identities and unchanged inbound pages. Changed global configuration/templates/data and uncertain ownership expand scope. An observed alias output with unproven page ownership also causes full scope, without guessing an owner from front matter.

check --since currently runs the full current check. Read data.check_scope: full separately from causal data.impact.full_scope. Completed inspect/impact queries return 0 while quality findings remain in data.current_check; full checking retains policy findings 1. Missing or unrenderable history is required incomplete 2: known current facts remain visible, while old identities and changes stay unknown. Current external local dependencies are never borrowed as historical bytes. A committed site-owned theme is supported; symlink/submodule and required unsupported or incomplete history states are explicit limits.

Preview and apply a content move

oink move content/docs/old content/docs/new --site my-docs --offline \
  --plan /tmp/oink-move-plan.json --json
oink plans apply /tmp/oink-move-plan.json --site my-docs --offline --json

Use clean physical site-relative file/bundle paths and save the new plan outside the selected site. The preview shows original checks, a provisional route probe, final validation, translation/attachment mappings, byte/full-mode diffs, actual old/new routes, alias advice and manual references. A provisional probe may report stale-link findings 1; only the final candidate can validate the plan. Raw HTML, shortcode output, transformed or ambiguous destinations are not rewritten. Repeated ordinary Markdown destinations can also stay manual when exact source/output occurrence ownership is unproven, including aggregate/print output. Their final broken targets return 1 and no plan is saved. Review manual source locations and actual output pointers in your editor, then create a fresh preview. A moved attachment needs a proven new published URL, not merely a new physical path. Paired equal-byte processed image outputs can be proven while absolute original-resource URLs remain manual; those unproven URLs are not constructed automatically. Aliases are advice for review, not automatically serialized front matter.

Explicit saved apply captures and regenerates the actual proof before selected writes. Complete source hashes/modes/inventory, external inputs and fresh target directories remain guarded. Existing targets, later source/attachment/ configuration edits or mode changes return 2 without overwriting them. The move preserves original modes and binary bytes, unrelated files and the Git index; it does not commit. The resulting ordinary Hugo inputs remain buildable with Hugo independently of the CLI. Inspect the named recovery directory if an apply reports a failure during writes.

Diagnose and validate an existing site

Run these commands from any directory and select exactly one site:

oink doctor --site ./my-docs
oink check --site ./my-docs
oink check links --site ./my-docs --format json
oink check --site ./my-docs --base-url https://example.org/manual/
oink check --site ./my-docs --release --keep-work

doctor reports the real Hugo executable and version, required tools, the declared theme pin, effective Hugo configuration, module graph and mounts, workspaces, replacements, vendor presence, languages, and enabled outputs. It does not build the site. Keep the raw subprocess evidence alongside the structured findings when investigating a Hugo error.

check copies the inputs into a disposable directory, isolates build outputs and caches, invokes Hugo with --panicOnWarning, and checks supported local links, anchors, resources, and machine-output references against the rendered files. Hugo itself enumerates each page’s enabled output formats and URLs for each language, including front matter overrides and statically authored pages excluded from ordinary page lists. A temporary verification output is added only in the disposable copy and removed before artifact checks. The CLI does not infer routes from Markdown filenames. Disabled machine outputs are not errors. Coverage entries identify checks that were completed, omitted, unsupported, or incomplete. Browser interactions, accessibility, external URL availability, server redirects, and deployment are outside this static check.

JSON data.pages supplies Hugo’s page identities, actual routes, aliases, languages, translations, publication settings, known source provenance and outputs. data.references supplies observed rendered references and checked anchor state. Generated pages with no proven file retain an explicit unknown source. These are production-view facts; their presence does not certify undeclared translation coverage or invent a Markdown source line. Human output summarizes page/reference counts; use JSON for the full arrays.

Both commands preserve source files. --keep-work retains the disposable directory and reports its path for inspection; otherwise it is removed. Use --config FILE, --environment NAME, and --hugo PATH when the site needs a specific configuration, environment, or Hugo executable. Configuration files must be inside the selected site. For inspection, --environment takes precedence over HUGO_ENVIRONMENT; otherwise the environment is production. If Hugo adds or changes go.mod or go.sum in the temporary copy, the CLI reports that required dependency preparation remains unreviewed; it does not apply those changes to the source or silently call the original inputs ready.

--release disables both Go and Hugo workspaces and disables environment and Hugo-configuration replacements in the disposable copy. It preserves go.mod replacements. A local OINK replacement must be reviewed explicitly before claiming a public-pin check; the CLI does not silently delete it. Vendor evidence is also separate: a public requirement in go.mod does not establish which bytes are in _vendor.

The initial isolated-check scope has these limits:

Likewise, disabling page rendering or selecting render segments that omit an enabled language’s verification output cannot produce a successful full check. These are coverage limits, not instructions to delete a worktree, replacement, symlink, or authored content. doctor can still inspect supported configuration without claiming a completed output build.

Select checks and record project policy

Create a regular oink.yaml at the site’s root when the project needs explicit checking policy. It uses schema_version: oink.policy/v1 in one YAML document. Keep languages, menus, URLs and theme versions in existing Hugo/module inputs. Unknown policy keys/groups, invalid reviews and required disabled groups return 2.

This example retains required links and demonstrates a reviewed finding and a separately deployed URL scope. Replace illustrative paths and review metadata with actual project decisions:

schema_version: oink.policy/v1
checks:
  links: {enabled: true, required: true}
rules:
  ANCHOR_MISSING: warning
exclusions:
  - rule_id: REFERENCE_MISSING
    file: docs/legacy/index.html
    reason: Reviewed legacy reference awaiting removal
    reviewed_by: site-maintainer
    reviewed_at: "2026-10-03T00:00:00Z"
external_scopes:
  - url: https://example.org/status/
    reason: Separately deployed status application
    reviewed_by: site-maintainer
    reviewed_at: "2026-10-03T00:00:00Z"

Rules use exact diagnostic IDs and error, warning or info. Exclusion globs use clean relative paths; recursive ** and escape paths are unsupported. Excluded findings stay visible with disposition: "excluded" and review metadata. Checks never create review records as a side effect. Required build/input/tool failures and unsupported coverage remain 2 despite policy.

For a site at https://example.org/manual/, same-origin HTML /status/ references normally fail as outside the published base path. The reviewed scope declares that separate application; availability remains untested. Complete path-segment matching excludes /status-other/. A scope cannot hide missing targets inside /manual/ or required local machine-output references.

Without a policy, check enables required links, translations and style. check links, check translations and check style each select one required engine; unselected groups report optional not_checked. Explicit policy groups can disable optional checks. Every check retains its strict Hugo prerequisites.

Declare translation coverage

Start with Hugo’s actual page identities in check --json (data.pages), then declare the source Page.Path scope and required enabled languages. Paths are Hugo source identities, independent of slug, URL, aliases or language prefixes. Extend the same single oink.yaml object; this complete example also declares protected prose and the baseline path:

schema_version: oink.policy/v1
checks:
  links: {enabled: true, required: true}
  translations: {enabled: true, required: true}
  style: {enabled: true, required: true}
translations:
  scopes:
    - path: /docs/handbook
      source_language: en
      required_languages: [zh]
      mode: localized
      drafts: include
      constraints:
        explicit_ids: true
        ids: [setup]
        placeholders: ["${SERVICE_NAME}"]
        code_labels: [bash]
        required_fields: [title]
        equal_fields: [weight]
style:
  protected:
    - file: content/docs/handbook.md
      literal: "${SERVICE_NAME}"
      count: 1
baseline: .oink/baseline.json

Use real page paths, filenames, IDs and protected literals from your project. mode defaults to localized, drafts to include. Strict mode with explicit_ids: true requires complete recognized explicit-ID correspondence; localized mode protects the selected ids. Placeholder counts, named fenced code, required dotted fields and equal dotted values are separate opt-in constraints. Other prose, heading counts and code may differ.

drafts: ignore skips draft sources and treats draft targets as unavailable; require-published requires the source and required targets in the production view. Hugo-disabled known languages are optional not_applicable; unknown languages fail policy loading. Without scopes, existing default-language pairs and duplicate relationships are inspected, but universal localization is not required. JSON data.translations distinguishes missing, draft and hash-review states. An explicit nonpublishable analysis includes draft/future/expired pages without replacing production output or publishing them.

Inspect source rules and provenance

oink check style --site ./my-docs --json

Generic rules inspect recognized explicit IDs and declared protected prose. The parser follows effective Hugo markup.goldmark.parser.attribute.title and .block, plus markup.goldmark.extensions.passthrough.enable and its configured .delimiters. These settings remain in Hugo configuration. It keeps original UTF-8/CRLF/BOM offsets and accepts unknown valid YAML/TOML/JSON front matter. Code, shortcode bodies, raw HTML and math contents are excluded from prose evidence; an attribute after a fence is not treated as a supported code attribute. Unsupported required source syntax or absent declared protected inputs returns 2.

The small native OINK v1.1.0 catalog reports advisory code/table conflicts, deprecated attribution fields and attributes the published theme drops. data.native_rule_provenance records immutable source/license hashes. The catalog runs only for a SHA-verified actual public module-cache mount. Other versions, replacements, vendor copies and unknown identities report optional native-theme-rules: not_checked; generic rules still run. Review this coverage before treating the check as complete for a particular component.

Review translations and apply metadata plans

Use the exact Hugo IDs or unambiguous captured source filenames from the report:

oink translations status --site ./my-docs --json
oink translations diff 'en:/docs/handbook' --site ./my-docs
oink translations review 'en:/docs/handbook' 'zh:/docs/handbook' \
  --site ./my-docs --reviewed-by site-maintainer \
  --reason 'Reviewed source and translation together' --plan /tmp/oink-review.json
oink plans apply /tmp/oink-review.json --site ./my-docs

Review previews .oink/translations.json (oink.translations/v1) after candidate validation. It never writes the site during preview. The record binds full source/translation byte SHA-256 values and explicit reviewer/reason/time. --reviewed-at RFC3339 is optional and defaults to current UTC. No record means unknown; current, source_changed, translation_changed and both_changed describe hashes since review, without judging translation accuracy. Modification time is not review evidence. diff shows captured source text for comparison.

To acknowledge completed, reviewed existing findings while keeping them visible:

oink baseline capture --site ./my-docs --reviewed-by site-maintainer \
  --reason 'Reviewed existing findings for this maintenance baseline' \
  --plan /tmp/oink-baseline.json
oink plans apply /tmp/oink-baseline.json --site ./my-docs

The default baseline is .oink/baseline.json (oink.baseline/v1); baseline in policy can select another clean relative file. Acknowledged exact rule, normalized location/pointer and condition remain visible with disposition: "baseline" and review metadata. Severity changes do not invalidate that fingerprint; new conditions still block. Required incomplete work cannot be captured or hidden by a baseline.

Both preview commands require reviewer and reason. --plan FILE creates a new oink.plan/v1 file without overwriting; omitting it prints the validated plan only. Review the readable diff, site, file list and base byte/mode guards before plans apply. That command validates a fresh isolated candidate and refuses stale guards, escapes, .git, symlinks and nonregular files. It writes only the plan’s selected files; these commands do not use --write. Failed partial writes restore owned unchanged files and preserve later editor bytes, modes or deletions. The reported recovery directory retains original/concurrent evidence.

Preview and apply one theme upgrade

Choose an explicit release tag. The following command validates a candidate and prints the proposed module-file changes without applying them:

oink upgrade --site ./my-docs --to v1.1.0 --json > upgrade-plan.json

The normal human output shows a unified module diff, mode changes and bounded route/alias/capability changes. In JSON, review data.plan_id, data.changes, data.comparison, baseline/candidate check summaries and raw evidence. A missing old URL/output blocks the update unless an observed redirect at its old output file proves preservation; unknown custom alias identity stays incomplete. This is not universal theme or browser compatibility. To apply the freshly revalidated reviewed plan, use its recorded ID:

oink upgrade --site ./my-docs --to v1.1.0 --write \
  --expect-plan 'COPY_PLAN_ID_FROM_PREVIEW'

The CLI changes only the selected go.mod and go.sum bytes after candidate validation. It preserves unrelated requirements, replacement directives, comments, and unrelated uncommitted work. --write refuses uncommitted changes to either selected file, and detects changes after planning. Recovery evidence identifies backups and any rollback that could not safely restore a concurrently changed file.

The ID binds current copied source bytes/modes/inventory and actual comparison, not just module-file text. A later source/workspace/dependency edit requires a new preview; only selected module files are applied. Unknown resolved pins or changed/unknown renderer/environment cannot pass. Comparison supports a single HTTP(S) base origin/path; multihost inputs stay incomplete. Emitted byte hashes also bind the ID, so nondeterministic templates can require a refreshed preview. No configuration migration is performed automatically; review unsupported changes manually.

An OINK go.mod replace is a blocking condition for this public-pin workflow. A site containing _vendor is also refused: this release does not refresh vendor content. Prepare a separate reviewed copy, update the intended pin and run hugo mod vendor explicitly, then review and validate the entire vendor change. A go.mod bump alone is never reported as a vendor upgrade.

Preview and build through Hugo

oink dev --site ./my-docs -- --port 1315 --bind 127.0.0.1
oink build --site ./my-docs -- --minify

Arguments after -- go directly to Hugo. The CLI shows the effective command and forwards process cancellation. dev runs hugo server; build selects the production environment by default and adds --panicOnWarning. These are direct Hugo operations by default and may create the site’s normal output and cache files. They do not run the reference checks performed by oink check.

Check and export one build

Choose a real publication URL in OINK_PUBLIC_BASE_URL, prepare the site’s exact dependencies, then use a fresh output directory and separate new manifest:

OINK_ARTIFACT_DIR=$(mktemp -d)
oink build --check --site ./my-docs --release \
  --base-url "$OINK_PUBLIC_BASE_URL" \
  --destination "$OINK_ARTIFACT_DIR/public" \
  --manifest "$OINK_ARTIFACT_DIR/build-manifest.json" --marker

Add --network to this operation only if its dependencies or required remote resources need downloading. An example/local publication address is a release error; ordinary diagnosis reports a warning. --release also checks actual public theme resolution independently of local Git history or declared pins.

Hugo renders one isolated production output. The CLI checks, seals and exports that same tree without rebuilding or changing site sources. Required incomplete coverage returns 2; blocking findings return 1. Neither result creates a verified export. An explicit scoped translation policy needing publication-excluded Hugo identities returns 2; run standalone check/translations for the full nonpublishable maintenance view, or deliberately select a production policy. The command does not infer identities from filenames.

The destination must be new or empty and its parent must exist. The manifest must be a new file outside the public tree. Existing entries are preserved; failed partial export remains explicitly unverified. Optional --marker adds only the artifact identity at .well-known/oink-build.json; without the flag, no marker is added. The local oink.artifact/v1 manifest records original input identity, known Git state, effective settings/theme/tools, required coverage, Hugo routes and exact file digests/modes. It excludes absolute local paths and logs and is saved with mode 0600. Keep it outside the upload.

Managed builds allow only --minify, --gc, --ignoreCache and --noTimes after --, with optional boolean =true/=false. The ordinary build example above still accepts transparent Hugo arguments.

Verify artifacts and a deployed site

Immediately before uploading, check the exported directory offline:

oink artifacts verify --artifact "$OINK_ARTIFACT_DIR/public" \
  --manifest "$OINK_ARTIFACT_DIR/build-manifest.json"

This compares the exact files, bytes and full modes. Missing, additional or modified files invalidate the previous identity. Upload this directory without rebuilding; preserve its hidden .well-known marker when enabled.

After a separately authorized deployment, check its public URL explicitly:

oink verify --site "$OINK_PUBLIC_BASE_URL" \
  --manifest "$OINK_ARTIFACT_DIR/build-manifest.json" --network

Verification reads every declared file and distinct actual Hugo route, including language/subpath URLs, and compares bounded decoded response digests plus recorded HTML canonical/language identities and the enabled marker. HTTP cannot inspect local file modes. Wrong content, a soft-404 or a different captured identity returns 1. Timeouts, authentication/rate-limit failures, server unavailability and a missing required marker return 2; redirects outside the selected origin/path are blocked. No credentials are discovered or sent. A build’s --network permission does not authorize this later request or any upload.

Retired CI generation

ci init is removed. Keep CI configuration in the site or Starter. Local CLI validation does not execute hosted CI or deploy a site. Previously saved CI plans are rejected by plans apply.

Check explicitly registered sites

Create a separate registry such as oink.workspace.yaml beside your selected projects. Its only site fields are name and directory; keep Hugo settings in each site and checking policy in that site’s oink.yaml.

schema_version: oink.workspace/v1
sites:
  - name: docs
    directory: ../docs-site
  - name: blog
    directory: ../blog-site

oink workspace list --workspace ./oink.workspace.yaml
oink workspace check --workspace ./oink.workspace.yaml --offline --json
oink workspace check links --workspace ./oink.workspace.yaml \
  --sites docs,blog --offline --json
oink check style --workspace ./oink.workspace.yaml --site docs --offline --json

Names are case sensitive ASCII identifiers matching [A-Za-z][A-Za-z0-9_-]{0,63}. A regular nonsymlink registry has one strict YAML document, 1–64 nonoverlapping sites and a 256 KiB limit. Directories are literal relative paths from its actual parent, or absolute paths; no environment/glob expansion or sibling discovery occurs. Canonical aliases identify the same site and cannot register it twice. Missing directories remain listed; their check returns 2, while the remaining explicit sites are still checked. The aggregate returns 2 before 1 before 0, preserving full per-site findings and coverage. Omitting --sites means all registered sites; an explicit list rejects blanks, duplicates and unknown names and keeps registry order.

A direct command needs --site NAME; there is no default registry site. init, artifacts and verify do not accept registry selection. Save a reviewed plan outside its site, then explicitly apply it to the same name:

oink translations review en:/docs/manual zh:/docs/manual \
  --workspace ./oink.workspace.yaml --site docs \
  --reviewed-by 'Maintainer' --reason 'Reviewed terminology and examples' \
  --reviewed-at 2026-10-03T00:00:00Z --plan ./review.plan.json --offline
oink plans apply ./review.plan.json \
  --workspace ./oink.workspace.yaml --site docs --offline

Use actual page identities returned by your site’s checks for the review selectors. Selecting blog for a plan bound to docs returns 2 before a source write. Preview, validation, freshness and byte/mode safeguards are the same as direct single-site use; no other registered or neighboring site is updated automatically.

Configure already provisioned optional tools

The CLI does not install markdownlint, Vale or lychee. After provisioning tools separately, add explicit entries to the selected site’s oink.yaml. The current protocols are markdownlint-cli 0.49.1, Vale 3.24.0 and lychee 0.24.2; other reported versions remain unsupported until qualified.

schema_version: oink.policy/v1
tools:
  markdownlint:
    required: false
    config: .markdownlint.yaml
    timeout_seconds: 60
  vale:
    required: false
    config: .vale.ini
    timeout_seconds: 60
  lychee:
    required: false
    config: lychee.toml
    timeout_seconds: 60

enabled defaults to true, required to false, and command to the kind’s name. You can select one provisioned executable by name or absolute path; commands are not shell snippets. Configuration paths must be clean relative paths inside the captured site. Process time defaults to 60 seconds, with bounded nondefault values 1–300. Unavailable optional tools show omissions; required unavailability or unsupported protocol returns 2. A problem baseline or lower rule severity cannot turn required incompletion into success.

Markdownlint and Vale belong to style; lychee belongs to links. Select the group whose tools you intend to run:

oink check style --workspace ./oink.workspace.yaml --site docs --offline --json
oink check links --workspace ./oink.workspace.yaml --site docs --network --json

The second command explicitly permits actual external HTTP requests. Without --network, lychee is not invoked: optional coverage is not_checked, required coverage returns 2. A successful native local-links check does not attest external availability. HTTP 401, 403, 408, 425, 429, 5xx, DNS/TLS failures and timeouts are inconclusive, not definite broken links. Other failed 4xx responses are typed findings. External locations remain actual output files and DOM pointers; the CLI does not guess their Markdown line.

For markdownlint, use declarative JSON, YAML or TOML, for example:

default: true
MD013: false

JS/JSONC configs, custom rules and extends are unsupported. The CLI stages a private rule object behind an unpredictable JSON pointer so upstream rc data does not change its effective rules. Vale requires an explicit INI and captured styles. A supported minimal configuration is:

StylesPath = styles
MinAlertLevel = warning

[*.md]
BasedOnStyles = Project

Provide declarative rule files under styles/Project/. Supported rule kinds are existence, substitution, repetition, occurrence, consistency, capitalization and sequence. Actions, scripts, packages, sync, conversion assets and style pipelines require manual review and are not executed by this adapter. Lychee accepts these bounded request settings:

timeout = 10
max_retries = 0
max_concurrency = 8

Allowed ranges are 1–300 seconds, 0–3 retries and 1–32 concurrent requests. The literal cache = false is also accepted; cache = true is refused. Cache and preprocessors are disabled; arbitrary extra tool arguments are not accepted. No adapter fixes or formats source files. Code prose is outside source attribution; Markdown structure and fence/inline code boundaries remain available to markdownlint, while Vale receives the prose-only mask. Private masks preserve proven UTF-8/BOM/CRLF boundaries around front matter, shortcodes, raw HTML, configured math and attributes; findings from excluded/synthetic text remain omissions. Only already captured site-owned Markdown is read for prose tools.

Inspect data.adapters, adapter.KIND coverage and raw evidence before interpreting an exit. Each adapter retains version/executable/configuration hashes and protocol provenance. Caller proxy URLs/credentials and Node preload settings are not forwarded; literal NO_PROXY/no_proxy host-list data may be retained for the qualified runtime. This does not disable every operating-system proxy route or create a network sandbox. Network checks do not verify external fragments, browser behavior or remote content identity.

Retired local Studio

studio is removed from the CLI. Use an ordinary editor and oink dev for a site preview. Read maintenance facts through inspect and structured reports. The dated R7 acceptance remains historical evidence for its identified inputs.

Retired Studio views

Read page and quality facts with inspect, check, and structured reports.

Retired browser targets

The CLI Studio browser test targets are removed with the implementation. Current CLI checks remain Go and actual Hugo tests.

Retired general editing

edit and Studio editing are removed. Edit source with an ordinary editor, then run check. new, move, review records, and baseline plans retain candidate validation and byte/mode guards. Previously saved editing plans are rejected. The dated R8 record remains historical evidence.

Retired edit commands

The edit text|field|snippet|attachment command family is removed. Run new --help or move --help for the retained bounded file workflows.

Retired Studio editing

The CLI does not serve an editor or accept browser Apply requests.

Retained plan review

Retained previews display the complete proposed diff. Save a new plan, then explicitly run plans apply FILE --site DIR. Candidate validation, source and external input guards, and concurrent-edit recovery remain required.

Network and offline operation

Network access is disabled by default; --offline makes that choice explicit. Missing dependencies produce an incomplete result. The CLI does not install Hugo, download a Go toolchain, change global configuration, or enable telemetry. Allow the current operation to use the network only when intended:

oink check --site ./my-docs --network

--network and --offline cannot be combined. Diagnostic and validation operations use disposable caches; a download there does not establish a persistent cache for the next offline run. For repeatable offline work, provision the exact module versions in a normal Go module cache and set GOMODCACHE explicitly as shown above. Include all transitive dependencies needed by your site. Isolated validation reuses provisioned module download artifacts, not Hugo’s global remote-resource (GetRemote) cache. A prewarmed remote-resource cache alone does not make this check work offline. Materialize required remote content as local site resources, or explicitly use --network for that build. Theme assets that already ship as local files do not require such a download.

Text, JSON, YAML, and automation

oink check --site ./my-docs
oink check --site ./my-docs --verbose
oink check --site ./my-docs -J > check.json 2> check.log
oink check --site ./my-docs -Y > check.yaml 2> check.log
oink translations review --help

Choose one structured format. Nonempty NO_COLOR or TERM=dumb also disables text colors. Structured output adds no terminal colors. Tool logs go to stderr. --format json|yaml and --non-interactive remain hidden compatibility options. Every command is non-interactive.

Default text shows status, counts, up to eight active findings, and explicit coverage omissions. Detailed facts and reviewed findings remain available in structured results. Plan and upgrade previews retain their complete diffs. Cobra owns command dispatch and focused help. CLI messages use short, active English sentences inspired by ASD-STE100; this does not assert certification. User content and external tool evidence retain their original language.

Always inspect coverage alongside the exit code. An exit code of zero from doctor does not prove a build, and a successful static check does not prove browser behavior or a public deployment. These commands do not commit, push, publish a theme, or deploy a site.

3 - Authoring

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

What a documentation page is made of

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

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

## Prerequisites {#prerequisites}

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

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

Save it as content/docs/install.md, run hugo server, and the page appears at /docs/install/ with an “Install” entry in the sidebar.

Content types and where they are covered

3.1 - Writing pages

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

Creating a page

A page is a Markdown file under content/, and its URL follows its position there: content/docs/install.md is published as /docs/install/. The Chinese translation is a .zh.md file of the same name in the same directory, sharing one logical path with the English page.

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

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

The front matter you need

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

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

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

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

Heading levels and stable anchors

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

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

## Prerequisites {#prerequisites}

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

There are two reasons:

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

## Getting started <a id="get-started"></a> {#quickstart}

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

Writing links

Three forms, for different purposes:

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

The theme has no link render hook: links go to Goldmark untouched. External links get no automatic target="_blank"; write HTML where a new tab is needed, or handle it in the site’s own layouts/_markup/render-link.html.

Plain Markdown links are not checked for existence. So:

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

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

Where images go

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

Drafts and publishing

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

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

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

OINK’s Markdown extensions at a glance

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

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

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

1. Install Hugo Extended, 0.160.1 at the oldest:
   ```bash
   brew install hugo
   ```
1. Clone 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.160.1 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

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

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

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

Verify

After writing a page, run a strict build:

hugo --printPathWarnings --panicOnWarning

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

Then confirm three things in the browser:

1. The page is in the sidebar, in the position weight implies;
2. The right-hand outline lists the ## headings you wrote, and clicking one puts an English anchor in the URL;
3. The English and Chinese versions of the same heading share an anchor (this site audits that with node scripts/check-doc-translations.mjs --public public).

Related

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

3.2 - Organizing content

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

Directories are the sidebar

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

Every directory needs an _index.md

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

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

A section _index.md has one further power: cascade pushes shared settings down the whole subtree once, instead of repeating them on every page.

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

Ordering: use multiples of 10 for weight

Pages in a section are sorted by ascending weight, and only equal weights fall back to date and linkTitle. Always use multiples of 10 (10, 20, 30) so a page can be inserted between two others without touching the rest. A section’s own weight decides its position among its siblings.

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

Single file or page bundle

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

List or cards on a section index

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

params:
  ui:
    section_index: cards # list | cards

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

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

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

Sidebar icons

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

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

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

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

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

Expanding and folding

A section with children carries a fold arrow in the sidebar. OINK saves the whole sidebar’s collapse, width, and scroll state; persisting individual branch choices is optional site code using the sidebar runtime API. The default behaviour: the path containing the current page is expanded and everything else is collapsed; blog-type sections are expanded by default.

sidebar_expanded: true   # this section is always expanded by default

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

Hiding from the sidebar

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

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, its button folds the children when sidebar folding is enabled, and 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; prefer never for an unpublished group so other navigation cannot invent 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 sidebar tree roots at the top-level section the reader is in, and a row above the tree names the current root. A large subtree can become a root of its own — a versioned API reference, say, or a self-contained handbook:

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

The switcher above the root is site-wide: it lists every top-level section plus every section anywhere that declares sidebar_root_for: self. With only one entry it degrades to a plain link; two or more make it a dropdown. To keep a top-level section 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 first link in the tree: the switcher picks a tree and the root link points at a document. sidebar_root_link_self: false makes that row point at the parent section instead.

Verify

hugo --printPathWarnings --panicOnWarning

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

Then confirm each of these in the browser:

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

When sidebar entries exceed params.ui.sidebar_menu_truncate, the build warns and says what to raise it to. That warning cannot be ignored: truncated entries never appear in the sidebar.

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 is the complete table of page-level parameters, listing the keys the OINK theme reads plus explicit 1.x compatibility no-ops. Keys the theme reads solely to warn that they were renamed or removed are not listed here — they 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 the rest) work as usual; their meaning is in the Hugo documentation. Site parameters (params.* in hugo.yml) are in Configuration.

How to read the tables

Precedence, highest first:

1. The page’s own front matter;
2. The nearest cascade (when several cascade layers set the same key, the one closest to the page wins);
3. The site parameter in hugo.yml.

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

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

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

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

cascade:
  pager: false
  section_index: list

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

No front matter key stops the build; the theme’s templates never raise an error. Where carrying on would publish something wrong rather than merely plain — an incomplete upstream attribution, for instance, because a partial notice reads exactly like a complete one — the warning is followed by omitting that block entirely rather than by a fallback. The one thing here that does stop a build belongs to Hugo, not the theme: a reference that cannot resolve.

Basics

Sidebar and navigation

The guide is Organizing content.

Page shell

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

Search

The guide is Search.

Output formats

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

Page end: comments, feedback and provenance

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

Upstream attribution

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

upstream_link is read from front matter only (a cascade counts, site parameters do not) — a site-wide value would make every page claim the same source. 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 is worse than an obvious omission. The theme ships an SPDX table at data/licenses.yaml, and a site adds to or overrides it with a file of the same name.

Image zoom

Blog posts

The guide is Blog posts.

Book

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

Landing

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

Release pages

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

Related

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

3.4 - Blog posts

A blog post’s body is written exactly like a documentation page; the shell is what differs. A post carries a date, an author, tags and a featured image, the list is ordered by date newest first, and the section has an RSS feed. This page covers creating the blog section, a post’s front matter, featured images, list pagination and feeds.

The blog directory

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

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

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

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

Blog sections are expanded by default in the sidebar and ordered by date, newest first; giving one post a weight pins it to the top.

A post’s front matter

---
title: Oink 0.4.0 — scenario components for a complete release workflow
linkTitle: Oink v0.4.0        # short name in the sidebar and pager
date: 2026-08-14              # publication date; decides 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 date in the future is not built by default; hugo server -F previews it.
• description is rendered as a standfirst above the body, not only as a search snippet, so write it as a sentence for the reader.
• author accepts inline Markdown, so [Vonng](https://vonng.com) works. For more than one author, a portrait, or a profile page, use the authors taxonomy below instead; the two do not interfere, and a post keeps rendering author wherever authors is absent.
• The date display format comes from params.time_format_blog and can be set per language (this site uses Monday, January 02, 2006 in English and 2006年1月2日 in Chinese).

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

Featured image

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

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