Authoring on OINK

Writing pages

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

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.

Organizing content

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

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.

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:

Page parameters

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

This page is the complete table of page-level parameters, listing only the keys the OINK theme reads. 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:

The page’s own front matter;
The nearest cascade (when several cascade layers set the same key, the one closest to the page wins);
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.

Blog posts

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

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 grouped by year 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. Do not create year directories: the year grouping is generated by the list page.

Books

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

A book is a content tree of type: book: the directory decides chapter order, front matter decides chapter numbers, and figures, tables, equations and examples each carry a hand-written number and a stable anchor. Cross-references resolve in all four outputs, and the book’s root page can generate a whole-book print HTML.

Two prerequisites: the site’s markup.goldmark has attribute lines and passthrough enabled (see Components); and params.ui.shell_types still contains book (the theme default includes it).

Releases and downloads

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

OINK keeps release facts in two local places: a release_url in a page’s front matter names the GitHub release this page is about, and data/download/<key>.yaml says how to install it. Release cards, asset tables, download blocks and index pages all derive from those two. Nothing contacts GitHub at build time, and nothing claims a tag or an asset already exists.

This page carries demonstration release facts

Its front matter holds a release_url (OINK v0.4.0), and the card, asset table and download block below are really rendered. The checksums and asset filenames are fabricated: the URLs are derived locally from the repository and the tag, the files they point at do not exist in any real release, and the hashes here must not be used to verify anything.

API reference pages

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

An API reference page is one OpenAPI specification plus one shortcode. The Swagger UI and Redoc runtimes ship with the theme (versions 5.32.13 and 2.5.3 respectively, per the repository’s VENDOR.json), load only on a page that uses them, and reach no external service at build time or in the browser.

Three steps: put the specification file under static/, create a page with the shortcode, and change the page type to swagger if it needs the dedicated shell.

Authoring on OINK

Writing pages

Creating a page

Organizing content

Directories are the sidebar

Page parameters

How to read the tables

Blog posts

The blog directory

Books

Releases and downloads

API reference pages