Skip to content

Write Beautiful Docs

A practical tutorial for creating clear, beautiful, and maintainable technical content with OINK.

Write Beautiful Docs

A practical tutorial for creating clear, beautiful, and maintainable technical content with OINK.

Write Beautiful Docs is the hands-on tutorial companion to the OINK reference. While the reference documents every parameter and component, this book walks through one Starter site from its first local preview to a reviewed, published bilingual site.

How to read this book

Start with Chapter 1: Start with a working site. Each chapter builds on the same Starter checkout: previewing locally, adding bilingual pages, composing clear prose and components, shaping the site’s brand and home page, choosing publishing layouts, and verifying the production build before shipping. The object indexes below also demonstrate Book publishing features; use them to locate any figure, table, equation, or code example in the book.

Contents

Figures

  1. Figure 1-1 — Documentation-site illustration. Your Starter preview uses neutral sample content; the first milestone is a site you can open and edit.

Tables

  1. Table 2-1 — One explicit order is reused by navigation, paging, and generated contents.
  2. Table 6-1 — Four verification stages from local preview to live deployment, and what each stage leaves to the next step.
  3. Table A-1 — One source tree can expose several purpose-specific Book outputs.

Equations

  1. Equation 3.1 — A page fails when any one of clarity, accuracy, or consistency falls to zero.

Examples

  1. Example 3-1 — The same page now states a prerequisite, a command, and a visible result.

1 Start with a working site

Install the prerequisite tools, run a local preview, and establish a visible baseline before changing the design.

A good tutorial begins with a result the reader can see. For OINK, that result is the official Starter served locally by Hugo Extended—before any logo, palette, language set, or content architecture is changed.

Define the outcome

At the end of this chapter you should have English, Chinese, and French home pages; working Docs, Blog, and Book routes; local search; and a color-mode control. That small baseline is enough to distinguish a content mistake from a theme or deployment problem later.

The OINK documentation site home page
Figure 1-1 Documentation-site illustration. Your Starter preview uses neutral sample content; the first milestone is a site you can open and edit.

Install the prerequisite

Install Git, Go 1.27.3 or newer, and Hugo Extended 0.168.0 for this tutorial. Styles compile with Hugo Extended’s built-in LibSass, so no external Sass compiler or Node.js installation is required. If you started from an older Starter template, update its GitHub Actions workflow to Hugo Extended 0.168.0 as well.

$ go version
go version go1.27.3 darwin/arm64
$ hugo version
hugo v0.168.0+extended+withdeploy darwin/arm64

Run the preview

Create a repository with GitHub’s Use this template action when it will become a real project. To evaluate the original locally, clone it and start Hugo:

$ git clone https://github.com/pgsty/oink-starter.git my-docs
$ cd my-docs
$ hugo server

Open the address Hugo prints. Change one sentence in data/home/en.yaml and confirm that the browser shows it. A preview that responds to a content edit is more useful evidence than a terminal that only says the server started.

Record the baseline

Before customizing anything, record four facts: the Hugo version, the theme version in go.mod, the commit under review, and the routes you opened. Chapter 2 turns that running site into a content tree without losing this baseline.

For the complete layered workflow, see Use OINK Starter. For installation without the template, see From scratch.

2 Give the content a structure

Turn directories, section indexes, page bundles, and weights into one predictable reading and navigation order.

OINK does not keep a second navigation database for an ordinary site. The content tree is the sidebar tree, and the same order drives the pager and the Book contents. A reader should not encounter three different answers to “what comes next?”

Start from the reader’s questions

Name the top-level sections after tasks or subjects the reader recognizes. A small engineering site usually needs a start section, a reference, operations guidance, and a record of change. Add a directory only when it gives several pages a useful shared context.

Keep the Starter from Chapter 1, including its existing examples. In this chapter, add one English page and its Chinese peer under the existing Docs section. French can remain enabled; this exercise adds only the two peers below.

Build the tree

Files used by this exercise; other Starter files stay in place

  • content/
    • docs/
      • _index.mdexisting section root
      • _index.zh.mdexisting translated root
      • preview-check.mdadd this page
      • preview-check.zh.mdadd its translation

Create these two files with the complete contents below. The section roots already exist; do not replace them.

content/docs/preview-check.md
---
title: Verify a local preview
description: Check that a documentation edit reaches the browser.
weight: 25
---

## Check the preview {#check-preview}

Open this page locally, change this sentence, and confirm the browser updates.
content/docs/preview-check.zh.md
---
title: 验证本地预览
description: 确认文档修改已经显示在浏览器中。
weight: 25
---

## 检查预览 {#check-preview}

在本地打开本页,修改这句话,再确认浏览器已显示新内容。

A translation sits beside its English source with the .zh.md suffix. These pages have no images or downloads, so individual Markdown files are enough; use a page bundle when a page owns those resources.

Keep order explicit

The existing sections use spaced weights. The new page uses 25 so it can fit between neighbors without renumbering them. Keep the same weight on both translations. For a new tree, multiples of ten leave similar room to grow:

Item Weight Why it comes here
Get started 10 Establish the working baseline
Write content 20 Build on a running site
Customize 30 Change presentation after structure
Operate 40 Validate and publish the result
Table 2-1 One explicit order is reused by navigation, paging, and generated contents.

Make stable addresses

Write an explicit ID on every heading another page may cite. The English and Chinese pages use the same ID even though their visible headings differ. This keeps links, the table of contents, and whole-book print aligned across both languages.

With hugo server running, open /docs/preview-check/ and /zh/docs/preview-check/. Both should appear in their Docs sidebar, and the language switch should open the matching peer. The heading in both pages should have #check-preview. Keep these files for Chapter 3.

For the complete rules, see Writing pages and Organizing content.

3 Compose a page worth reading

Combine prose, callouts, code, media, tables, and mathematics without turning the page into a component catalogue.

Components should clarify an argument, not compete with it. Begin with plain prose, then introduce structure only where a reader needs to compare, verify, copy, or pause.

Give every block one job

Write the sentence first

If you cannot state why a component belongs on the page in one sentence, leave it as prose until the need becomes clear.

Use a callout for a prerequisite or risk, a table for repeated fields, a code block for material the reader can run, and an image when shape or spatial relationships carry information that prose cannot.

Start from a small page contract

Continue with content/docs/preview-check.md from Chapter 2. Replace its contents with this complete example; the command inside the page is run from your site repository in a second terminal while the preview server stays open.

Example 3-1 The same page now states a prerequisite, a command, and a visible result.
content/docs/preview-check.md
---
title: Verify a local preview
description: Check that a documentation edit reaches the browser and builds with reviewed diagnostics.
weight: 25
---

## Check the preview {#check-preview}

> [!NOTE] Keep the preview server running
> Run the build below in a second terminal, from the site repository.

```bash
hugo --environment production
```

The command should exit cleanly. Refresh this page at
`http://localhost:1313/docs/preview-check/` and confirm that the new note and command
are visible in the browser.

Update preview-check.zh.md with the same task and command in Chinese. Keep weight: 25 and #check-preview; use /zh/docs/preview-check/ in its local URL. The title names the task, the description states the result, and the note explains where to run the command. Open both peers and test language switching again before adding more components.

Measure quality without counting decoration

A useful page balances three independent properties:

Q=Cclarity×Aaccuracy×Kconsistency Q = C_{clarity} \times A_{accuracy} \times K_{consistency}
Equation 3.1 A page fails when any one of clarity, accuracy, or consistency falls to zero.

The product form is intentional: visual polish cannot compensate for an incorrect command, and accurate prose still fails when readers cannot find or follow it.

Cross-reference the example and check

Use Example 3-1 as the source pattern, and use Equation 3.1 as the review question. Continue to Chapter 4: Shape the reading experience to customize the site’s identity, visual preset, and home page.

The component reference begins at Components. Read the individual page for a component only when the tutorial introduces a need for it.

4 Shape the reading experience

Turn a sound content structure into a recognizable, responsive, and bilingual publication.

Design begins after the content tree works. This chapter connects brand identity, visual presets, home-page composition, navigation, and bilingual alignment in your Starter checkout.

Establish the visual hierarchy

Start with title, lead, body, headings, and local navigation. A reader should understand which region owns the next action before color or ornament is added. OINK provides the hierarchy; site variables provide the identity.

Open hugo.yaml in your Starter repository and update the site title, canonical URL, visual preset, and brand accent color:

hugo.yaml
title: &siteTitle Acme Docs
baseURL: https://docs.acme.example/

params:
  ui:
    preset: paper
    preset_menu: [paper, slate, ink, terminal]
    dark_mode: true
    theme_color: '#245f94'
    typography: system

Save the file and check http://localhost:1313/. The YAML anchor updates the title across all enabled languages, and the Appearance menu in the top navbar lets readers switch between paper, slate, ink, and terminal in both light and dark modes.

Compose the home page

The home page is driven by data files in data/home/. Its YAML section list should tell a short story: what the project is, who it serves, and what readers can do next.

Edit data/home/en.yaml to point the primary hero action to the page you wrote in Chapters 2 and 3:

data/home/en.yaml
sections:
  - hero
  - cards
  - cta

hero:
  align: center
  eyebrow: Acme · Open Source Documentation
  title_lines:
    - words: [{ text: Clear operational guides }]
    - words: [{ text: for Acme. }]
  lead: Install, configure, and run Acme in production with copy-ready examples.
  actions:
    - label: Verify Local Preview
      url: docs/preview-check/
      icon: fa-solid fa-rocket
      style: primary
    - label: Browse Docs
      url: docs/
      style: ghost

Keep navigation predictable

Navbar entries, the shell root switcher, the sidebar, the outline, and the pager answer different questions. Review them together on desktop and mobile, and ensure the same content order remains visible in both languages:

  • Top navbar (menus.main on section roots): switches between top-level content areas (Docs, Blog, Book).
  • Left sidebar (directory tree + weight): shows where the current page sits in its section.
  • Right outline (page ## and ### headings): jumps within the current page.
  • Bottom pager: moves sequentially to the previous or next page in the current tree.

Design both languages at once

Treat translations as full peers from the start. Mirror your home-page change in data/home/zh.yaml so Chinese readers land on /zh/docs/preview-check/ with the same structure and actions:

data/home/zh.yaml
hero:
  eyebrow: Acme · 开源工程文档
  title: 清晰可靠的 Acme 运维指南。
  lead: 通过可直接复制的示例,在生产环境中安装、配置并运行 Acme。
  actions:
    - label: 验证本地预览
      url: docs/preview-check/
      icon: fa-solid fa-rocket
      style: primary
    - label: 浏览文档
      url: docs/
      style: ghost

Notice that url: docs/preview-check/ stays relative to the language root—OINK resolves it to /docs/preview-check/ in English and /zh/docs/preview-check/ in Chinese automatically. For the complete set of visual options and landing sections, see Brand and appearance, Home and landing pages, and Languages.

5 Publish more than reference pages

Use Docs, Blog, Case, Book, and release pages as distinct answers to distinct reader needs.

One site can publish several kinds of knowledge without forcing them into one layout. The content type selects the shell; front matter variants refine the presentation inside that shell.

Match the surface to the reader

  • Docs answer a task or reference question and expose their place in a tree.
  • Blog posts are dated articles with authors, taxonomies, feeds, and sharing.
  • Case pages explain how a real site applies the theme.
  • Book chapters form a deliberate reading sequence with stable references.
  • Release notes connect a version to migration and verification evidence.

Configure a Blog family

An ordinary Blog section can use horizontal entries (list), regular cards (cards), a compact table (table), or a cover gallery (gallery). OINK 1.4.0 supports all four. The blog layout guide covers selection, reader switching, and the gallery’s three arrangements.

A section that needs an immersive opening keeps the same type and changes four independent presentation keys:

type: blog
featured_image: hero
toc_style: flow
toc_taxonomies: false
sidebar_enabled: false

This is the same configuration used by Immersive reading, sharing the standard blog templates, feeds, and taxonomy pages.

Turn examples into Case studies

A Case index uses the Blog card form, while each internal page documents the site, source, language model, scale, and OINK features before linking to the live result. Giving each case its own overview page lets readers inspect how the site is structured before visiting the live URL.

Keep Book and Docs complementary

Reference pages remain exhaustive and independently searchable. A tutorial selects a path through that reference, introduces one decision at a time, and links back when a reader needs the full parameter table.

To see how a dated release announcement complements your documentation tree, add content/blog/release/0.2.0.md (and 0.2.0.zh.md) in your Starter checkout and link it directly to the guide you created in Chapter 3:

content/blog/release/0.2.0.md
---
title: Acme 0.2.0
date: 2026-10-28
description: Adds local preview verification and bilingual home-page navigation.
tags: [release, preview]
---

Acme 0.2.0 adds a repeatable local preview check before production builds.

## Highlights {#highlights}

- Added the [Verify a local preview](/docs/preview-check/) guide.
- Updated the English and Chinese home pages to link directly to the workflow.

Open http://localhost:1313/blog/release/0.2.0/. The release post announces when and why the change shipped, while /docs/preview-check/ stays the evergreen how-to reference.

6 Ship with confidence

Verify local previews, production builds, theme upgrades, and live deployments with a repeatable release checklist.

Shipping a documentation site moves through four stages: previewing locally, pinning or updating the theme module, running a clean production build, and deploying to your hosting provider. Checking each stage in order makes build or deployment problems easy to isolate.

Check each stage in order

Stage What it verifies What still needs checking
Local preview Pages, navigation, and edits render cleanly in hugo server Production base URL, draft exclusion, and clean module state
Theme module pin hugo mod graph resolves the target public tag in go.mod and go.sum Whether site content and overrides build cleanly against that tag
Production build Content, configuration, and go.mod build cleanly in --environment production Hosting workflow, CDN caching, and live public routes
Live deployment CI workflow succeeds and key public URLs load as expected Desktop and mobile layout across representative pages
Table 6-1 Four verification stages from local preview to live deployment, and what each stage leaves to the next step.

Validate the smallest useful surface

From your Starter repository, run a clean production build before pushing to your deployment workflow:

hugo --cleanDestinationDir --gc --minify --environment production \
  --printPathWarnings

Confirm that hugo mod graph resolves the expected release in go.mod, then follow the Starter deployment steps. An ordinary Starter site needs no npm build script or sibling theme checkout. If you are developing changes to the OINK theme itself, follow the theme-development workflow.

Review the rendered result

Automated checks catch broken links, duplicate IDs, invalid shortcodes, and accessibility regressions, while visual review checks layout and readability. Inspect representative English and Chinese pages at desktop and mobile widths, including Hero cropping, wide tables, navigation, theme controls, code blocks, and the whole-book print view.

Keep a release checklist

When opening a pull request or upgrading the theme, record the Hugo version, the theme version in go.mod, the build output, and the routes you reviewed against Table 6-1. Keeping a concise checklist in your pull request makes reviews and rollbacks straightforward.

The full operational references are Preview the site, Deploy the site, and Troubleshoot a build.

A Front matter patterns

Copy-and-adapt contracts for Book roots, chapters, immersive Blog posts, and generated Book outputs.

These patterns are intentionally small. Copy the fields that establish the content contract, then add presentation options only when a reader-facing need requires them.

Book section root

type: book
book_kind: book
outputs: [HTML, print, markdown]
cascade:
  type: book
  book_draft_banner: true

The root declares the Book shell and generated outputs. It does not need a chapter number; numbering belongs to the material that appears in the reading sequence.

Book chapter

book_kind: chapter
book_number: 1
book_status: draft
weight: 10

Use book_status: draft for a visible editorial state. Unlike Hugo’s draft: true, it keeps the page available in a normal build so reviewers can read the unfinished chapter.

Immersive Blog article

type: blog
authors: [oink, vonng]
featured_image: hero
toc_style: flow
toc_taxonomies: false
sidebar_enabled: false

The article remains part of the Blog family—feeds, authors, series, and sharing continue to work—while the keys above change only its reading presentation.

Generated output matrix

Output Scope Typical use
HTML One root or chapter Reading, navigation, and search
print The complete Book Review, printing, and PDF conversion
markdown The source-shaped Book Export and downstream processing
Table A-1 One source tree can expose several purpose-specific Book outputs.

The generated contents, figure, table, equation, and example indexes on the Book root prove these contracts together. Keep explicit heading and object IDs aligned between translations so every format preserves the same references.