如何编写同时兼容Markdown查看器与Jekyll的文档链接？

你需要的是同时兼容两种环境的链接写法，以下是几种实用方案：

方案1：利用Jekyll配置+无后缀链接（最省心） #

在Jekyll的_config.yml中配置permalink规则，比如：

permalink: pretty

然后使用不带.md后缀的链接：

[some link](path/to/file)

• 普通Markdown查看器：多数现代查看器（如VS Code预览、Typora）会自动尝试补全.md后缀，直接打开对应的文件；少数不支持的查看器，用户只需手动添加.md即可访问。
• Jekyll编译：会自动将无后缀路径转换为编译后的HTML路径（如path/to/file/index.html或path/to/file.html，取决于你的permalink配置）。

方案2：双链接注释法（完全兼容） #

这种写法让两种环境各自解析对应的链接，互不干扰：

[some link](path/to/file.md)
<!-- [some link]({% link path/to/file.md %}) -->

• 普通Markdown查看器：仅解析第一行的标准.md链接，HTML注释内容会被忽略，完全正常显示。
• Jekyll编译：你需要在布局文件（如_layouts/default.html）中添加一段Liquid处理逻辑，替换掉原始的.md链接：

  {{ content | replace: '.md)', ')' | remove: '<!-- ' | remove: ' -->' }}
  

  这段代码会移除.md后缀，并去掉HTML注释标记，让Jekyll执行{% link %}标签生成正确的HTML链接。

方案3：Liquid环境判断法（需查看器支持Liquid高亮） #

利用Jekyll的环境变量区分编译状态，编写条件判断链接：

{% if jekyll %}
[some link]({% link path/to/file.md %})
{% else %}
[some link](path/to/file.md)
{% endif %}

• Jekyll编译：识别jekyll变量，执行{% link %}生成正确的HTML链接。
• 普通Markdown查看器：会显示Liquid标签，但多数支持语法高亮的查看器会将其作为代码块样式展示，不影响链接的可读性，用户仍可复制.md路径访问。

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