文章术语自动加百科链接，一分钟搞定

背景

技术博客的作者常常面临一个两难困境：写得浅显，资深读者觉得冗余；写得深入，新手读者却因陌生术语频频卡顿。一位读者在读完作者一篇涉及自建服务器和 NAS 的文章后反馈，文中诸如 RSS、WebDAV、DDNS、内网穿透等缩写和名词反复出现，读到后面需要向上翻页回忆，而用手机划词搜索又严重打断阅读节奏。作者意识到，虽然现有工具（如 Safari 划词、Chrome 搜索、AI 浏览器翻译）都能帮助读者理解术语，但它们都需要读者主动发起动作，哪怕只花两秒，累积起来也会彻底破坏阅读的沉浸感。理想的解法是：读者遇到关键概念时，只需点击一下就能跳转到解释该概念的页面。但手动为每篇文章的每个术语添加链接——尤其是确保只在首次出现时加链接、维护链接有效性——工作量巨大且极易出错。于是作者决定构建一个自动化方案，在博客发布时自动将术语嵌入百科链接。

核心内容

作者基于自己的博客框架 Astro（一个静态站点生成器）设计了一套在构建时自动嵌入术语链接的机制。核心思路是：在文章从 Markdown 文件编译为静态 HTML 的过程中，利用两个插件接力完成术语匹配和链接插入，最终读者拿到的是已经处理好的、可直接阅读的静态页面，无需在浏览器端额外加载术语表或执行匹配逻辑。

整套方案由两个插件组成，运行在 Astro Markdown 处理管线的不同阶段：

1. remark-glossary：这是一个 remark 插件（处理 Markdown AST 的阶段），任务很简单：读取文章 frontmatter 中的 lang 字段，将其存入 vfile.data.glossaryLang，供后续插件使用。文章未声明语言时默认中文（zh）。这个字段被第二个插件用来决定链接指向的维基百科子域名（中文文章用 zh.wikipedia.org，英文用 en.wikipedia.org，繁体中文也用 zh.wikipedia.org）。

2. rehype-glossary：这是核心引擎，运行在 rehype 阶段（此时 Markdown 已被转为 HTML AST）。它执行以下步骤：

   • 从 vfile.data.glossaryLang 获取文章语言。
   • 检查文章 tags 是否包含「周刊」或「Weekly」，若是则跳过整篇文章（因为周刊内容时效性强且常以术语开玩笑，不适合加链接）。
   • 使用 unist-util-visit 遍历 HTML AST 的所有文本节点。
   • 用 findTermMatches 函数扫描文本，找出所有命中术语表的位置。
   • 将原始文本节点拆分为「文本片段 + <a> 链接片段」的混合序列，替换到原位置。例如：“我每天都在使用 RSS 和 Git” 被拆分为：“我每天都在使用 <a href="...">RSS</a> 和 <a href="...">Git</a>”。

匹配规则包含多个精细设计：

• 长词优先：术语按长度降序排列，长的先匹配，避免短词（如“Script”）截胡长词（如“AppleScript”）。
• 每篇文章只链接一次：同一个术语 ID 在全文中只在第一次出现时加链接，后续出现保持朴素文本，通过全局 Set<string> 跟踪已用 ID。
• 跳过特定节点：不处理 <code>、<pre>、<a>、<h1> 到 <h6>、<script>、<style>、<input>、<button>、<select>、<textarea> 中的文本。
• ASCII 术语的边界检查：对于纯英文术语（如 RSS、Git），确保匹配的是独立单词而非嵌套在其他词中（如“RSSFeed”）。做法是检查匹配位置前后字符是否属于 [\w]。
• 重叠匹配处理：若有多个术语位置重叠（如“GitHub”和“Git”出现在“GitHub”中），按起始位置排序，然后从前往后取不重叠的匹配（起始位置 >= 上一个匹配的结束位置）。

链接指向的 URL 采用优先级递减的决策树：

1. 该语言下自定义 URL（如指向官方中文文档）。
2. 顶层自定义 URL（如产品官网）。
3. 自动拼接维基百科 URL（按语言选择子域名 + 词条路径）。目前约 15% 的术语配置了自定义 URL，用于处理没有维基百科页面或页面过于简略的情况。

此外，作者还开发了两个辅助工具：

• 审计脚本（audit-glossary.ts）：扫描所有文章，用正则找出高频出现的英文大写词组、缩写、混合大小写的产品名等候选词，对照现有术语表输出“未注册高频术语”报告，帮助手动补充遗漏。
• 术语总览页（/glossary/）：按字母分组展示所有已收录术语及其简短描述，支持多语言版本，方便读者浏览。

目前术语表收录了 60 多条术语，覆盖技术基础（RSS、XML、Git、Docker、DNS、SSH）、AI/大模型（AI、Gemini、ChatGPT、Claude、Ollama、Cursor）、自托管工具（WordPress、Telegram、Obsidian、Syncthing）、知识管理（Notion、Obsidian、Evernote）、艺术设计（印象派、C4D）等五个类别。

关键要点

• 构建时处理：将术语链接嵌入放在构建阶段（编译为 HTML 时），而非运行时，避免每次页面加载时下载术语表并在用户设备上执行匹配，减少对网络带宽和性能的消耗，且匹配逻辑更新后能立即生效。
• 双插件接力：remark-glossary 负责提取语言信息，rehype-glossary 负责核心匹配和替换，职责清晰，与 Astro 的 Markdown 管线无缝集成。
• 精细匹配规则：长词优先、每篇文章只链接一次、跳过非内容节点、ASCII 边界检查、重叠匹配处理，确保视觉不杂乱且不破坏代码或已有链接。
• URL 决策树：优先使用自定义 URL（如官网或官方文档），其次使用维基百科，兼顾覆盖面和灵活性；约 15% 的术语配置了自定义 URL。
• 辅助工具体系：审计脚本帮助发现未收录的高频术语，术语总览页方便读者查阅，降低维护成本。
• 当前局限：术语表需手动维护；多义词（如“Node”）无法自动区分上下文；不支持同义词推断（如“GitHub”和“GH”需独立添加）。

意义与影响

该方案从根本上解决了技术博客中术语解释与阅读流畅性之间的矛盾。它不再依赖读者主动搜索，而是将知识链接前置到内容生产