术语词汇表链接与工具提示：编写规则

术语词汇表链接将一个术语在其首次有意义出现之处连接到拥有其完整定义的那个页面。该链接帮助读者在不中断文章的情况下理解不熟悉的语言，并为爬虫提供术语与其规范实体页面之间的一致性关系。

canonical URL 是当多个URL包含相同或基本相似内容时的首选版本。

这个句子就是实时元素。锚文本是准确的术语，目标是其规范词汇表条目，周围的句子即使不打开链接也仍然可理解。在支持此功能的系统上，相同的链接可以在悬停或键盘聚焦时显示一个简短的定义工具提示。链接指向的页面——而非工具提示——仍然是真实信息来源。

为什么这个元素很重要

读者并非带着相同的词汇量而来的。专家可能立即认出"canonical URL"，而买家或新团队成员可能需要定义。在每个括号里解释术语会减慢面向专家的正文；一个都不解释则排除了新手。术语词汇表链接创建了一个安静的逃生通道：如果术语熟悉则继续阅读，如果不熟悉则打开其定义。

首次提及规则之所以重要，是因为不确定性会累积。如果读者在第二段误解了一个术语，那么之后建立在该术语基础上的每一个说法都更难评估。在首次有意义的出现处链接该术语可以在不确定性扩散之前解决它。该规则并不意味着"链接第一个字符串匹配"。出现在标题、导航标签、代码示例或摘要中的术语可能尚未承载解释中所使用的含义。

机器可提取性是指软件在去除呈现形式后仍然能够保留关系的能力。描述性锚文本和稳定的目标创建了一个明确的边：这个页面使用了该概念，而那个词汇表页面定义了它。一致的边强化了哪个URL拥有定义。它们不会创建正式的知识图谱或保证可见性，但它们减少了爬虫本会仅通过邻近性来判断的歧义。

过度链接会逆转这些好处。当每个重复的术语都被链接时，页面就不再有优先级信号。读者面对一片相互竞争的出口，辅助技术用户反复听到相同的目标，而机器接收到的是一大堆冗余的边，而非一小组精心设计的关系。因此，在首次有意义提及处的一个规范链接是默认做法，而不是在每个章节都要重复的最低标准。

何时使用它

当所有三个条件都满足时使用该元素：

1. 该术语有一个规范的词汇表页面，而非几个近似重复的定义。
2. 理解该术语在实质上帮助读者理解当前页面。
3. 首次有意义的使用可以承载描述性锚文本而不扭曲句子。

强候选对象包括专业术语、首次展开使用的缩略语、命名标准、指标，以及领域含义与日常使用不同的词语。工具提示可以预览一个简短定义；完整的词汇表页面处理边界、示例、来源和相关术语。

近似错误的情况是该元素最常被误用的地方：

• 普通词汇： 不要仅仅因为存在词汇表条目就链接一个熟悉的词语。
• 附带提及： 如果文章提到了一个概念但并不依赖它，链接会创建一个不必要的出口。
• 重复提及： 在第一次链接使用之后，除非一个长的、多部分的页面创建了真正独立的阅读上下文，否则让术语保持为纯文本。
• 模糊的锚文本： “这个方法”、“了解更多"和"该指标"不能标识词汇表实体。链接术语本身。
• 没有规范目标： 不要用搜索结果、标签归档或松散相关的文章来替代。在规范定义存在之前使用纯散文。
• 已经提供了完整定义： 如果词汇表没有增加有用的深度，第二个定义绕道可能是不必要的。
• 商业路由： 词汇表链接不是伪装的行动号召产品。产品页面、注册流程和定价页面服务于不同的读者意图。

在即兴创作之前，先应用共享的元素编写规则 。它们的优先级规则要求作者根据目的选择元素。如果目的是将一个命名术语连接到其规范定义，则使用这种类型化的关系，而不是一个样式相似的通用内联链接。

放置位置

将链接放在首次有意义的正文提及处：第一个使用该术语（以目标页面意义上的）的句子。如果术语首次出现在标题或H2中，则在接下来的段落中链接其首次使用。标题应保持为稳定的章节标签，而不是大型导航目标。

对于缩略语，写出完整术语后跟缩写，并链接完整术语：retrieval-augmented generation（RAG）。后续出现可使用RAG而不加链接。

不要在以下位置放置术语词汇表链接：

• 在另一个链接、按钮或可点击卡片内部；
• 在相同锚文本上的第二个链接旁边；
• 在代码、URL、电子邮件地址或用户输入的原文中；
• 仅在标题中仅为了满足首次提及规则；
• 在表格的每一行中，如果引言中的一个链接定义就能确立该术语；
• 紧邻引用标记旁，如果两个目标在视觉或操作上变得无法区分；
• 在独立于实际链接的工具提示触发器内部。

如果一个句子包含多个不熟悉的术语，只链接理解该句子所需的术语。一个句子中出现三个或更多词汇表链接是一个警告，表明散文假定了过多的词汇。重写该句子，在适当位置定义一个概念，或拆分解释，然后再添加更多出口。

结构

标注的标本有六个区域：

1. 术语锚文本： 可见的术语或完整的展开名称，不带"了解更多”。
2. 规范目标： 一个稳定的词汇表URL，拥有该定义。
3. 上下文句子： 即使不打开链接，也足以理解该术语为何出现的散文。
4. 链接样式： 网站的标准内联链接处理方式；颜色不是唯一的提示。
5. 焦点指示器： 可见的键盘状态，不会被段落或工具提示剪切。
6. 可选工具提示： 一个绑定在链接本身的简短预览，绝不是单独的仅图标控件。

呈现方式可以变化，而不改变锚文本、目标或首次提及行为。

设计示例

每个变体都保持相同的语义链接。

默认内联链接： 必需的基线。在JavaScript禁用、阅读器模式、打印注释和不支持悬停的设备上都能正常工作。

聚焦或悬停时显示定义工具提示： 针对密集型教育内容的增强。预览为一到两个句子，绝不包含链接、按钮、引用或格式控件。

移动端和触屏： 第一次点击跟随链接，除非产品有已建立且无障碍的展开模式。不要让用户发现一次点击打开预览、两次点击才导航，除非这种交互在整个网站上保持一致并已清晰说明。

深色背景： 链接、焦点环、工具提示文本和工具提示边界保持清晰对比度。不要仅仅因为强调色很亮就去掉下划线。

参数

规范URL和可见锚文本是内容决策。工具提示行为属于渲染器。分离这些来源可以防止一个可选的界面特性改变链接的含义。

切勿从term推断href：同形异义词可能拼写相同但需要不同的目标。仅当词汇表记录的简短定义经过审核可在页面外使用时，才从词汇表记录中提取工具提示。

语法与代码示例

所有三种格式都保留一个普通链接作为核心。命名字段是一个可移植的契约；平台可以通过原生块、插件或预处理步骤来渲染它们。

可移植的Markdown指令

The :::glossary-link{href="/glossary/canonical-url/" definition="A canonical URL is the preferred version of a page when duplicate or similar URLs exist." tooltip="true"}canonical URL::: consolidates signals on the preferred page.

如果发布流水线不支持内联指令，使用普通的Markdown并省略工具提示：

The [canonical URL](/glossary/canonical-url/) consolidates signals on the preferred page.

Hugo短代码

The {{< glossary-term-link href="/glossary/canonical-url/" definition="A canonical URL is the preferred version of a page when duplicate or similar URLs exist." tooltip="true" >}}canonical URL{{< /glossary-term-link >}} consolidates signals on the preferred page.

此表示法指定了必需的映射；它不要求作者向已经通过Markdown渲染或内容预处理处理词汇表链接的项目引入新的短代码。渲染的回退必须始终是一个普通的<a href>元素。

WordPress

<!-- wp:amicited/glossary-link {"href":"/glossary/canonical-url/","definition":"A canonical URL is the preferred version of a page when duplicate or similar URLs exist.","tooltip":true} -->
<a href="/glossary/canonical-url/">canonical URL</a>
<!-- /wp:amicited/glossary-link -->

导出的内容必须保留锚文本和href，即使工具提示元数据不可用。

示例

正确示例

Select one canonical URL for substantially similar pages so indexing signals point to the preferred version.

在渲染后的文章中，“canonical URL"在此首次有意义使用处链接到/glossary/canonical-url/。锚文本准确地命名了实体，句子提供了足够的本地上下文以便继续阅读，后续出现保持为纯文本。读者可以选择是否需要完整定义。

错误示例

Select one preferred page for similar pages. Your canonical URL should then reference the canonical URL in every section.

这犯了两个错误。“Preferred page"是相关措辞，但不是目标定义的确切术语，因此关系不够明确。在每个章节重复规范URL链接增加了出口却没有增加含义。正确的修复是首次有意义使用时链接一次"canonical URL”，后续使用保持不链接。

另一个不好的模式是在未链接术语后放置一个信息图标。该图标将目标隐藏于扫描链接文本的读者，创建了一个小触摸目标，并可能使工具提示与可导航的词汇表关系分离。

Schema标记与无障碍

术语词汇表链接不需要单独的Schema.org类型。它仍然是包含在Article、TechArticle或WebPage中的链接。不要为每个内联链接制造DefinedTerm、mentions或about标记；仅通过由可见内容证明的一致页面级数据模型添加此类关系。

无障碍始于一个真正的锚点。它必须在上下文中可理解，不单独依赖颜色可区分，可通过键盘到达，并且具有可见焦点。重要信息不能只存在于工具提示中。

如果实现了工具提示，在其可见期间使用aria-describedby将其与锚点关联。在键盘聚焦和指针悬停时都打开它，在指针移过工具提示时保持打开状态，并允许按Escape关闭而不移动焦点。不要在工具提示内放置可聚焦的控件。不要依赖HTML title属性作为定义接口：其时机、呈现方式、触摸支持和辅助技术暴露方式都不一致。title可以作为补充，但不能作为无障碍名称、描述或规范定义。

当脚本失败时，链接必须能够导航。在触摸设备上，倾向于直接导航而非模拟悬停。如果增强功能无法满足这些要求，则使用普通链接。

编写规则

链接确切的术语或其无歧义的完整形式。保持锚文本在一到八个词以内，不超过80个字符。仅在冠词是专有名称的一部分时才包含如"a"或"the"等冠词。不要加粗每个词汇表锚点；标准链接样式已经传达了交互性，叠加的强调会使技术散文变得杂乱。

默认情况下，每个术语每页使用一个词汇表链接。只有在独立消费的内容——例如长的附录、独立的常见问题解答或嵌入的模块——会失去关系时，才允许使用第二个链接。不要设置固定的最少词汇表链接数量。一个包含两个必要术语的清晰页面优于一个包含十个装饰性出口的页面。

工具提示定义应为40–180个字符，不超过两个句子。陈述该术语是什么，而不是为什么读者应该点击。使用中性、陈述性的语言。预览必须与目标的当前定义一致，并应尽可能从词汇表记录中获取，以便更新不会产生分歧。

切勿将以下内容放入链接或工具提示中：

• 另一个链接、按钮、表单控件或交互式图标；
• 销售主张或行动号召；
• 引用列表或来源说明；
• 图片、视频、表格、代码块或多步骤流程；
• 与规范页面冲突或超出规范页面的定义；
• 完成读者任务所必需的说明。

手动审核同形异义词。“Java”、“conversion"或"agent"可能命名不同的实体。句子和目标必须解决相同的含义。切勿为了链接分发而轮换目标；规范性是关键。

使用该元素的文章类型

postTypes[] Frontmatter标明了该元素被记录为内容系统一部分的格式。表格说明了每种格式如何应用相同的首次提及契约。

QA检查清单

• 规范目标： 路径是拥有该定义的那个词汇表页面；不是搜索、标签、产品或相关文章URL。
• 目标存在： 内容文件现在存在，或路径出现在同一发布版本的已批准规范注册表中。
• 含义匹配： 锚文本和目标引用的是术语的同一含义，包括模糊的缩略语和同形异义词。
• 首次有意义提及： 链接出现在后续使用之前的正文中，而不是仅仅因为某个出现最先出现就在标题或代码示例中。
• 确切锚文本： 链接的词语命名了术语或其完整的无歧义形式；没有"点击此处"或模糊的替代品。
• 局部句子可理解： 读者不需要打开目标或触发工具提示就能理解该句子。
• 每术语默认一个： 重复出现保持不链接，除非有文档记录的独立阅读上下文证明另一个链接是合理的。
• 无链接簇： 句子和段落保持可读性；过多不熟悉的术语应该重写而不是用链接覆盖。
• 工具提示一致性： 任何预览与规范定义一致，并保持在40–180个字符内。
• 渐进增强： 当脚本、悬停或工具提示样式不可用时，锚点仍然有效。
• 键盘行为： 焦点可见；工具提示在聚焦时出现，可按Escape关闭，且不包含可聚焦控件。
• 触摸行为： 链接具有正常的目标尺寸，不需要悬停或无法解释的双击交互。
• 结构化数据约束： 不发出不受支持的schema关系或虚构的元素类型。
• 可移植输出： Markdown、Hugo和WordPress保留相同的术语和规范href，即使工具提示元数据被丢弃。
• 截图状态： 捕获注释保持为非渲染指令，直到命名的资源存在；不引用不存在的图片。

常见问题解答

学院模板会渲染经过审核的Frontmatter问题，涵盖资格、首次提及、工具提示范围、规范一致性和链接限制。