标题系统：H1、H2 和 H3 规则

标题系统是一个页面标题及其章节标签的有序集合。它将长页面转变为可供人类阅读的路径，以及可供搜索引擎、辅助技术和 AI 问答系统机器可读的大纲。

上方的页面标题就是本页的唯一 H1。下面的每个主要规范都是 H2，主章节内的任何细分都是 H3。这个实时大纲就是呈现的元素：其层级表达的是关系，而非字号。

为什么这个元素很重要

读者很少一口气读完一个长页面。他们会扫描寻找可识别的问题，将章节标签与当前需求进行比较，然后决定在哪里慢下来。描述性的标题减少了这种认知负担，因为每个标题都对后面的内容做出了一个小承诺。“稳定的标题 ID 如何保留引用"一目了然，而"再说几句"则不是。

同样的层级也支持机器可提取性，这意味着自动化系统可以识别一个章节，理解它如何与页面主题相关，并在不将其与相邻章节混淆的情况下检索它。H1 确立页面主题。H2 将该主题划分为主要关注点。H3 将 H2 细化为一种方法、案例、标准或例外。跳级隐藏了这种关系，迫使解析器推断一个子章节是同级的、子级的还是一个不相关的块。

标题还创建了可寻址的章节。片段标识符是 URL 中 # 之后的部分，例如 #qa-checklist。搜索结果、内部链接、浏览器书签和 AI 答案都可以指向那个确切的目标位置。因此，一个随意重命名的自动生成的 ID 可能会破坏 URL，即使页面本身仍然存在。标题不是装饰：其文本定义了章节，其 ID 成为了一个持久的公共地址。

当某个章节的目的与类型化元素匹配时，请遵循元素写作规则 。名为"警告"的 H2 不能替代警告框，名为"对比"的 H2 也不能替代比较表。标题提供文档层级结构；类型化元素提供特定目的的结构。两者可能都需要。

何时使用

在每一个有实质内容的可索引页面上使用标题系统。即使是短页面也需要一个 H1。当读者需要在不同的问题、阶段、标准或证据组之间切换时，添加 H2 章节。只有当 H2 包含至少两个真正独立、值得单独导航的部分时，才添加 H3 子章节。

容易混淆的是那些看起来像标题但不属于文章大纲的视觉标签：

• 卡片标题命名了一个重复的卡片；它不自动成为文档章节。
• 标注标签如"提示"或"重要"标识了框的类型；它不会仅仅因为加粗就变成 H2。
• 图表标题标识了一个图形。除非该图表开始一个完整的章节，否则它属于图形的说明或无障碍名称。
• 导航菜单标签、面包屑、标签页、手风琴控件、页脚标题和模态框标题可能需要组件语义，但它们不进入主文章层级。
• 大型促销标语是展示文案。字号不能将其提升为文档的 H1。

不要仅仅为了介绍一句话、拆分连续的解释或创造视觉留白而添加标题。这些工作应使用段落间距或编辑来完成。一个有用的标题标志着该章节足够有分量，能够回答读者一个明确的需求。

标题的放置位置

位置表达父子关系。将 H1 放在主要内容开头，面包屑或其他网站导航之后、引言之前。将每个 H2 放在主章节之前。仅在其父 H2 及其父级的导向内容之后放置 H3，绝不能放在第一个 H2 之前，也不能仅仅为了视觉效果而将其视为同级元素。

在撰写的文章内容中，两个标题不能相邻。每个标题在遇到下一个同级或更深层级的标题之前，必须拥有有用的内容。这条规则防止了空章节标签，在子章节列表前为读者提供上下文，并创建可提取的段落而非仅仅是一个大纲。

构成

标注的构成包含五个部分：

1. H1： 唯一的页面主题和内容大纲的顶层。
2. H2： 该主题内的一个主要问题、阶段或维度。
3. H3： 如果没有其父级 H2 就无法正确理解的子主题。
4. 所属内容： 从一个标题到下一个同级或更高层级标题之间的答案、证据、说明或解释。
5. 稳定 ID： 附加在标题上并在发布后保留的片段目标位置。

即使排版发生变化，这种关系仍然有效。一个主题在移动端可能使用更小的字号渲染 H2，但它必须在 HTML 中保持为 H2。相反，让一个段落变大加粗并不会赋予它标题语义或片段目标位置。

设计示例

设计变体对应的是语义层级和实际的换行状态，而非任意的颜色选项。

H1 页面标题： 在主要内容开头显示唯一主题。后面可以跟一个辅助描述，但眉标、Logo 或英雄横幅标语不能成为另一个 H1。

H2 主章节： 使该章节在目录中可理解，并在其后跟确定范围的内容。

H3 子章节： 使用较低层级是因为该主题是从属的，而不是因为设计师想要更小的文字。

换行的标题： 允许在窄屏上自然地换行为两行。不要仅仅为了保持在一行内而将一个清晰的标题缩短为含义模糊的标签。

锚点状态： 显示悬停和键盘聚焦状态，而不使锚点成为理解目标位置的唯一方式。直接导航必须偏移任何粘性页眉，以确保标题不被遮挡。

参数

标题系统是一个文档契约，而非装饰性组件。其参数定义了大纲、读者看到的文本、每个节点所属的内容以及该节点可被访问的 URL。

字符和字数限制是编辑建议范围，而非省略必要详细信息的理由。一个 94 字符的标题能够区分两个相似流程，这比一个简短但误导性的标题更好。结构性限制是严格的：一个 H1，无跳级，无重复 ID，无空章节。

语法和代码示例

规范的便携格式将原生大纲包裹在 heading-system 指令中。第一个标题映射到文档标题；后续标题保持为有序内容节点。一旦标题公开，就添加显式 ID。

可移植 Markdown 指令

:::heading-system
# 无停机轮换 API 密钥

在撤销旧密钥之前，替换每个依赖服务中的凭据。

## 准备替换

记录当前读取该凭据的每个服务。

### 识别隐藏的消费者

检查定时任务、部署密钥和本地集成。

## 验证并撤销

测试替换内容，然后撤销已暴露的密钥。
:::

发布时固定稳定 ID，而不是允许未来的文本编辑重新生成它们：

## 准备替换 {#prepare-replacement}
### 识别隐藏的消费者 {#identify-hidden-consumers}

Hugo 短代码

{{< heading-system h1="无停机轮换 API 密钥" >}}
## 准备替换 {#prepare-replacement}

记录当前读取该凭据的每个服务。

### 识别隐藏的消费者 {#identify-hidden-consumers}

检查定时任务、部署密钥和本地集成。
{{< /heading-system >}}

这是 Hugo 适配器契约，并非声称此仓库注册了 heading-system 短代码。Hugo 实现可以继续从 frontmatter 渲染 H1，并通过 Markdown 渲染正文标题（就像本页所做的那样），前提是它验证相同的层级并保留显式 ID。

WordPress 块

<!-- wp:heading {"level":2,"anchor":"prepare-replacement"} -->
<h2 id="prepare-replacement">准备替换</h2>
<!-- /wp:heading -->

<p>记录当前读取该凭据的每个服务。</p>

<!-- wp:heading {"level":3,"anchor":"identify-hidden-consumers"} -->
<h3 id="identify-hidden-consumers">识别隐藏的消费者</h3>
<!-- /wp:heading -->

WordPress 应将 H1 存储在页面标题字段或经批准的英雄块中，而不是作为文章正文中的第二个标题块。显式设置每个已发布标题的 HTML 锚点，以便后续措辞编辑不会静默更改其 URL。

示例

好示例：大纲预测了完整的答案

# 如何选择发票审批工作流

## 定义审批风险
解释哪些发票金额、供应商和例外需要审核。

### 设置金额阈值
为每个阈值指定一个具名的审批人，并记录边界情况如何处理。

### 处理政策例外
将缺少采购订单和已更改的银行信息发送至单独的审核路径。

## 测试工作流
在启动前，用常规和异常发票运行完整的流程。

这个示例有效，因为 H1 陈述了一个任务，每个 H2 命名了一个主要阶段，每个 H3 属于其父级，并且每个标签后都有实现其承诺的内容。读者可以扫描大纲并预测阈值、例外和测试在哪些部分被覆盖。

差示例：样式替代了层级

# 发票审批

### 需要考虑的事项
## 更多信息
### 例外
### 其他

这个示例因四个独立的原因而失败。它从 H1 跳到了 H3，使用了无法预测答案的标签，将标题相邻放置而没有所属内容，并且"例外"在下一个标题之前没有任何解释。由此产生的大纲暗示了页面并未提供的覆盖范围。它还会产生弱的自动生成 ID，如 #other，在页面外引用时会产生歧义。

Schema 标记和无障碍

标题不需要独立的 Schema.org 类型。H1 通常提供或镜像 Article、TechArticle 或其他适当页面实体的 headline，但可见措辞和 JSON-LD 必须描述相同的主题。H2 和 H3 章节保持为 HTML 结构；不要为每个标题编造一个 schema 实体。名为"常见问题"的标题也不会单独创建 FAQPage 标记——可见的问答数据必须满足 FAQ 元素的契约。

无障碍依赖于语义 HTML 和逻辑顺序。屏幕阅读器用户可以通过标题导航、检查标题列表或在章节之间直接跳转。当页面为了样式而跳级、使用加粗段落作为伪标题、或将工具和文章标题混合在一个不连贯的层级中时，这种工作流程就会被破坏。

使用实际的 <h1>、<h2> 和 <h3> 元素。保持标题文本可见；aria-label 不能替代清晰的屏幕文字。锚点控件需要描述性的无障碍名称、可见的键盘焦点，以及当链接整个标题会混淆选择时，一个独立于标题文本的点击目标。当加载片段 URL 时，键盘焦点不需要自动移动，但目标标题必须可见且不被粘性页眉遮挡。

标题 ID 必须在页面内唯一，并应以字母开头。保持小写、连字符分隔、可读，且不含临时日期或位置编号。即使可见标题从"验证结果"改进为"验证新凭据有效”，稳定的 ID 可以保持为 #verify-results。如果章节的含义完全改变，请创建新 ID，并在平台支持时通过别名或记录在案的重定向行为保留旧片段。单独的锚点链接 规范管理锚点导航和交互细节。

写作规则

在润色单个标签之前，先编写页面的大纲。每个标题应以具体的语言回答"我将在这里学到、决定或做什么？“优先选择"比较年度和月度计费成本"而非"定价考虑”，优先选择"为什么导入会拒绝重复 ID"而非"故障排除"。描述性并不意味着冗长；它意味着标签预测该章节的实际内容。

使用 20–80 字符的一个 H1。建议 H2 和 H3 标题为 2–12 个词且不超过 90 个字符。长篇指南通常有 3–12 个 H2 章节。H2 在任何 H3 之前至少需要一个范围句或答案句。当细分有帮助时，在一个父级下使用两个或更多 H3 章节；单个 H3 通常表明其内容应合并到 H2 中。

使用句首大写，除非专有名词或产品名称需要大写。当该章节立即回答确切问题时，问句是合适的。陈述式标签适合阶段、标准、发现和规格说明。保持并列章节在语法上并列：为流程序列使用动词，为比较标准使用名词，为 FAQ 集使用问句。

切勿将以下内容放入标题文本中：

• Markdown 链接或原始 URL；它们会创建竞争性的目标位置和不稳定的无障碍名称。
• 脚注标记或来源引用；将证据放在所属内容中。
• 用作结构标签、状态徽章或装饰前缀的表情符号。
• 手动编号，除非后期类型定义了一个稳定的有序序列。
• CTA 语言如"立即购买"、价格声明、紧迫性词语或促销徽章。
• 样式指令、HTML 换行符或特定于设备的缩写。
• 属于下方段落的第二个句子。

不要编写依赖周围文字才能理解的巧妙标签。“剧情变得复杂了"可能适合一篇文章的语气，但它不会为搜索结果、目录、屏幕阅读器标题列表或 AI 引用提供有用的上下文。在精确的标题之后，在解释中保留个性。

使用该标题的后期类型

Frontmatter 中的 postTypes 数组驱动这些关系。每个列出的后期类型使用相同的层级契约，而其自身的构成决定了确切章节名称和顺序。

QA 检查清单

• 页面渲染恰好一个可见的 H1，并且它命名了页面的实际主题。
• 大纲按照 H1 到 H2 到 H3 顺序，无跳级。
• 每个 H3 有一个清晰的父级 H2。
• 每个标题之后，在下一个标题之前都有有意义的所属内容。
• 每个 H2 在其第一个 H3 之前包含一个导向句或答案句。
• 标题文本在目录或屏幕阅读器标题列表中单独阅读时具有描述性。
• 并列章节使用并列语法和等效层级。
• 标题层级反映关系，而非字号或期望的视觉权重。
• 类型化目的仍然使用其必需的元素；标题不模仿组件。
• 每个发布的标题都有一个唯一、可读、稳定的片段 ID。
• 当可见措辞被编辑而章节含义不变时，现有片段 ID 保持不变。
• 直接片段导航使目标标题在任何粘性页眉下方可见。
• 标题文本不包含链接、引用、表情符号标签、促销徽章或手动换行。
• 在菜单、卡片、手风琴、模态框和其他页面组件存在的情况下，HTML 大纲保持连贯。
• 渲染的页面在窄屏宽度下正常工作，两行标题换行无裁剪或重叠。

当视觉设计看起来精美但大纲失败时，拒绝该页面。标题缺陷会叠加：一个跳级或空章节使得每个下游使用者需要付出更多努力来重建本应由源文档直接陈述的关系。

常见问题

以下问题解决了跨编辑和平台最有可能产生不一致大纲的常见情况。它们的权威值存在于上面结构化的 [[faq]] frontmatter 中，以便可见输出和任何符合条件的 schema 输出可以共享同一个来源。