# Write Beautiful Docs

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

---

LLMS index: [llms.txt](/llms.txt)

---

*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 {#contents}

- [1 Start with a working site](/book/01-start/)
  - [Define the outcome](/book/01-start/#outcome)
  - [Install the prerequisite](/book/01-start/#prerequisite)
  - [Run the preview](/book/01-start/#preview)
  - [Record the baseline](/book/01-start/#baseline)
- [2 Structure the content](/book/02-structure/)
  - [Start from the reader’s questions](/book/02-structure/#reader-questions)
  - [Build the tree](/book/02-structure/#content-tree)
  - [Keep order explicit](/book/02-structure/#ordering)
  - [Make stable addresses](/book/02-structure/#stable-addresses)
- [3 Compose the page](/book/03-compose/)
  - [Give every block one job](/book/03-compose/#one-job)
  - [Start from a small page contract](/book/03-compose/#page-contract)
  - [Measure quality without counting decoration](/book/03-compose/#quality)
  - [Connect the evidence](/book/03-compose/#connect-evidence)
- [4 Shape the experience](/book/04-design/)
  - [Establish the visual hierarchy](/book/04-design/#hierarchy)
  - [Compose the home page](/book/04-design/#home)
  - [Keep navigation predictable](/book/04-design/#navigation)
  - [Design both languages at once](/book/04-design/#languages)
- [5 Choose a publishing surface](/book/05-publishing/)
  - [Match the surface to the reader](/book/05-publishing/#surfaces)
  - [Configure a Blog family](/book/05-publishing/#blog-family)
  - [Turn examples into Case studies](/book/05-publishing/#case-studies)
  - [Keep Book and Docs complementary](/book/05-publishing/#book-and-docs)
- [6 Validate and ship](/book/06-ship/)
  - [Name every delivery state](/book/06-ship/#delivery-states)
  - [Validate the smallest useful surface](/book/06-ship/#validate)
  - [Review the rendered result](/book/06-ship/#visual-review)
  - [Hand off facts, not implications](/book/06-ship/#handoff)
- [A Appendix: Patterns](/book/appendix-patterns/)
  - [Book section root](/book/appendix-patterns/#section-root)
  - [Book chapter](/book/appendix-patterns/#chapter-pattern)
  - [Immersive Blog article](/book/appendix-patterns/#article-pattern)
  - [Generated output matrix](/book/appendix-patterns/#output-matrix)

## Figures {#figures}

- [Figure 1-1](/book/01-start/#fig-first-preview) — The first milestone is a site a reader can open\, not a configuration file that merely looks plausible\.

## Tables {#tables}

- [Table 2-1](/book/02-structure/#tbl-reading-order) — One explicit order is reused by navigation\, paging\, and generated contents\.
- [Table 6-1](/book/06-ship/#tbl-delivery-states) — Each delivery state needs its own evidence and handoff\.
- [Table A-1](/book/appendix-patterns/#tbl-output-matrix) — One source tree can expose several purpose\-specific Book outputs\.

## Equations {#equations}

- [Equation 3.1](/book/03-compose/#eq-page-quality) — A page fails when any one of clarity\, accuracy\, or consistency falls to zero\.

## Examples {#examples}

- [Example 3-1](/book/03-compose/#eg-page-contract) — A page contract with one stable title\, one summary\, and an explicit place in the tree\.

## How to read this book {#reading-path}

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.

---

Section pages:

- [Start with a working site](/book/01-start/): Install the one required tool, run a local preview, and establish a visible baseline before changing the design.
- [Give the content a structure](/book/02-structure/): Turn directories, section indexes, page bundles, and weights into one predictable reading and navigation order.
- [Compose a page worth reading](/book/03-compose/): Combine prose, callouts, code, media, tables, and mathematics without turning the page into a component catalogue.
- [Shape the reading experience](/book/04-design/): Turn a sound content structure into a recognizable, responsive, and bilingual publication.
- [Publish more than reference pages](/book/05-publishing/): Use Docs, Blog, Case, Book, and release pages as distinct answers to distinct reader needs.
- [Ship with confidence](/book/06-ship/): Separate local preview, repository integration, theme release, and hosted deployment, then verify each state with the right evidence.
- [Front matter patterns](/book/appendix-patterns/): Copy-and-adapt contracts for Book roots, chapters, immersive Blog posts, and generated Book outputs.