如何在 kramdown 中向标题添加永久链接？答案

【问题标题】：How do I add permalinks to headers in kramdown?如何在 kramdown 中向标题添加永久链接？
【发布时间】：2016-11-07 15:54:45
【问题描述】：

我正在用 Markdown 编写的 Jekyll 和 Github-Page 建立一个网站。我想像大多数在线文档一样轻松地永久链接到标题。

我想在单击标题时获取带有哈希的 URL。在 Kramdown 或 Jekyll 的配置中是否有简单的方法来实现这一点？

降价页面

#### A regular header

A regular sentence.

理想结果

<h4 id="a-regular-header"><a href="#a-regular-header">A regular header</a></h4>
<p>A regular sentence.</p>

【问题讨论】：

标签： jekyll github-pages kramdown

【解决方案1】：

您可以在每个标题的 Markdown 中手动执行此操作：

#### [A regular header](#a-regular-header)

A regular sentence.

缺点是维护成本。另一种选择是通过将其添加到您选择的页面底部来在客户端创建链接：

<script>
    var headings = document.querySelectorAll("h1[id], h2[id], h3[id], h4[id], h5[id], h6[id]");

    for (var i = 0; i < headings.length; i++) {
        headings[i].innerHTML =
            '<a href="#' + headings[i].id + '">' +
                headings[i].innerText +
            '</a>';
    }
</script>

如果 JavaScript 依赖项不适合您的受众，您可以在构建时查看插件、修改后的 Markdown 解析器或任务运行器（如 gulp.js）来执行此操作。如果您希望 GitHub Pages 构建您的页面，则不能使用这些替代方法，但您可以在本地构建并提交输出。

【讨论】：

谢谢，我最终使用了这样的 JS 解决方案，但我想我会借用你更智能的查询选择器。

【解决方案2】：

如果你想在没有 JavaScript 的情况下使用 GitHub Pages 兼容的方式来做到这一点，你可以使用 Liquid 获得 ~~crazy~~ ^creative 并仔细解析你的渲染将 HTML 作为字符串并对其进行操作。

或者你也可以使用这个 sn-p 来做到这一点：https://github.com/allejo/jekyll-anchor-headings

【讨论】：

【解决方案3】：

您可以使用 Jekyll plugins 来覆盖标准行为。我把这个放在_plugins/header.rb:

class Jekyll::MarkdownHeader < Jekyll::Converters::Markdown
    def convert(content)
        super.gsub(/<h(\d) id="(.*?)">/, '<h\1 id="\2"><a href="#\2">§</a>')
    end
end

正则表达式将所有带有 ID 标记的标头替换为还添加了链接的标头。在一般情况下，这不是一种万无一失的方法（例如<h2 class="foo" id="x") 不起作用），但 Kramdown 输出相当可靠且一致，所以应该没问题。我在 Jekyll 3.8.4 和 Kramdown 1.17.0 中添加了这个。

如果您想要/需要更强大的解决方案，那么您可以使用 HTML 解析器。应该不会那么难。

这样做的好处是它在客户端不需要 JavaScript。

或者，如果您想链接实际标题而不是前置链接：

class Jekyll::MarkdownHeader < Jekyll::Converters::Markdown
  def convert(content)
    super.gsub(/<h(\d) id="(.*?)">(.*)<\/h(\d)>/, '<h\1 id="\2"><a href="#\2">\3</a></h\1>')
  end
end

【讨论】：

【解决方案4】：

从生成器的角度来看，如果没有 Jekyll 插件，这是不可能的。由于您使用的是 GitHub Pages，因此这是不可能的，因为它们不支持自定义插件。

一个合理的解决方案是创建一个脚本来查找所有带有 ID 的标题并将它们转换为链接或附加一个链接图标。

【讨论】：

真；现在有了 Jekyll 3，Github 页面是超级准系统。