处理文章中的相对链接

[neveler]

• 支持自动转换相对链接 #324

与上面的 PR 的目的一致，均是处理文章中的相对链接的，区别在于本 PR 未使用插件实现。

[burningtnt]

可能是我不太懂 Jekyll，但我没看懂这个 PR 在做什么。

[neveler]

可能是我不太懂 Jekyll，但我没看懂这个 PR 在做什么。

当前站点使用的 Markdown 转换器为 kramdown

HMCL-docs/_config.yml

Line 80 in c852e38

# markdown: kramdown

PR 中似乎没有用到 kramdown 的语法

使用 GFM 方言

HMCL-docs/_config.yml

Line 133 in c852e38

# input: GFM

下面这种写法 (https://github.github.com/gfm/#shortcut-reference-link) 会被渲染为 <a title="dddd" href="cccc">aaaa</a>

[aaaa][bbbb]

[bbbb]: cccc "dddd"

其实等价于 [aaaa](cccc "dddd") 之所以使用上面的方式书写主要是为了在 GitHub 中可以正常预览的同时也可以让站点正常渲染。

在 jekyll 中可以在 md 中使用 liquid 模板语法，但是 Github 并不支持渲染 liquid 模板语法。

{% comment %}
liquid 注释
中间的内容不会被 Jekyll 渲染出来
{% endcomment %}

<--
html 注释
中间的内容不会被 Github 渲染出来
-->

通过将两种注释结合，可以实现双向兼容的效果：

1. 在 Github 中可以渲染而 Jekyll 忽略

<!--{% comment %}-->
在 Github 中可以显示而 Jekyll 忽略
<!--{% endcomment %}-->

上面的写法在 Jekyll 渲染的结果为 <!----> 因此不会在页面中显示，而在 md 中 {% %} 都被 html 注释包裹因此也不会显示 liquid 标签

2. 在 Jekyll 中可以渲染而 Github 忽略

<!----{{'>'}}
在 Jekyll 中可以渲染而 Github 忽略
<!---->

上面的写法在 Github 中会被整个识别为 html 注释，因为第一行的 --{{'>'}} 不会被 Github 识别为注释的结束部分，因此一直到第三行的 --> 才会结束注释，因此三行内容在 Github 里都会被识别为注释不会显示。在 Jekyll 里 {{'>'}} 是插值语法，因此渲染的结果如下则可以正常渲染第二行的内容。

<!---->
在 Jekyll 中可以渲染而 Github 忽略
<!---->

---

liquid 转换相对链接的方法有两种：

1. relative_url filter

基础写法 {{ '/test' | relative_url }}

2. link tag

基础写法 {% link 'test/1.md' }} {% link '/assets/1.png' }}

link 链接静态文件和文章的方式有所不同，链接静态文件前需 '/' 开头，而链接文章则需去掉 '/'

上面两种写法都可以把相对链接转为正确的相对于 baseurl 的链接地址，区别在于 link 标签会更严格，原因在于 link 写法会检查目标是否存在，如果目标不存在会导致构建报错。还有就是 relative_url 不会把 md 的相对链接转换为 html 地址，而 link 会自动转换为文章对应的 permalink 地址。

---

<!--{% comment %}-->
[~/docs/groups]: /_docs/groups.md
<!--{% endcomment %}--{{'>'}}
[~/docs/groups]: {% link _docs/groups.md %}
<!---->

此写法的效果是：

在 GitHub 上，链接目标为 /_docs/groups.md；

在 Jekyll 上，链接目标为 {% link _docs/groups.md %}，即实际生成页面的正确地址。

换句话说，它相当于同时兼顾了以下两种写法：

[xxxxxx](/_docs/groups.md) → GitHub 可用，但 Jekyll 链接错误

[xxxxxx]({% link _docs/groups.md %}) → Jekyll 可用，但 GitHub 链接失效

因此，这种双注释写法可以同时兼顾 GitHub 与 Jekyll 的显示效果。
若仅需确保 Jekyll 渲染正确，直接使用 [xxxxxx]({% link _docs/groups.md %}) 即可。

[burningtnt]

如果我的理解正确，那该 PR 实际上是修复了 所有链接仅能在 Jekyll 环境中正确跳转但不能在 GitHub GFM 中正确渲染 的 Bug。

然而，我没有理解您特意支持 GitHub GFM 链接渲染的意义所在。原先我们没有 PR 预览，确实需要在 GitHub 环境中确认文本链接。但在您贡献的预览构建功能加持下，维护者可主动创建预览页面来调试文本链接。

[neveler]

如果我的理解正确，那该 PR 实际上是修复了 所有链接仅能在 Jekyll 环境中正确跳转但不能在 GitHub GFM 中正确渲染 的 Bug。

然而，我没有理解您特意支持 GitHub GFM 链接渲染的意义所在。原先我们没有 PR 预览，确实需要在 GitHub 环境中确认文本链接。但在您贡献的预览构建功能加持下，维护者可主动创建预览页面来调试文本链接。

可能存在一些误解：该 PR 的核心目标其实是修复相对链接在 baseurl 不为空时的渲染错误。例如，当页面中出现 ![](/xxxxx) 时，其生成的 HTML 链接依然为 /xxxxx，这会导致在 baseurl 不为空的情况下，链接跳转错误、图片无法加载等问题。至于无法在 GitHub GFM 中正确渲染的问题，仅是我在修复过程中顺带一并解决的。

你可以为当前 PR 创建预览，理论上页面中的图片及链接都应能正确指向对应的地址。

举例来说，当 baseurl 不为空时（例如在 PR 预览构建中，以 baseurl: /HMCL-docs/PR312 为例）页面中的 /test.png 这一链接应被渲染为 https://hmcl-dev.github.io/HMCL-docs/PR312/test.png 但实际上却被渲染成了 https://hmcl-dev.github.io/test.png 从而导致资源路径错误。

[burningtnt]

那我的理解确实有误。不过，我认为可以不将 GitHub 原生渲染纳入支持范围，仅提供 [xxxxxx]({% link _docs/groups.md %}) 风格的链接声明来保障 Jekyll 环境中相对链接正确。

[burningtnt]

[Preview] https://hmcl-dev.github.io/HMCL-docs/PR312

[neveler]

那我的理解确实有误。不过，我认为可以不将 GitHub 原生渲染纳入支持范围，仅提供 [xxxxxx]({% link _docs/groups.md %}) 风格的链接声明来保障 Jekyll 环境中相对链接正确。

我个人认为，保留 GitHub 的原生渲染仍有一定意义，如果完全不考虑 Markdown 的可读性，那直接使用 HTML 岂不是更容易。我觉得可以听听其它人的意见，不过当前的写法确实维护成本较高，且不易读。

我有考虑过通过插件自动转换链接的方案，但由于 Jekyll 插件需使用 Ruby 编写，而我对 Ruby 并不熟悉，担心实现不当可能带来安全隐患。理论上可以实现一个插件通过正则替换的方式，为 Markdown 中的 和 自动应用相对路径。