# 组合出值得阅读的页面

> 把散文、提示块、代码、媒体、表格与数学公式组合在一起，而不把页面变成组件目录。

---

LLMS 索引： [llms.txt](/zh/llms.txt)

---

组件应该帮助论证，而不是与内容争夺注意力。先写普通散文，只有当读者需要比较、验证、复制
或停下来思考时，才引入额外结构。

## 让每个内容块只做一件事 {#one-job}

> [!TIP] 先写出那句话
>
> 如果你无法用一句话解释某个组件为什么应该出现在这里，
> 那就先保留普通正文，直到需求变得明确。

用提示块表达前置条件或风险，用表格对齐重复字段，用代码块放置读者可以执行的材料，
只在形状或空间关系承载了散文无法表达的信息时才使用图片。

## 从一份小型页面契约开始 {#page-contract}

```yaml {num="3-1" caption="一份只包含稳定标题、摘要和树中位置的页面契约。" #eg-page-contract}
---
title: 备份集群
description: 创建并验证一份可恢复的备份。
weight: 20
---

## 验证备份 {#verify-backup}
```

标题命名读者的任务，描述说明预期结果，权重确定页面的位置，
而显式标题 ID 则为其它页面提供稳定的引用目标。

## 不用装饰数量衡量质量 {#quality}

有用的页面需要同时平衡三项独立属性：

$$
Q = C_{clarity} \times A_{accuracy} \times K_{consistency}
$$
{#eq-page-quality num="3.1" caption="清晰度、准确性或一致性中任何一项降为零，整个页面就会失败。"}

这里刻意使用乘法：视觉精美无法弥补错误命令，准确的正文在读者找不到或无法按步骤执行时，
同样会失败。

## 连接证据 {#connect-evidence}

用 [示例 3-1](#eg-page-contract) 作为源码模式，
再用 [公式 3.1](#eq-page-quality) 作为评审问题。第 4 章会把两者用到站点级视觉系统上。

组件参考的起点是[组件](/zh/docs/components/)。只有当教程引入了某项真实需求时，
才需要阅读对应组件的独立页面。