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
Tables
- Table 2-1 — One explicit order is reused by navigation, paging, and generated contents.
- Table 6-1 — Each delivery state needs its own evidence and handoff.
- Table A-1 — One source tree can expose several purpose-specific Book outputs.
Equations
Examples
- 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.
Install the one required tool, run a local preview, and establish a visible baseline before changing the design.
Turn directories, section indexes, page bundles, and weights into one predictable reading and navigation order.
Combine prose, callouts, code, media, tables, and mathematics without turning the page into a component catalogue.
Turn a sound content structure into a recognizable, responsive, and bilingual publication.
Use Docs, Blog, Case, Book, and release pages as distinct answers to distinct reader needs.
Separate local preview, repository integration, theme release, and hosted deployment, then verify each state with the right evidence.
Copy-and-adapt contracts for Book roots, chapters, immersive Blog posts, and generated Book outputs.