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 is being developed around one Starter site, from its first local preview toward 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.

How to read this book

Start with Chapter 1: Start with a working site. Chapters 1–3 use the same Starter to preview the site, add bilingual pages, and improve their content. Chapters 4–6 and the appendix are still draft outlines. To finish customization and deployment now, continue with the Starter tutorial and Deploy. The object indexes below also demonstrate Book publishing features; use them when you need to locate a figure, table, or example.

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 — 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 — The same page now states a prerequisite, a command, and a visible result.

1 Start with a working site

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.

Install the prerequisite

The current Starter needs Git, Go 1.27 or newer, and Hugo Extended 0.165.0 or newer. OINK’s lower declared compatibility floor remains 0.160.1, but the Starter and its workflows deliberately pin the current tested toolchain. Node.js is not required.

$ go version
go version go1.27.0 darwin/arm64
$ hugo version
hugo v0.165.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

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

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

---
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.

---
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:

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

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

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.

---
title: Verify a local preview
description: Check that a documentation edit reaches the browser and builds without warnings.
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 --panicOnWarning
```

The command should exit successfully without warnings. Refresh this page at
`http://localhost:1313/docs/preview-check/` and confirm the new note and command
are visible. A successful build and a visible edit are two separate checks.

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:

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 outlines the next visual-design stage; for a complete next task now, continue with Starter customization.

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

From your Starter repository, run the ordinary production build before using the deployment workflow you selected:

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

Check that hugo mod graph resolves the intended release in go.mod, then follow the Starter deployment steps. A normal Starter site needs no npm build script or sibling theme checkout. If you are also changing OINK itself, follow the separate theme-development workflow. Record the build, workflow result, and public URL checks separately.

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.