Skip to content

Highlights

Compare OINK with an ordinary Hugo theme. Each feature links to its guide.

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

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

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.