我如何在 Kgateway Docs 中添加 Glossary Tooltip Hover（使用 Hugo Shortcodes）
Source: Dev.to
引言
当我加入 Kgateway 文档团队，担任技术写手和贡献者 时，在审阅和用户反馈中出现了一个反复出现的模式：
读者经常在核心术语上卡住。
Kgateway 涉及多个领域——Kubernetes、Envoy、Service Mesh、AI/Agentic 模式以及 Kgateway‑特有的架构——因此像 Clusters (Envoy)、Backends、A2A、Ambient Mesh 或 Data Plane 这样的概念随处可见。新读者常常需要离开页面去了解这些术语，打断了学习流程。
为了解决这个问题，我使用 Hugo 短代码实现了一个可复用的术语表工具提示悬停系统。结果是文档更清晰，切换上下文的次数更少，整体感受也更精致。
为什么术语表工具提示很重要（尤其在技术文档中）
工具提示看似是一个微小的 UI 细节，但它们能显著提升 阅读体验。
- 加快学习，减少上下文切换 – 读者不必打开多个标签页来理解一句话；一次悬停即可获得即时定义。
- 帮助统一混合术语 – Kgateway 混用了 Kubernetes CRD、Envoy 概念、Agentic AI 术语、网格网络术语以及自己的关键字。中心化的术语表可以保持一致性。
- 页面更简洁、可读性更高 – 与其重复出现定义，不如用工具提示让正文保持整洁。
- 唯一真相来源（通过 YAML） – 在数据存储中更新一次定义，即可在所有位置同步生效。
但有个陷阱：不要滥用工具提示
我们制定了一个简单的规则：
不要在每一次出现的术语上都使用工具提示。
过多的悬停效果会分散读者注意力，尤其在内容密集的技术页面上。我们采用了 策略性放置模型。
工具提示的放置位置（以及不该放置的地方）
在以下位置使用工具提示
| 位置 | 原因 |
|---|---|
| 首次引入术语的地方 | 帮助读者建立初始理解 |
| 概览或概念页面 | 这些页面通常会引入大量新概念 |
| 大量讨论某一概念的页面 | 只放置一两次工具提示 |
| 术语表页面 | 可选，但很有帮助 |
避免在以下位置使用工具提示
- 每一次重复出现
- 文本较长的表格
- 代码块
- 标题（会破坏格式）
这样可以保持 UI 的简洁和专业。
我是如何实现术语表工具提示的（Hugo 短代码 + YAML + CSS）
1. YAML 术语表数据存储
文件： /data/glossary.yaml
A2A:
short: "Agent-to-Agent Protocol — secure, policy-driven communication between sidecarless agents."
Agentgateway:
short: "An open-source data plane optimized for agentic AI connectivity."
Cluster (Envoy):
short: "Envoy 'cluster' — a logical grouping of upstream endpoints used for load balancing."
Backends:
short: "Destination services or endpoints Kgateway routes traffic to (Kubernetes services, Lambdas, external hosts)."这相当于一个包含 30 多个关键概念的中心小型数据库。
2. Hugo 工具提示短代码
文件： layouts/shortcodes/gloss.html
{{ $key := .Get 0 }}
{{ $entry := index site.Data.glossary $key }}
{{ if $entry }}
{{ .Inner | default $key }}
**{{ $key }}**
{{ $entry.short }}
{{ if $entry.link }}
Learn more
{{ end }}
{{ else }}
{{ .Inner | default $key }}
{{ end }}在 Markdown 中的使用方式
The translation cycle starts by defining {{}}Envoy clusters{{}}...
图 1：在概念架构页面上对 “Control Plane” 的工具提示悬停定义。
3. 工具提示样式（CSS）
文件： static/css/glossary.css
.glossary-term {
position: relative;
cursor: help;
border-bottom: 1px dotted #666;
}
.glossary-term > span {
visibility: hidden;
opacity: 0;
width: 280px;
padding: 12px;
background: #fff;
border-radius: 6px;
position: absolute;
bottom: 125%;
left: 50%;
transform: translateX(-50%);
box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
transition: opacity .3s;
}
.glossary-term:hover > span,
.glossary-term:focus > span {
visibility: visible;
opacity: 1;
}该工具提示具备可访问性、响应式且不突兀。
4. 术语表页面
我们还创建了一个 glossary.md 页面，用于：
- 提升 SEO
- 将所有术语集中在一起
- 提供完整的参考索引
结语
术语表悬停工具提示虽小，却能让你的文档：
- 更易阅读
- 对初学者更友好
- 更加统一
- 更具现代感
在我为 Kgateway 文档贡献的过程中，这一功能显著提升了用户体验。无论你使用 Hugo 还是其他静态站点生成器，我都强烈建议加入可复用的工具提示系统。
感谢阅读！如果你想要可复用的模板或模块版本，随时提问。以下是此任务的合并 Pull Request： Tooltip Hover feature