Authoring
This section covers all content types supported by OINK: documentation pages, blog posts, books, Expo image albums, release and download pages, and OpenAPI references. They share a single Markdown dialect and front matter schema, while each content type adds its own layout conventions.
What a documentation page is made of
Every documentation page is a single Markdown file. YAML front matter between
the opening --- lines sets the page metadata (title, linkTitle,
description, and weight), followed by standard Markdown and OINK’s native
components:
Save the file as content/docs/install.md and run hugo server. The page is
served at /docs/install/ with an Install entry in the left sidebar.
Common Markdown patterns
Most everyday components use standard Markdown plus a Goldmark attribute block rather than custom shortcodes:
| Pattern | Syntax | Guide |
|---|---|---|
| Explicit heading anchor | ## Prerequisites {#prerequisites} |
Writing pages |
| Callout / admonition | > [!NOTE] (TIP, IMPORTANT, WARNING, CAUTION, DETAILS) |
Callouts |
| Code tabs | Adjacent code fences with ```bash {tab="macOS"} |
Tabs |
| Numbered steps | An ordered list followed by {.steps} on the next line |
Steps |
| Navigation cards | A bullet list of links followed by {.cards} on the next line |
Cards |
| Parameter / field table | A Markdown table followed by {.fields} on the next line |
Fields |
| Captioned or sized image |  followed by {width="800" caption="..."} |
Images |
| File tree | A ```filetree fenced block using a YAML-like list |
FileTree |
Content types and where they are covered
| What you are writing | Where to go |
|---|---|
| A documentation page: front matter, heading anchors, links, images, drafts | Writing pages |
The tree and the sidebar: _index.md, weight, icons, folding, multiple sidebar roots |
Organizing content |
| Looking up what a front matter key means | Page parameters |
| A blog post, a release announcement, RSS | Blog posts |
| A book: chapter numbering, figures and tables, cross-references, whole-book print | Books |
| An image album: file structure, metadata, layouts, and the image viewer | Expo albums |
| A release and download page: version cards, asset tables, checksums | Releases and downloads |
| An OpenAPI reference page | API reference pages |
| Writing in two languages: paired files, aligned anchors, fallback for untranslated pages | Languages |
| A component’s syntax and parameters | Components |
Create a documentation page. Learn where to save it, how to set front matter and anchors, and how links, images, and page-end controls work.
Use the directory structure to create the sidebar tree. Configure _index.md, weight, index styles, icons, folding, hidden pages, and documentation paths.
The full front matter table — active page keys and retained 1.x compatibility no-ops, grouped by sidebar, shell, search, output, page end, Book, Expo, landing and release pages.
Set up a blog section. Learn directory conventions, post front matter, featured images, the date-ordered list page, and RSS.
Turn a directory tree into a book with type: book: chapter numbering, numbered figures and tables, cross-references, generated indexes and whole-book print.
Create an image album, add optional metadata, select a layout, and use the image viewer.
Record versions, tags, archive links, checksums, and install commands locally. Release cards, asset tables, download blocks, and index pages use these records.
Add an OpenAPI specification to the site. Use bundled Swagger UI or Redoc to render a browsable API reference without a CDN.