# Compose a page worth reading

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

---

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

---

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 {#one-job}

> [!TIP] 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 {#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.

````markdown {title="content/docs/preview-check.md" num="3-1" caption="The same page now states a prerequisite, a command, and a visible result." #eg-page-contract}
---
title: Verify a local preview
description: Check that a documentation edit reaches the browser and builds with reviewed diagnostics.
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
```

The command should exit cleanly. Refresh this page at
`http://localhost:1313/docs/preview-check/` and confirm that the new note and command
are visible in the browser.
````

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 {#quality}

A useful page balances three independent properties:

$$
Q = C_{clarity} \times A_{accuracy} \times K_{consistency}
$$
{#eq-page-quality num="3.1" caption="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.

## Cross-reference the example and check {#connect-evidence}

Use [Example 3-1](#eg-page-contract) as the source pattern,
and use [Equation 3.1](#eq-page-quality) as the review question.
Continue to [Chapter 4: Shape the reading experience](/book/04-design/) to
customize the site's identity, visual preset, and home page.

The component reference begins at [Components](/docs/components/). Read the
individual page for a component only when the tutorial introduces a need for
it.
