Jekyll中目标文件不存在时动态修改链接目标的实现方案

需求背景 #

在Jekyll构建多语言站点时，需要实现：插入链接时自动检查对应语言的目标文件是否存在，动态调整链接指向；已通过生成器插件创建包含文章标题、路径等属性的索引site.docs_by_path，计划通过传入路径参数的include标签（{% include link.html path='getting-started/test.md' %}）来修正页面中的无效链接。

现有方案合理性分析 #

你给出的include代码逻辑整体是合理的：

• 针对英文页面，直接匹配英文路径的文件
• 针对非英文页面，优先匹配当前语言的文件，不存在则 fallback 到英文版本
• 加入了错误提示逻辑，当目标文件完全不存在时，会显示错误链接和路径信息，便于排查问题

但代码存在冗余：比如两次拼接英文路径的逻辑重复，可以合并简化。

性能弊端（针对数千个链接场景） #

现有方案的核心问题是Liquid模板逻辑的重复执行：

• 每个include都会重复执行路径拼接、索引查找等操作，Jekyll是单线程处理模板，数千个链接会显著增加构建时间
• Liquid本身是解释型模板语言，执行效率远低于原生Ruby代码，大量重复调用会放大性能损耗

更优实现方式 #

1. 优化现有include代码（低成本改造） #

合并重复逻辑，减少Liquid判断次数：

{% comment %} 通用路径拼接逻辑 {% endcomment %}
{% assign lang_path = "_" | append: page.lang | append: "/" | append: include.path %}
{% assign en_path = "_en/" | append: include.path %}

{% comment %} 优先当前语言，不存在则用英文 {% endcomment %}
{% assign post = site.docs_by_path[lang_path] %}
{% unless post %}
  {% assign post = site.docs_by_path[en_path] %}
{% endunless %}

{% comment %} 输出链接 {% endcomment %}
{% if post[0] %}
  <a href="{{ post[0] }}">{{ post[1] }} <sup>{{ site.data.i18n[page.lang].english_note }}</sup></a>
{% else %}
  <a href="wrong-link-target">无效链接：{{ lang_path | default: en_path }}（页面：{{ page.url }}）</a>
{% endif %}

注：可把多语言提示文本（如in English、in inglese）放到_data/i18n.yml中，实现统一管理

2. 自定义Jekyll Tag（高性能方案） #

用Ruby编写自定义Tag代替Liquid include，执行效率提升明显，适合大量链接场景：

1. 在_plugins目录下创建localized_link.rb：

module Jekyll
  class LocalizedLinkTag < Liquid::Tag
    def initialize(tag_name, path, tokens)
      super
      @path = path.strip.delete('"\'')
    end

    def render(context)
      site = context.registers[:site]
      page_lang = context['page']['lang'] || 'en'
      docs_index = site.data['docs_by_path'] || site.config['docs_by_path']

      # 拼接路径
      lang_path = "_#{page_lang}/#{@path}"
      en_path = "_en/#{@path}"

      # 查找目标文章
      post = docs_index[lang_path] || docs_index[en_path]

      if post&.first
        # 从i18n数据中获取提示文本
        note = site.data['i18n'][page_lang]['english_note'] || 'in English'
        "<a href=\"#{post.first}\">#{post.last} <sup>#{note}</sup></a>"
      else
        "<a href=\"wrong-link-target\">无效链接：#{lang_path}（页面：#{context['page']['url']}）</a>"
      end
    end
  end
end

Liquid::Template.register_tag('localized_link', Jekyll::LocalizedLinkTag)

2. 在页面中使用：

{% localized_link 'getting-started/test.md' %}

3. 预生成多语言映射（极致优化） #

在构建前通过插件预生成所有文章的多语言对应关系，存储在site.data中，后续直接查询即可，避免每次链接都重复拼接路径：

• 编写生成器插件，遍历所有文章，为每个文件生成当前语言和 fallback 语言的路径映射
• 页面中直接调用预生成的映射数据，无需每次拼接查找

附加问题：Include输出被包裹在p标签中 #

这是Markdown解析器的默认行为：当Markdown中出现块级HTML元素（如<div>）时，会自动用<p>标签包裹。解决方法：

• 去掉块级容器：直接输出<a>标签，不要用<div>包裹include的内容
• 禁用Markdown解析：在include标签前后添加{% raw %}或调整排版，避免Markdown触发块级解析
• 配置解析器：在_config.yml中修改kramdown配置，关闭自动包裹块级HTML的功能：

  kramdown:
    parse_block_html: true
  

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