内容元素规则：何时使用每种区块

SEO 剧本中的每个页面都依赖于一个区分：一段内容有其目的，而其标题级别和视觉呈现只是展示形式。这些元素编写规则将这一区分转化为生产契约。在应用任何组件、在发布系统之间转换文章或更改已出现在已发布页面上的元素之前，请遵循这些规则。

快速概览

• 按目的优先于名称检查元素库 。如果一个元素的目的与某章节执行的任务匹配，则该元素是强制性的。
• 仅当确认没有类型化元素代表该段文字的目的时候，才使用纯 Markdown。自由文本是备选方案，而非默认选项。
• 先以纯文本形式完成整篇文章。在单独的自上而下的结构化处理过程中应用元素，这样写作和标记不会争夺注意力。
• 将 Markdown 指令视为规范的创作内容。Hugo 和 WordPress 渲染器将相同的字段和正文映射为平台原生输出。
• 保持现有已发布页面的含义与其审核时的版本一致。破坏性定义变更会创建新版本和明确的迁移；它永远不会静默地重新解释旧内容。

管理优先级规则

必须根据一段文字的功能来检查元素库，而不是根据作者碰巧给它起的名称。名称各不相同：一位作者可能将章节标题命名为"什么是流失率？"，另一位可能命名为"流失率详解"，第三位可能命名为"工作定义"。它们的目的相同，因此三者都映射到同一个定义元素。

存在这种优先级是因为自由文本和类型化元素在屏幕上可能看起来完全相同，但在下游行为上却截然不同。一个带样式的标题后跟一个段落，在浏览器中可能看起来像一个定义框，但它不携带任何组件标识。它无法可靠地产生定义的结构化输出、无法将其字段暴露给其他渲染器、无法在迁移过程中保留其语义、也无法被询问页面是否包含定义的质量检查所发现。类型化元素映射到一个组件和已知的数据形状；视觉上相似的自由文本不映射到任何内容。

因此规则是严格的：

在撰写或批准任何标题或内容区块之前，先确定其目的。如果该目的与元素定义匹配，则使用该元素。视觉相似性、已有的 H2 或在段落中表达相同文字的能力，都不能使自由文本成为对等替代品。

优先级是语义性的而非视觉性的。当元素定义允许时，页面仍然可以在元素内部或周围包含普通标题，但标题永远不能取代元素类型。

自由文本与类型化元素

在共享图表可用之前，请使用以下决策路径：

1. 用一个动词陈述该段文字的工作。 例如：定义、警告、总结、比较、证明、指导或邀请行动。这可以防止标题文字掩盖底层目的。
2. 按该目的及其同义词搜索元素库。 只寻找字面标题"什么是 X？“的写作者可能会错过一个页面名称为"定义框"的定义元素。
3. 当存在匹配元素时使用它。 不要比较外观或询问 Markdown 是否可以模仿设计；注册的行为才是决定性因素。
4. 当没有目的匹配时使用自由文本。 这适用于连接性解释、论证、分析、叙述语境和过渡，这些内容属于文章主流程，不需要独特的组件行为。
5. 记录重复出现的空白。 如果相同的不匹配目的出现在多个页面上，建议添加一个库元素，而不是在文章中发明一次性指令或 CSS 处理。

纯 Markdown 在以下情况是正确的：文字构成文章的持续推理，不需要独立的标签、数据契约、交互或复用路径。例如，用两个段落解释为什么某个建议源自前面的证据，这是普通的散文。而页面顶部的一组紧凑结论，仅仅因为它可以用项目符号写成，并不是普通散文；它具有概览或要点元素的公认目的。

导致错误标记的常见混淆

以下情况被明确列出，因为它们容易通过视觉审查。只有当另一个渲染器、验证器、搜索引擎或结构化输出消费者收到该页面时，错误才会显现。

关键要点和快速概览之间的区别尤其重要。当项目是读者应记住的结论时使用要点，这意味着它们通常只能在文章完成后才能写出。当项目在阅读前引导读者了解范围或顺序时使用概览。根据编辑任务进行选择，即使当前主题使两个组件看起来相似。

指令和属性语法

规范的 Markdown 形式使用命名块指令。属性跟随在指令名称之后，放在大括号内：

:::element-name{key=value key2="value with spaces" .class}
Body content
:::

属性用于携带影响元素含义或支持的展示的小型、稳定的属性。保持机器可读性可以防止作者将配置隐藏在散文中。对于没有空格的属性值使用 key=value，当有空格时使用 key2="value with spaces"。未加引号的属性值不能包含空格。 前导点号为支持的类名，例如 .compact；它不是用来发明页面特定样式的地方。

属性键为小写，并使用元素页面上定义的精确拼写。布尔值和枚举值也遵循该页面的约定。不要因为渲染器碰巧容忍就创建属性：未声明的属性没有跨平台保证。

闭合的 ::: 分隔符属于外部元素。将它们保持独立一行，以便解析器可以将正文与下一段落区分开。演示指令的代码示例必须放在围栏代码块内，如本页所示，这样 Hugo 不会将其解释为内容。

默认正文映射

大多数元素需要一个短标题和一个较长的正文。要求作者将这些作为属性重复会使长文本难以编辑且容易转义错误，因此正文提供默认映射：

:::example
## 一个具体的标题

正文的其余部分可以包含段落、列表、链接以及元素定义允许的其他内容。
:::

除非元素页面明确覆盖该规则，否则正文中的第一个标题映射到 title，而该标题之后的内容映射到 content。标题标记为编辑表达了源层级结构；映射的字段让每个平台在上下文中渲染适当的语义标题级别。

只有第一个正文标题受到这种特殊处理。后续标题仍然是 content 的一部分。如果正文没有标题，则 title 不存在；只有当元素定义标记其标题为可选时，这才是有效的。如果元素定义了命名插槽或不同的映射，其自身页面优先于这个默认值，因为渲染器必须确切知道每个片段属于何处。

嵌套项目

某些元素包含可重复的列表，其中每个条目都需要属性和正文，例如带有标识符的步骤、带有标签的卡片或带有初始状态的 checklist 项目。将这些条目扁平化为一个 Markdown 列表会丢失它们的各个字段，因此嵌套项目使用显式的项目指令：

:::parent-element{variant=compact}
::item{key=value}
### 第一个项目标题

第一个项目的解释。
::
::item{key2="value with spaces"}
### 第二个项目标题

第二个项目的解释。
::
:::

约定是 ::item{key=value} … ::：两个冒号打开每个项目，单数名称为 item，两个冒号关闭它。父元素保留其三冒号闭合分隔符。这种视觉差异很重要，因为它使得嵌套无需依赖缩进即可明确，而缩进很容易被复制粘贴破坏。

除非父元素页面另有说明，否则每个项目应用相同的默认正文映射：其第一个标题成为该项目的 title，其余部分成为其 content。当属性仅描述该特定项目时，将其放在项目上；当属性影响整个集合时，将其放在父元素上。

链接、图片和内联按钮

可移植的源需要可预测的路径。相对 URL 应相对于站点根目录，而不是当前 Markdown 文件，因为相同的源可能在 Hugo 中以不同的文件系统深度渲染，或被导入到 WordPress 中。

• 内部页面链接使用前导和尾随斜杠，如元素库 链接所示。不要使用 ../、省略前导斜杠或为内部页面硬编码生产域名。
• 外部链接使用完整的 https:// URL。方案是目的地的一部分，不得由渲染器推断。
• 图片源文件位于 cdn-assets/seo-playbook/ 下，其公开路径以 /cdn-assets/seo-playbook/ 开头。仅在资源存在后才附加已批准的组和文件名。
• 替代文本描述图片传达的信息，而非其文件名或装饰性外观。装饰性图片使用空替代文本，但相关元素页面必须明确允许装饰。
• 内联行动号召使用 :button[Visible label]{href="/target/"}。方括号内的文字是可访问标签，href 遵循相同的内部或外部路径规则。仅当存在真正的下一步操作时才使用按钮，而不是为了使普通引用链接更突出。

图片是内容，而不是不受支持布局的变通方案。如果图片包含必要的标签、数字或说明，应在可访问文本中重复该信息，或使用暴露这些信息的结构化元素。截图捕获请求在命名资源存在前保持为 HTML 注释；它们不是已发布的图片引用，且必须在 frontmatter 中设置 screenshotsPending = true。

Frontmatter 和正文元素有不同职责

Frontmatter 将文档描述为文档。正文指令描述阅读体验中的有意义区块。保持这些层的分离，让列表页面、模式、路由和发布工具无需解析可见散文即可读取元数据。

因此元数据元素位于 frontmatter 中：页面标题、描述、关键词、发布和更新日期、规范或别名信息、所有权、分类、剧本关联以及页面契约放置在那里的任何面向模式的集合，例如学院页面上的 FAQ 条目。这些字段永远不会作为 ::: 指令编写。一个重复某些元数据的可见区块，并不会将有权威的字段移出 frontmatter；只有当它有独立的面向读者的目的时，它才会获得自己的正文元素。

内容元素位于正文中：定义、警告、提示、概览、要点、清单、比较、证据块、示例、步骤和行动号召。它们是指令，因为它们在叙述中的位置很重要。将警告移入 frontmatter 会使其与所限定的段落脱节；将元数据隐藏在正文指令中会使文档级系统无法可靠地找到它。

元数据默认是必需的

元数据在任何人在阅读正文之前驱动路由、预览、发现、关联和结构化输出。因此，省略的字段可能会破坏那些从不渲染文章的消费者。正因如此，除非元素页面明确说明为可选，否则每个元数据元素都是必需的。

必需意味着填充了有效值，而不仅仅是作为空字符串或空集合存在。不要从其他页面的省略推断可选性，也不要添加占位符值来满足验证。如果必需值尚不知道，则页面尚未准备好发布。正文元素遵循相关帖子类型和元素页面的要求规则，而非这个元数据默认值。

先写作，后应用元素

元素选择是一个分类任务，而草稿写作是一个推理任务。尝试逐句同时进行两者会使作者过早地为组件边界进行优化。通常的结果是：过渡较弱、解释浅显以适应框的大小、为实现标记而创建重复的标题，以及选择方便而非目的匹配的指令。

因此，制作分两个不同的阶段进行：

1. 以纯文本形式完成整篇文章。 完成论点、示例、限定条件、过渡和结论。在这个阶段，标题可以描述草稿的逻辑，但它们不决定最终的元素类型。
2. 在单独的自上而下的处理过程中应用元素。 对于每个标题和区块，说明其目的、检查元素库、包裹匹配的章节、添加已声明的属性，并确认正文映射和嵌套。

这种分离改善了两种输出。散文根据读者的问题发展，而不是当前主题的框大小；而标记处理过程可以在整个文档中一致地比较相似的区块。它也使得遗漏可见：作者可以在决定如何编码之前看到文章包含警告或定义。

在结构化处理之后，在不看指令名称的情况下通读页面一次。元素必须支持连贯的文章，而不是将其变成一堆不连贯的小组件。然后在不评判散文的情况下检查源一次，验证分隔符、属性、嵌套项目、路径和必需的元数据。

三符号契约

一个元素通过其目的、规范字段、允许值、正文映射、无障碍行为、结构化输出行为和版本一次性定义。该定义是真理之源。三种平台符号是适配器，而不是三种独立的组件设计。

代表性形式说明了映射；各个元素页面发布其确切支持的名称和字段。作者按照其发布工作流要求的符号工作，但他们不会重命名字段、添加仅平台的含义或手动模仿另一个渲染器的 HTML。

元素所有者维护规范定义，并决定提议的变更是兼容性还是版本化的。Hugo 和 WordPress 维护者拥有自己的适配器，并针对共享的测试固件进行测试：相同的标题、内容、属性、项目、链接和无障碍期望必须通过所有三条路径。编辑所有者验证目的和示例。没有平台维护者可以在本地重新定义编辑含义；如果平台无法表达契约，那是适配器缺陷或提议的契约变更。

此模型允许在平台需要时展示有所不同，同时保持语义稳定。Hugo 可能渲染服务器端 HTML，WordPress 可能存储区块注释，但警告仍然是警告，checklist 项目仍然是项目，相同的必需字段在下游仍然可用。

已发布元素的版本管理

已发布的内容是在发布时存在的元素含义下进行审核的。静默更改该含义可能会改变警告、结构化数据、无障碍性或导入，而无需编辑触碰页面。版本管理保护了该编辑批准。

使用以下变更策略：

• 兼容性渲染器变更： 保留目的、字段、接受值、正文映射和输出含义的视觉改进、性能优化或错误修复可以在当前版本中发布。现有页面通过渲染器接收它。
• 兼容性新增变更： 新的可选属性可以加入当前版本，仅当其缺失时保留现有输出且每个适配器可以安全地忽略或支持它。定义和平台测试一起变更。
• 破坏性变更： 重命名或删除字段、新必需字段、更改正文映射、更改目的、具有语义效果的更改默认值或不兼容的嵌套项目结构将创建新的主要元素版本。
• 弃用： 旧版本对已发布的页面保持可渲染。其元素页面标识替代方案和迁移路径；新页面使用当前版本。
• 迁移： 内容迁移是明确的、有范围的、在 Markdown、Hugo 和 WordPress 之间预览的，并在发布前经过编辑验证。记录哪些页面已更改以及原因。不要让渲染器猜测旧源应如何重新解释。

当源中没有写入版本时，元素使用本契约采用时定义的基线版本。该隐式基线必须保持稳定。新的主要版本使用元素页面上声明的版本机制来标识自身；它们不会重新利用无版本语法。

回滚也很重要。保留以前的渲染器和源表示，直到迁移的页面通过结构、视觉、无障碍和结构化输出检查。如果迁移失败，恢复以前的版本映射，而不是将元素扁平化为自由文本，后者会丢弃版本管理旨在保护的语义。

生产审查清单

在完成散文处理和元素处理之后，使用以下最终审查：

• 每个非散文区块的目的是否可以用一个动词表述？
• 是否按该目的及其近义词搜索了元素库？
• 每个匹配的目的是否使用了其类型化元素，即使 H2 和段落看起来相似？
• 每个剩余的自由文本段落是否属于文章的持续解释、分析、叙述或过渡？
• 属性是否遵循 {key=value key2="value with spaces" .class} 格式，空格已加引号且仅使用已声明的键？
• 第一个正文标题是否映射到 title，其余部分映射到 content，除非元素页面声明了其他映射？
• 可重复的子元素是否使用 ::item{key=value} … ::，父元素和项目属性是否放置在正确的层级？
• 内部链接是否以根目录相对路径形式包含前导和尾随斜杠，外部链接是否绝对路径，图片路径是否在批准的图片根目录内？
• 元数据字段是否在 frontmatter 中（而不是正文指令中），并且所有必需的元数据值是否完整？
• 相同的规范字段能否无损地映射到 Markdown、Hugo 和 WordPress？
• 任何定义变更是否保留了旧页面，或者引入了明确的版本和迁移？

本页是每个单独元素页面的前提条件。每个元素定义必须链接回这些基本规则，然后仅记录其特定于目的的例外：支持的属性、必需字段、正文或项目映射覆盖、允许的嵌套、确切的平台名称和版本历史。如果元素页面未作说明，则应用本页的默认值。