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:

Authoring

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

This section covers the content types OINK supports: documentation pages, blog posts, books, release and download pages, and OpenAPI references. They share one Markdown dialect and one front matter schema, and each adds its own conventions.

What a documentation page is made of

A documentation page is one Markdown file. Between the two --- lines at the top is the front matter — the page’s metadata: title, short sidebar name, description, ordering. The rest is the body: ordinary Markdown plus OINK’s native components. Here is a complete page:

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. Keys the theme reads solely to warn that they were renamed or removed are not listed here — they are in Migration, and they are also kept out of the generated editor schema. 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.

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 in its HTML output, and reach no external service at build time or in the browser. Swagger UI’s online validator is pinned off (validatorUrl: null), so a published API page never sends its specification address anywhere.

Authoring on OINK

Writing pages

Creating a page

Organizing content

Directories are the sidebar

Authoring

What a documentation page is made of

Page parameters

Blog posts

The blog directory

Books

Releases and downloads

API reference pages