What is OINK

• 1: Highlights
• 2: Case Guide
• 3: License and acknowledgements
• 4: Contributing to OINK

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

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

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

What the theme provides

• The documentation and blog shell provides navigation, a sidebar tree, a table of contents, breadcrumbs, a pager, dark mode, print view, and accessible interaction.
• The multilingual structure provides translation routing, fallback for untranslated pages, language weighting, RTL, 32 complete interface catalogs, and an opt-in duo view (params.ui.compare: true) for side-by-side reading.
• Local browser features include Mermaid, Markmap, Swagger UI, Redoc, Asciinema, ECharts, Infographic, and full-text search. Mathematics is rendered by Hugo at build time and uses local KaTeX styles.
• Content components include callouts, tabs, steps, cards, field lists, file trees, galleries, badges, keys, and more. Most have a native Markdown form.
• Additional content types provide built-in book numbering and cross-references, release and download pages, data-driven landing pages, and OpenAPI reference pages.

The theme does not handle source hosting or deployment. A site can use GitHub, GitLab, or a private Git server. You can publish Hugo’s static output anywhere. The site owns its content, brand, and business components. The theme supplies the shell and reusable components.

Is OINK for me

A good fit when	A poor fit when
The site has many pages and combines documentation, a blog, a book, release pages, and an API reference	The site has one or two pages and needs no structured navigation. A README or a lighter Hugo theme is simpler
You need full multilingual support rather than only a translation link on an English site	The site is mostly application UI. OINK can provide its documentation. Business components remain at the site layer
Reproducible builds and network isolation matter, and the build machine has no outbound access	You need interactive components inside the prose (React / MDX)
Several sites need a shared shell without copies of layouts and shortcodes	You want one switch to change the appearance. The theme has no brand switch. Appearance changes require CSS tokens and partial overrides
The team has no front-end engineers and maintains no Node toolchain	You need a built-in CMS or a WYSIWYG editor

How it differs from other documentation systems

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

Your priority	What to evaluate
Keep an existing Hugo content workflow	Compare OINK with Docsy and Hextra using your own content tree, overrides, and language needs
Build without a Node toolchain	OINK includes browser assets in the theme. Hugo Module installation still needs Go to resolve modules
Write React components inside documentation	Evaluate an MDX-based system such as Docusaurus. OINK’s main authoring model uses Markdown, attributes, and shortcodes
Publish books, downloads, or data-driven landing pages	Try OINK’s built-in patterns on one representative page before adopting them site-wide

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

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

Start here

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

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

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

1 - Highlights

This page lists the differences between OINK and an ordinary Hugo theme. Each item links to its guide. To install OINK now, see Quick start.

Components are written in Markdown

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

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

→ Components

Build with Hugo

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

The interface runs JavaScript in the browser: search, the command palette, diagrams and tabs are page scripts. The theme includes those scripts. Each page receives only the scripts it uses.

→ Quick start

Local-first

Everything the browser needs is committed to the theme repository: Bootstrap, Font Awesome, four fonts, Lunr, Mermaid, KaTeX, Markmap, Swagger UI, Redoc, Asciinema, ECharts, Infographic, and the local PlantUML engine. VENDOR.json records the version, source, license file and SHA-256 checksum of each dependency. When you update a runtime, update its artifact, license, and checksum together.

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

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

→ License and acknowledgements · Configuration

One source, four outputs

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

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

→ Print · AI-agent support

Two languages and 32 interface locales

Multilingual support uses Hugo’s own mechanism: translation routing, a language picker ordered by weight, fallback for untranslated pages, RTL, and canonical and alternate metadata. Interface strings come in 32 language packs sharing one 235-message schema. These include all 31 locale filenames that Docsy supports, plus generic zh. Every pack contains native OINK interface text instead of English placeholder blocks. zh and zh-cn use Simplified Chinese. zh-tw uses Traditional Chinese. Setting params.ui.compare: true adds an opt-in duo view so readers can open an existing translation beside the current page and scroll both versions together.

→ Languages · Duo view

Full-text search that stays on the site

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

→ Search

Command palette

Cmd/Ctrl + K opens the command palette. A bare / enters search mode. A bare \ enters command-only mode. The palette contains pages, commands, and page actions, such as switching language, switching theme, and copying Markdown. Use the same entry point to search and run actions.

→ Command palette

Keyboard navigation

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

→ Keyboard navigation

Backlinks

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

→ Backlinks

Four content types beyond documentation

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

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

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

Output for AI assistants

Add markdown to outputs. Each page then has a .md version. Its HTML <head> has a rel="alternate" reference to that version. Page actions include “Copy Markdown” and “View source”. The LLMS output format writes an llms.txt inventory at the site root (this site’s is https://oink.pgsty.com/llms.txt).

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

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

→ AI-agent support

Versions

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

→ Versions

See for yourself

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

1. Press Cmd/Ctrl + K on any page. Type postgres to see local search results. Press \ for command-only mode.
2. Append index.md to the current page address to get this page’s Markdown version.
3. Open https://oink.pgsty.com/llms.txt, the site inventory for AI assistants. It links to the docs section’s llms-full.txt and to navigation.json.
4. Look at this page’s right rail. “Backlinks” lists the pages that link here.

Related

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

2 - Case Guide

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

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

Distribution documentation

pigsty.io

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

pigsty.cc

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

pgsty.pro

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

Product documentation

PIG

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

SOW

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

SILO

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

PG Exporter

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

Books

Designing Data-Intensive Applications

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

The Product-Minded Engineer

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

PG Internal

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

Aggregate, landing, and custom sites

PostgreSQL ecosystem library

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

pgsty.com

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

Capslock

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

oink.pgsty.com

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

pgext.cloud

This PostgreSQL extension catalog uses a queryable dataset as its primary object. It indexes 2,241 extensions and 576 packaged builds across 16 platforms.

Choosing a starting point

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

The theme repository’s tests/site/ is an internal CI fixture. Do not use it as a starter template. Its pages test rendering behavior. Use the production cases above as design references.

→ Browse all cases · Quick start · Repository tour

3 - License and acknowledgements

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

Which licence covers what

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

Community contributors

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

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

Upstream: Docsy

The theme’s NOTICE records these facts:

• OINK is derived from Docsy, Copyright 2018 Google LLC and Docsy contributors.
• OINK’s own theme work is Copyright 2026 PGSTY contributors.
• The project and its upstream both use Apache License 2.0. VENDOR.json records each third-party browser dependency’s license, source, version, and checksum. Each required NOTICE file accompanies its asset.
• The Docsy name and Google’s trademarks belong to their respective holders. These names identify the upstream project and imply no endorsement.

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

Third-party runtimes shipped with the theme

The theme commits everything the browser needs to the repository (assets/third_party/, assets/js/third_party/, static/webfonts/). These assets need no npm step or build-time download. Hugo Module resolution still needs Go and an available module source. VENDOR.json is the machine-readable manifest for these assets. Each entry records the name, pinned version, source URL, license file path, and SHA-256 of every selected artifact. It also records an aggregate checksum for each of the three asset trees.

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

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

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

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

Fonts and icons

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

The theme makes no request to a remote font service. The repository has no Google Fonts link. The site always serves fonts from its own baseURL. To change fonts or switch to the platform stack, see Brand and appearance.

Design references

Docsy is the only code upstream. The projects below are references for the design language. They supply no code or runtime dependencies. OINK has ported no code from them:

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

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

Reusing this documentation

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

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

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

Reusing the theme

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

Apache-2.0 grants no trademark rights. It does not change third-party assets into Apache-licensed works.

Related

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

4 - Contributing to OINK

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

Where to contribute

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

Report a reproducible problem

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

Build and check

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

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

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

npm ci
make check
make browser

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

Prepare a pull request

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

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

Credit and licences

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

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