目录：格式与规则

在元素库 中，快速概览和目录告诉读者页面涵盖了什么内容、帮助他们做出什么决定，以及如何跳转到他们需要的章节。

**快速概览。**将此配对的开场元素用于较长或结构复杂的页面。撰写一段40-90字的概览，设定范围和预期结果，然后提供一个由稳定的H2标题和仅有用的H3标题组成的目录列表。在本网站上，下方的实时目录控件在读者滚动超过300像素前保持隐藏状态；之后它会作为固定在桌面端站点标题下方的下拉菜单出现。

为什么这个元素很重要

读者并非每篇长页面都从同一处开始阅读。一个人需要定义，另一个人想要实施步骤，还有第三个人只是在批准工作前检查某个约束条件。一段简短的概览在读者投入注意力之前回答了"我来对地方了吗？“这个问题。目录列表则回答了"我需要的内容在哪里？“而无需线性通读。

这两个部分被一起规定，是因为它们解决的是相邻但不同的定位问题。概览用句子解释了页面的承诺、边界和有用结果。目录列表则将实现该承诺的路径暴露为目标位置。没有概览的目录可以显示页面有名为"配置"和"可访问性"的章节，但无法解释该页面是概念性介绍还是生产规格说明。有概览但没有导航可以确立范围，但仍会让读者在3,000字的内容中搜索。

此元素还提高了机器可提取性，即软件隔离段落并在完整页面之外保留其用途的能力。概览是标题和描述之后的第二个简洁、自包含的摘要。Hugo的源目录是页面覆盖范围及层次结构的一个带链接、机器可读的大纲；当前的固定渲染器将这些链接转换为保留其URL片段值（URL的#section部分）的选项。搜索系统、检索工具、浏览器扩展和AI代理可以在处理每个段落之前，使用文档大纲来识别可能的答案区域。这并不能保证搜索功能或AI引用；但它减少了关于主题从何处开始以及它们如何关联的歧义。

这种配对不能造成重复。概览陈述范围和结果。直接答案块 回答首要问题。关键要点 陈述值得记住的结论。当三者用不同方框说同样的事情时，开篇就变成了障碍而非辅助。

何时使用

目录列表在跳转是读者可能的行为时才有价值。字数是常用的参考指标，但结构才是决定性因素。

当标题可能被宽泛解读、页面有意排除相邻主题、或读者需要在继续之前了解预期结果时，单独使用概览。一个900字的政策页面可能需要两句话的概览，即使它不需要导航。

仅当标题和开篇已经明确无误地确立了范围时，才可单独使用目录列表。这种接近边界的情况在参考页面上很常见：开篇可能包含一个执行定位功能的直接定义，而一长串独立的字段仍然需要导航。

不要将任何一部分作为装饰使用。一篇700字文章上的六个条目TOC在给出答案之前增加了一个额外决定。一个说"本指南探讨了您需要知道的一切"的概览并没有定义范围、结果或排除项。不要使用这一配对来掩盖薄弱的标题结构：如果标题重叠、语法不一致、或将一个想法分割成许多微小章节，请先修复文档，再暴露其大纲。

放置位置

位置是元素含义的一部分。概览必须出现在英雄区或开篇直接答案之后、第一个H2之前。它可以是一个短段落或一个紧凑列表，但必须在读者投入正文之前被看到。TOC调用应紧接在概览之后，以便在源文件中将定位和导航保持在一起，尽管本网站的固定控件在滚动300像素后才变为可见。

这一配对不得打断定义、不得将主张与其证据分离、也不得在文档中途首次出现。不要将其放在标题与该标题的开篇段落之间：标题与解释之间的关系应保持直接。不要将另一个概览型组件紧邻其放置。当需要直接答案或关键要点块时，分配不同的任务并按此顺序排列：直接答案、简短范围概览、TOC调用、第一个正文章节。如果措辞仍有重叠，则省略其中一个摘要。

每页使用一次短代码。其渲染后的ID（tocDropdown、tocSelect、selectTrigger及相关控件）是固定的，因此第二个实例会创建重复的文档ID和不可预测的脚本。

结构解析

该元素有六个有意义的区域。前五个是内容或行为区域；进度指示器是状态区域。图例保留在页面中，以便在截图被调整大小或替换时保持可读性。

1. 概览正文： 40-90字，说明范围、预期结果和任何重要的边界。
2. 固定包装标题： 默认为页面标题，或当更短的标签更清晰时使用编写的title属性。
3. 当前章节标签： 初始为"选择章节…"，当浏览器的IntersectionObserver（一种检测元素进入定义视口区域的API）将章节标记为活动时随之变化。
4. 下拉触发器： 在当前实现中，点击时打开生成的章节目标位置列表。
5. 标题选项： 从Hugo页面目录派生的链接，当前为H2和H3（由markup.toml配置）。
6. 进度条： 显示已遍历的可滚动文档比例；不标识章节完成状态。

设计示例

图库展示的是行为状态而非装饰主题。底层内容保持不变，以便评审者比较时机、层级、裁剪和交互。

没有通过Markdown编写的其他视觉变体。title更改标签，class添加包装类，但两者都不会创建语义上不同的元素。新的颜色、卡片、侧边栏或内联列表处理方式需要组件决策，而非在内容中添加任意类。

参数

概览和TOC共享一个编辑契约，但只有固定TOC由当前短代码渲染。配置值被包含在内是因为它们会改变输出，尽管作者无法在每个调用中设置它们。

这种依赖关系容易被忽视：没有H2标题的页面会静默地不渲染固定TOC，因为Hugo不会生成可用的大纲，且部分仅在存在标题时发出标记。在当前配置下，H2及其H3子级符合条件；H4及更深层标题被排除。部分通常解析Hugo的 .TableOfContents。其HTML回退仅扫描渲染后的H2元素，因此作者不得依赖回退行为来保留H3导航。

语法与代码示例

可移植表示法将概览作为元素正文，导航设置作为属性。标题链接仍从周围文档生成，而非由作者重复。

:::quick-overview-and-toc{title="On this page" class=""}
This guide explains when to use the element, how the sticky Hugo control behaves,
and how to preserve accessible, stable section destinations after publication.
:::

当前的Hugo映射将概览写作普通Markdown，并调用所附带的短代码一次。没有JSON正文。

This guide explains when to use the element, how the sticky Hugo control behaves,
and how to preserve accessible, stable section destinations after publication.

{{< table-of-contents title="On this page" class="" >}}

WordPress块映射存储相同的正文和属性。尚未注册该块的网站可以使用等效的短代码形式；不得手动编写标题链接。

<!-- wp:amicited/quick-overview-and-toc {"title":"On this page","className":""} -->
<p>This guide explains when to use the element, how the sticky control behaves,
and how to preserve accessible, stable section destinations after publication.</p>
<!-- /wp:amicited/quick-overview-and-toc -->

[amicited_quick_overview_toc title="On this page" class=""]
This guide explains the element's scope, behavior, and anchor policy.
[/amicited_quick_overview_toc]

在所有三个系统中，真实的来源是文档的实际标题层级。手动维护的列表会随着标题的变化而产生偏差，并可能指向不再存在的ID。

示例

好示例

快速概览。 本指南向内容团队展示如何规划、撰写、审阅和维护一个对比页面。涵盖证据标准、对比标准、产品声明、无障碍表格和发布后检查。不包括付费投放或联盟佣金条款。

本页内容： 定义决策 · 选择对比标准 · 收集证据 · 起草页面 · 审阅声明 · 衡量与维护

这行之有效，因为概览用48个字指明了受众、结果、覆盖范围和边界。六个目标是读者可能独立回访的不同任务。它们的标签使用并列的动词短语，因此人和机器都能推断出一个流程。没有任何条目重复页面标题或暴露琐碎的子章节。

差示例

概览： 欢迎来到我们的完整指南。在当今不断变化的世界中，有很多东西需要了解，所以请继续阅读以学习一切。

目录： 引言 · 更多信息 · 重要事项 · 其他事项 · 结论

这失败有两个原因。概览用了22个字却没有定义范围、读者、结果或排除项。条目标记的是修辞容器而非主题，因此无法帮助读者预测答案所在位置。添加更多标题也无法解决这个问题；文档首先需要有意义的章节边界。

第二个接近边界的情况是一篇600字的答案，其TOC中包含"概述”、“背景”、“细节”、“技巧"和"结论”。即使每个锚点都工作正常，这个列表增加的界面比导航价值更多。保留直接的开篇并移除TOC。

Schema标记与无障碍

此处，Schema标记 指的是识别实体和属性的标准化机器可读代码。该元素在Schema.org词汇表中没有专门的类型或属性，Hugo短代码也不发出JSON-LD（通常用于发布该词汇表的基于脚本的表示法）。不要仅仅因为TOC是一个列表就将其标记为ItemList；那将暗示一个主题条目列表而非导航。只有当措辞独立适用时，概览才可能为页面的description提供信息，但它不会自动复制到结构化数据中。

HTML和ARIA行为在此更为重要。ARIA（无障碍富互联网应用标准）在原生HTML不足时提供角色、名称和状态。地标是一个命名的页面区域，辅助技术用户可以跳转到该区域。焦点是当前的键盘交互目标。

这些是实现事实，并非忽视无障碍的许可。内容评审者今天就可以验证标题清晰度、唯一ID和逻辑顺序。组件所有者必须在将固定变体描述为键盘可访问之前，解决触发器、地标、焦点、URL和减少动效行为问题。

写作规则

在页面结构稳定后再撰写概览。这可以防止早期的承诺偏离最终的覆盖范围。保持在40到90字之间。优先使用两到三个句子；仅当页面包含多个真正并列的结果时，才使用三到五个要点。说明页面帮助读者理解、决定或做什么。当标题可能合理地承诺超出页面内容时，指明排除内容。

使用H2作为页面的主要问题、阶段或决策领域。只有当H3在实质性H2下作为有用的独立目标时才将其包含在导航中。在本网站上，配置自动包含每个H2和H3，因此实际操作策略更为严格：除非标题值得出现在导航中，否则不要创建它。目标总条目数为5-18个。如果生成的列表超过18个，合并重叠的章节、移除不必要的H3标题或拆分页面。永远不要为了从TOC中隐藏某个标题而直接从H2跳到H4；标题级别表达的是层级关系，而非样式或导航偏好。

使用简洁、描述性的标题文本。读者应该在不阅读其父段的情况下理解每个目标。在序列中优先使用并列形式：“选择标准”、“收集证据"和"审阅声明"比混合名词、问题和模糊标签更易于浏览。不要仅仅为了影响TOC而在标题中放置引用、推广声明、表情符号、状态徽章或完整句子。

概览中绝不能包含第二个微缩目录列表、未经支持的性能声明或正文中未出现的说明。TOC中绝不能包含手动键入的锚点、当前页面之外的目标或指向空章节的链接。

锚点稳定性策略

标题ID是URL的片段部分，例如#anchor-stability-policy。已发布的片段URL是公共接口。书签、推广链接、支持文档、搜索结果和AI生成的答案都可能直接指向它们。更改标题文本可能会改变Hugo生成的ID，并破坏每个入站锚点，即使页面URL保持不变。

发布后，冻结所有H2和H3标题的ID。优先编辑标题下方的段落，而非重命名标题。当必须重命名时，使用发布系统支持的显式锚点机制保留旧ID，然后验证旧的入站片段和新的TOC选择。永远不要将旧ID用于不同的主题，永远不要在页面上复制ID，也永远不要在没有迁移计划的情况下翻译现有本地化URL上的ID。在发布说明或内容变更日志中记录有意的锚点更改，以便已知入站链接的所有者可以更新它们。

使用该元素的文章类型

postTypes前置元数据列出了该元素属于其生产模式的格式。这仍然是条件性的：一个通常为长格式的短文实例可能低于TOC阈值。

产品、分类和用例页面默认不包含，因为它们的主要旅程通常由页面级导航和行动号召处理。仅通过文档化的模板决策添加此元素，而非因为页面恰好很长。

QA检查清单

• 确认页面满足阈值：至少1,800字、七个H2章节，或文档化的非线性导航需求。
• 确认概览为40-90字，并说明了范围、预期结果和任何必要的排除项。
• 确认概览不与直接答案或关键要点重复。
• 确认短代码只出现一次，紧接在概览之后、第一个H2之前。
• 确认每个H2都是有意义的主要目标，每个H3都足够有用以至于可以出现在导航中。
• 确认生成的列表包含5-18个条目，使用逻辑顺序，并且在当前配置下不包含H4项。
• 确认config/_default/markup.toml仍然使用startLevel = 2、endLevel = 3和ordered = false，或随组件变更更新本规范。
• 确认没有合格H2的页面不声称包含TOC；短代码将静默地渲染为空。
• 确认每个生成的片段是唯一的，并且指向预期的标题。
• 在更改任何H2或H3措辞之前，测试已发布的入站锚点URL；当标题必须更改时保留旧ID。
• 在桌面端，确认固定包装器在300像素或以下时隐藏，并在滚动位置超过300像素后出现。
• 确认固定包装器位于实际标头下方、进度条前进，并且活动标签跟随章节变化。
• 确认窄视口不显示当前控件，并将其记录为预期的当前行为而非损坏的截图。
• 记录当前的无障碍限制：无导航地标、无键盘可聚焦的可见触发器、无焦点转移、无片段更新、无减少动效分支。
• 确认在相应资源存在于磁盘之前，不渲染任何截图路径。

常见问题

以下问题涵盖了最常导致此元素被过早添加、嵌套过深或在发布后损坏的编辑决策。