在GitHub Pages的Jekyll中如何在脚注内引入外部内容？

问题原因 #

这个问题的核心是Jekyll和Kramdown的处理顺序冲突：
Jekyll会优先扫描并处理所有{% include %}标签，把include的内容直接插入到文档对应位置；之后Kramdown才会开始解析Markdown语法，包括脚注的[^1]和[^1]: ...结构。

所以当你在脚注定义里写[^1]: {% include citation.html key="ref1" %}时，Jekyll先把citation.html的内容输出到页面正文里，等Kramdown处理脚注的时候，脚注定义的位置已经没有实际内容了，只剩空的脚注标记，最终就出现了引用内容在<li>之外的情况。

可行解决方案 #

方案1：手动生成脚注（推荐，适合多引用场景）

放弃依赖Kramdown的原生脚注，用Jekyll的Liquid语法手动控制引用和脚注的生成，这样能完全掌控HTML结构：

1. 先创建一个_includes/cite.html作为引用标记模板：

{% assign citation = site.data.biblio | where:"key", include.key | first %}
{% comment %} 生成正文里的上标引用链接 {% endcomment %}
<sup><a href="#fn-{{ include.key }}" id="fnref-{{ include.key }}">{{ include.index }}</a></sup>

{% comment %} 收集当前页面用到的引用key，避免重复 {% endcomment %}
{% unless page.citations %}
  {% assign citations = "" | split: "" %}
{% else %}
  {% assign citations = page.citations %}
{% endunless %}
{% unless citations contains include.key %}
  {% assign citations = citations | push: include.key %}
  {% assign page.citations = citations %}
{% endunless %}

2. 在你的page1.md里这样使用：

This is a sentence with a citation{% cite ref1 index=1 %}
Another sentence with another citation{% cite ref2 index=2 %}

## References
<div class="footnotes">
  <ol>
    {% for key in page.citations %}
      {% assign citation = site.data.biblio | where:"key", key | first %}
      <li id="fn-{{ key }}">
        <span class="cit-authors">{{ citation.authors }}</span>, <span class="cit-title">{{ citation.title }}</span>
        <a href="#fnref-{{ key }}" class="reversefootnote">↩</a>
      </li>
    {% endfor %}
  </ol>
</div>

这个方法会先收集页面中所有用到的引用，然后在页面底部统一生成脚注列表，所有内容都会正确落在<li>标签内。

方案2：直接在脚注中使用Liquid变量（适合少量引用场景）

如果你的引用数量不多，可以直接在页面中先通过Liquid获取文献数据，再写入Kramdown脚注定义：

{% comment %} 先获取需要的引用数据 {% endcomment %}
{% assign ref1 = site.data.biblio | where:"key", "ref1" | first %}

This is a sentence with a citation[^1]

[^1]: <span class="cit-authors">{{ ref1.authors }}</span>, <span class="cit-title">{{ ref1.title }}</span>

这种写法绕开了include标签，直接把数据插入到脚注定义里，Kramdown解析时会把内容正确渲染到脚注的<li>中。

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