Skip to content

Highlights

What separates OINK from an ordinary Hugo theme, one item at a time, each linking to the guide that covers it.

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

Components are written in Markdown

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

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

→ Components

One Hugo binary is enough

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

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

→ Quick start

Local-first

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

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

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

→ License and acknowledgements · Configuration

One source, four outputs

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

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

→ Print · AI-agent support

Two languages and 32 interface locales

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

→ Languages

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

→ Search

Command palette

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

→ Command palette

Keyboard navigation

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

→ Keyboard navigation

Four content types beyond documentation

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

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

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

Output for AI assistants

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

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

→ AI-agent support

Versions

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

→ Versions

See for yourself

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

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