Customization on OINK

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

This is the single home of site parameters. Every key the theme reads has a row in one of the tables below, giving its type, default and a one-line description, and linking to the guide that covers it. The guides give pasteable snippets and never repeat the definitions. Page-level parameters (front matter) are in Page parameters.

The tables are grouped by function, one ## each, and the anchors are referenceable — for example /docs/customize/config/#sidebar. An empty default column means the theme has no default: leave the key out and the feature is off.

Brand and appearance

Mon, 01 Jan 0001 00:00:00 +0000

This page covers a site’s appearance: the name and logo live in hugo.yml, colours and fonts go through SCSS entry points, and page width and footer shape are parameters. It assumes the site already builds (Quick start).

There are four things to change: hugo.yml, the icons under static/, assets/scss/_variables_project.scss, and assets/scss/_styles_project.scss. Do not edit files inside the theme directory: the theme is a Hugo Module, and an upgrade replaces the whole directory.

Home and landing pages

Mon, 01 Jan 0001 00:00:00 +0000

The home page is not a template but a data file: the sections list in data/home/<language>.yaml decides which sections the page has from top to bottom, and each section’s content is looked up by name in the same file. An ordinary page with layout: landing uses the same sections.

Every section is rendered on the server. Prices, star counts, screenshots, avatars and download states all have to exist in the repository before Hugo starts; no section fetches data in the browser.

Navigation and menus

Mon, 01 Jan 0001 00:00:00 +0000

This page covers the ways a reader moves between pages: the navbar menu, the section switcher, breadcrumbs, page actions, previous / next, and the footer. The sidebar tree and the outline belong to Layouts and page types.

Navigation has no second information architecture: the navbar comes from Hugo’s menus.main, and the sidebar from the shape of content/. The theme reads no parallel navigation tree such as a docs.json or a navigation.yaml.

Layouts and page types

Mon, 01 Jan 0001 00:00:00 +0000

This page covers a page’s skeleton: whether it has a sidebar, how wide that is, how deep the outline goes, and whether a section index is a list or cards. Where content goes is in Organizing content; this page is only about the shell.

The rule is that the shell follows type, not the path. Documentation can live anywhere under content/ as long as it has type: docs.

Shell types

params.ui.shell_types lists the types that use the reading shell with a sidebar:

Search

Mon, 01 Jan 0001 00:00:00 +0000

OINK’s search is local search: Hugo generates one JSON index per language at build time, the reader’s browser downloads it, and the search runs in the browser. No crawler, no account, no CDN, and no network access. The theme leaves it off, and one line of configuration turns it on.

The entry point to search is the command palette; how to open it and what else it holds are in Command palette.

Command palette

Mon, 01 Jan 0001 00:00:00 +0000

The command palette is the site’s one modal entry point: searching pages, copying this page’s Markdown, switching language, switching version and jumping to a site’s own links all happen in one dialog. It is assembled together with local search: with params.offline_search off, the palette, the index and Lunr all stay out of the page — see Search.

Opening the palette

How to open it	What opens
Click the search box in the navbar or sidebar	Full search mode
`⌘` / `Ctrl` + `K`	Full search mode; press again to close
`/`	Full search mode
The backslash key	Command-only mode (equivalent to a prefilled `>`)
`f` / `c`	The same two, provided by keyboard navigation
Typing a query beginning with `>` in the box	Command-only mode

/, backslash, f and c are all bare single keys and stand down for typing: while focus is in an input, textarea, select or contenteditable, and while an input method is composing, they type an ordinary character. The modified ⌘/Ctrl + K has no such restriction and opens the palette even from inside a text box.

Keyboard navigation

Mon, 01 Jan 0001 00:00:00 +0000

OINK’s interactive pages come with a set of single-key shortcuts: WASD moves through the sidebar tree, J K jump between headings, Q E page back and forward, and a few more toggle the theme, the language and the command palette. They are on by default, every binding stands down for typing, and they can be turned off per site or per page.

Keyboard navigation keeps no second copy of any state: expanding and collapsing reuses the sidebar’s own arrow buttons, section jumps read the right-hand outline, and switching language and theme reuse the command palette’s actions. Keyboard order and mouse order are therefore the same order.

Languages

Mon, 01 Jan 0001 00:00:00 +0000

OINK uses Hugo’s multilingual model and adds no directory conventions of its own: configure a languages block, and keep a translation beside its original in the same directory, distinguished by a filename suffix. What follows covers what a single-language site has to change to become bilingual, plus the two things bilingual sites get wrong: resource ownership and heading anchors.

Enabling a second language

defaultContentLanguage: en

languages:
 en:
 label: English
 locale: en-US
 weight: 1
 title: OINK
 params:
 description: A Hugo theme for engineering docs
 zh:
 label: 简体中文
 locale: zh-CN
 weight: 2
 title: OINK
 params:
 description: 为工程而设计的 Hugo 文档主题
 time_format_default: 2006年1月2日
 time_format_blog: 2006年1月2日

That is this site’s configuration. What the four fields do:

Versions

Mon, 01 Jan 0001 00:00:00 +0000

When a product has several supported versions, its documentation usually needs versions too. The theme provides two things: a version switcher in the navbar, and an archive banner on older sites. The deployment layout is the site’s decision — the theme does no cross-version build, and each version is its own Hugo build.

List the versions that should appear in the menu under params.versions. When that list is non-empty, a branch-icon menu appears in the navbar’s utility area, with the same content in an icon-only upward menu in the footer’s bottom bar.

Taxonomies

Mon, 01 Jan 0001 00:00:00 +0000

A directory tree gives a page one path; a taxonomy gives it a second. The same PostgreSQL backup document sits under an “Operations” directory and is also reachable from a “backup” tag page. Enabling it needs only Hugo’s taxonomies: configuration: the term pages, filter chips, rail cloud and navbar panel are all generated by the theme, with no template to write.

This page carries a category. The “Categories: Customization” line under the title, and the counted chips under the outline in the right column, need no configuration on the page itself.

Repository links and page info

Mon, 01 Jan 0001 00:00:00 +0000

The repository-related entries in the action menu at the right of the breadcrumb row are derived from a few github_* parameters, and the “last modified” line at the page end comes from git history. Both assume the content lives in a GitHub-style repository.

Four keys wire up every link

Every repository-related entry in the action menu derives from these keys:

params:
 github_repo: https://github.com/pgsty/oink.pgsty.com # the documentation source repository
 github_project_repo: https://github.com/pgsty/oink # the product repository (optional)
 github_branch: main # defaults to main
 github_subdir: '' # path from the repository root to the Hugo site root

That is this site’s real configuration. With it filled in, this page’s action menu points at:

Print

Mon, 01 Jan 0001 00:00:00 +0000

Printing one page needs no configuration: the shell (sidebar, outline, navbar, buttons) all carries d-print-none, so the browser’s Cmd/Ctrl+P yields a clean body. That is why the theme has no per-page “print this page” button.

What does need configuration is the other thing: assembling a whole section (or a whole book) and all its pages into one continuous document with a table of contents. What follows covers enabling it, the structure of the print view, and how to exclude pages.

AI-agent support

Mon, 01 Jan 0001 00:00:00 +0000

An HTML page carries a sidebar, scripts and styles, and a model has to strip that shell before reading it. OINK emits the same content a second time as plain Markdown: one .md per page, one llms.txt index at the site root, and a “copy as Markdown” button on the page. All three are build-time artifacts, with no runtime service and no content negotiation.

All three have to be declared by the site under outputs; the theme does not turn them on. Two further artifacts, equally opt-in, serve an agent that wants more than one page at a time: a full-text bundle per section and a navigation tree per language.

Customization on OINK

Configuration

Brand and appearance

Home and landing pages

Navigation and menus

Layouts and page types

Shell types

Search

Command palette

Opening the palette

Keyboard navigation

Languages

Enabling a second language

Versions

The version switcher

Taxonomies

Repository links and page info

Four keys wire up every link

Print

AI-agent support