Write Beautiful Docs
Write Beautiful Docs
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
Tables
- Table 2-1 — One explicit order is reused by navigation, paging, and generated contents.
- Table 6-1 — Four verification stages from local preview to live deployment, and what each stage leaves to the next step.
- Table A-1 — One source tree can expose several purpose-specific Book outputs.
Equations
Examples
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
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.
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:
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
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
- docs/
Create these two files with the complete contents below. The section roots already exist; do not replace them.
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 |
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
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.
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.
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
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:
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:
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.mainon 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:
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
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:
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:
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
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 |
Validate the smallest useful surface
From your Starter repository, run a clean production build before pushing to your deployment workflow:
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
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
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
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
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 |
| The complete Book | Review, printing, and PDF conversion | |
| markdown | The source-shaped Book | Export and downstream processing |
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.