Content on OINK

Authoring

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

This chapter is about how to write. The available building blocks are in Components; site-level settings are in Site configuration.

In this chapter

Organize content: the content tree, sections, page bundles, front matter
Writing conventions: Markdown, alerts, links, bilingual authoring
Images and media: logos, favicons, icons, and images
Taxonomies: taxonomy configuration and multilingual support

Organize your content

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

Oink derives the documentation sidebar from Hugo’s content tree. The directory structure is therefore part of the reader experience, not just a source-code detail. Start with the questions readers need answered, then create the smallest hierarchy that makes those answers easy to find.

Start from reader goals

Give new readers a short path from product context to a successful first task. Give returning readers direct routes to procedures, reference material, and troubleshooting. A practical documentation set usually needs:

Hugo authoring tips

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

Oink is a Hugo theme, so ordinary Markdown and Hugo’s content model remain the authoring foundation. These conventions keep pages readable in source form and stable after translation, reorganization, or subpath deployment.

Link to published routes

Link readers to the canonical published URL, not to a neighboring source-file path. Root-relative links such as /docs/content/ are easy to audit across the site. When a link should follow a page through source moves, Hugo’s ref and relref shortcodes can resolve the target page:

Logos and images

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

Add brand marks

Oink uses assets/icons/logo.svg as its default brand mark. Override it with params.logo, or set params.wordmark when the header should show a complete wordmark instead of an icon followed by the site title:

YAML

params:
  logo: icons/product.svg
  wordmark: images/product-wordmark.svg

Both parameters can name a Hugo asset or a public path. Prefer assets/ for theme-processed files and static/ when a file must be copied unchanged. Keep the source SVG tightly cropped so the header, sidebar, and footer can size it consistently.