Authoring
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:
Save it as content/docs/install.md, run hugo server, and the page appears at
/docs/install/ with an “Install” entry in the sidebar.
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 |
| 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 |
Creating a documentation page — where the file goes, what the front matter says, why heading anchors are written by hand, how links and images work, and what appears at the end of a page on its own.
The directory structure is the sidebar tree — _index.md and weight, section index styles, icons and folding, hiding pages, and putting documentation at any path.
The full front matter table — every page key the theme actually reads, grouped by sidebar, shell, search, output, page end, Book, landing and release pages.
Setting up a blog section — directory conventions, a post’s front matter, featured images, the year-grouped 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.
Record versions, tags, archive links, checksums and install commands as local facts, then let release cards, asset tables, download blocks and index pages derive from that one record.
Put an OpenAPI specification on the site and render it as a browsable API reference with the bundled Swagger UI or Redoc, without touching a CDN.