Write Beautiful Docs

Write Beautiful Docs is the tutorial companion to the OINK reference. The reference tells you what each parameter and component does; this book follows one site from its first local preview to a reviewed, published result.

The first three chapters contain working material. Later chapters deliberately show the Book draft state while their full walkthroughs are being written.

Contents

Figures

1. Figure 1-1 — The first milestone is a site a reader can open, not a configuration file that merely looks plausible.

Tables

1. Table 2-1 — One explicit order is reused by navigation, paging, and generated contents.
2. Table 6-1 — Each delivery state needs its own evidence and handoff.
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 — A page contract with one stable title, one summary, and an explicit place in the tree.

How to read this book

Read chapters 1–3 in order when starting a site. Return to chapters 4–6 when you are shaping the public presentation and preparing a release. The appendix is a copy-and-adapt reference for the front matter patterns used throughout.

1 Start with a working site

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

Define the outcome

At the end of this chapter you should have an English home page, its Chinese peer, working Docs and Blog 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.

Install the prerequisite

OINK consumers need Hugo Extended 0.160.1 or newer. Node.js is part of this repository’s maintainer test harness, not a requirement for building an ordinary consuming site.

$ hugo version
hugo v0.160.1+extended

Run the preview

Clone the documentation site, enter the checkout, and start Hugo with drafts, future content, and expired content visible:

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

Open the address Hugo prints. Change one sentence in content/_index.md 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 installation alternatives, see Quick start and From scratch.

2 Give the content a structure

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.

Build the tree

Every directory that readers can enter gets an _index.md. A translation sits beside its English source with the .zh.md suffix. Use a Page Bundle when a page owns images or downloads; keep a single Markdown file when it does not.

Keep order explicit

Use weights in multiples of ten. The gaps leave room for a future page without renumbering every sibling.

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.

The Chapter 1 baseline is a visible reference point. The tree in this chapter gives every later change a stable place relative to it.

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

3 Compose a page worth reading

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

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

---
title: Back up a cluster
description: Create and verify one recoverable backup.
weight: 20
---

## Verify the backup {#verify-backup}

The title names the reader’s task. The description explains the result. The weight locates the page, and the explicit heading ID gives another page a durable target.

Measure quality without counting decoration

A useful page balances three independent properties:

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.

Connect the evidence

Use Example 3-1 as the source pattern, and use Equation 3.1 as the review question. Chapter 4 applies both to the site-wide visual system.

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

Design begins after the content tree works. This chapter will connect brand, home-page composition, navigation, typography, page width, and language behavior into one reviewable system.

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.

The completed walkthrough will replace the site title, logo, wordmark, favicon, accent color, and fonts while keeping both color modes legible.

Compose the home page

The home page is data, not a one-off template. Its YAML registry should tell a short story: what the project is, who it serves, what readers can do next, and where they can see the theme in production.

The worked version of this section will build a Hero, a component matrix, a Case gallery, and a final call to action from bilingual data/home files.

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.

Design both languages at once

Translations are peers, not a finishing pass. Preserve route meaning, explicit heading IDs, menu order, images, and functional parameters while translating reader-facing text into natural Chinese.

Until the full exercise lands, use Brand and appearance, Home and landing pages, and Languages as the reference.

5 Publish more than reference pages

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 choose rows, cards, or a table. 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 contract demonstrated by Immersive reading. There is no second Article type and no duplicated publishing pipeline.

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. Keeping an internal explanation page makes the showcase part of the documentation rather than a wall of outbound logos.

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.

The complete walkthrough will add a new article, one Case study, and a short Book chapter from the same source facts, then compare their reader experience.

6 Ship with confidence

Publishing is a sequence of independently verifiable states. A successful local preview proves that the content and theme can render together; it does not prove that a remote module tag exists or that the public site has deployed that revision.

Name every delivery state

Validate the smallest useful surface

Start with the checker that owns the changed contract, then widen the scope. For this site, a strict local build against the sibling theme checkout is an explicit development operation:

HUGO_MODULE_REPLACEMENTS='github.com/pgsty/oink -> /path/to/oink' \
  npm run build -- --panicOnWarning

Before a public release, repeat the build without the replacement and verify the module selected by go.mod. Record which command produced each result so another maintainer can reproduce it.

Review the rendered result

Automated checks catch broken links, duplicate IDs, invalid shortcodes, and accessibility regressions. They do not decide whether a Hero crops well or whether a dense table remains readable on a phone. Review representative English and Chinese routes at desktop and narrow widths, including navigation, theme controls, code blocks, and the whole-book output.

Hand off facts, not implications

A useful handoff lists changed files, commands and results, known limitations, and the next state still waiting to happen. Use Table 6-1 to say exactly which state has been reached instead of compressing validation, release, and deployment into the word “done.”

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

A Front matter patterns

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

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.