如何在Jekyll中实现类似Madcap Flare的自动术语表功能？

1. 准备术语表数据源 #

在Jekyll项目的_data目录下创建glossary.yml，按如下格式定义术语和对应定义：

- term: "API"
  definition: "应用程序编程接口，是不同软件组件之间交互的一组定义和协议。"
- term: "静态站点生成器"
  definition: "一种提前生成全部HTML页面的工具，无需服务器实时渲染内容。"

如果需要自定义锚点名称，可给每条术语添加slug字段（比如slug: "api"），否则后续会自动用术语名称的slug化结果作为锚点。

2. 生成独立术语表页面 #

创建glossary.md文件，用于展示完整术语列表并生成锚点：

---
layout: page
title: 术语表
---

{% for entry in site.data.glossary %}
  {% assign term_slug = entry.slug | default: entry.term | slugify %}
  <h3 id="{{ term_slug }}">{{ entry.term }}</h3>
  <p>{{ entry.definition }}</p>
{% endfor %}

构建后，每个术语会生成对应锚点链接，比如/glossary#api。

3. 自动替换文章中的术语为链接 #

静态替换方案（构建时处理，适配GitHub Pages） #

修改文章使用的布局文件（比如_layouts/post.html），用Liquid过滤器在构建时自动替换内容中的术语：

{% assign processed_content = content %}
{% for entry in site.data.glossary %}
  {% assign term_slug = entry.slug | default: entry.term | slugify %}
  {% assign term_link = site.baseurl | append: "/glossary#" | append: term_slug %}
  {% assign term_pattern = '\b' | append: entry.term | append: '\b' %}
  {% assign processed_content = processed_content | replace_regex: term_pattern, '<a href="' | append: term_link | append: '" title="' | append: entry.definition | append: '">' | append: entry.term | append: '</a>' %}
{% endfor %}

{{ processed_content }}

注意：若术语包含特殊字符，需提前用escape处理正则转义。

动态替换方案（前端JS处理，更灵活） #

如果担心静态替换的正则冲突或性能问题，可在页面加载时用JS动态替换：

<script>
// 从Jekyll数据源注入术语数据
const glossaryData = [
  {% for entry in site.data.glossary %}
    {
      term: "{{ entry.term | escape_js }}",
      definition: "{{ entry.definition | escape_js }}",
      slug: "{{ entry.slug | default: entry.term | slugify | escape_js }}"
    }{% unless forloop.last %},{% endunless %}
  {% endfor %}
];

// 替换文章内容中的术语
const contentContainer = document.querySelector('.post-content');
if (contentContainer) {
  glossaryData.forEach(item => {
    // 转义正则特殊字符
    const escapedTerm = item.term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
    const termRegex = new RegExp(`\\b${escapedTerm}\\b`, 'g');
    const termLink = `${window.location.origin}{{ site.baseurl }}/glossary#${item.slug}`;
    contentContainer.innerHTML = contentContainer.innerHTML.replace(termRegex, 
      `<a href="${termLink}" title="${item.definition}">$&</a>`
    );
  });
}
</script>

将这段代码放在文章布局的底部即可。

4. 实现悬浮提示（类似Madcap Flare的弹出定义） #

如果想要鼠标悬停时显示定义、点击跳转到术语表，可结合Bootstrap Tooltip实现：

1. 页面中引入Bootstrap的CSS和JS（若项目未集成）
2. 修改链接的HTML结构，添加tooltip属性：
   • 静态方案中替换为：<a href="{{ term_link }}" data-bs-toggle="tooltip" data-bs-title="{{ entry.definition }}">{{ entry.term }}</a>
   • 动态方案中替换为：<a href="${termLink}" data-bs-toggle="tooltip" data-bs-title="${item.definition}">$&</a>
3. 添加tooltip初始化脚本：

<script>
document.addEventListener('DOMContentLoaded', function() {
  const tooltipTriggers = document.querySelectorAll('[data-bs-toggle="tooltip"]');
  tooltipTriggers.forEach(el => new bootstrap.Tooltip(el));
});
</script>

内容的提问来源于stack exchange，提问作者oceanclub