3 Compose a page worth reading

Combine prose, callouts, code, media, tables, and mathematics without turning the page into a component catalogue.

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

Write the sentence first

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.

Example 3-1 The same page now states a prerequisite, a command, and a visible result.

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

Q = C_{clarity} \times A_{accuracy} \times K_{consistency}

Equation 3.1 A page fails when any one of clarity, accuracy, or consistency falls to zero.

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.