Jekyll：将 kramdown 目录放在 _include 中以进行哈希导航答案

【问题标题】：Jekyll: Place the kramdown table of contents in an _include for hash navigationJekyll：将 kramdown 目录放在 _include 中以进行哈希导航
【发布时间】：2015-02-21 01:43:17
【问题描述】：

我想在网页菜单中引入指向页面标题的哈希链接。网页使用 Jekyll 生成，默认布局如下：

<!DOCTYPE html>
<html>

  {% include head.html %}

  <body>

    {% include header.html %}

    <div id="BigFatContainer">
        {{ content }}
        {% include footer.html %}
    </div>
  </body>
</html>

导航到不同页面的菜单位于标题中。在以下 Kramdown 命令的帮助下，我已经能够将目录添加到 {{ content }}：

* Point at which the TOC is attached
{:toc}

可以使用一些丑陋的 JavaScript hack 将这个目录从 {{ content }} 移动到 header.html，但这是一个糟糕的解决方案。不可能将 {:toc} 宏放在 header.html 中，因为 Kramdown 不会解析它，即使您确保它是由 Kramdown 使用例如 this 插件解析的，它也会输出 header.md 的 TOC 而不是内容目录。

【问题讨论】：

标签： jekyll tableofcontents kramdown

【解决方案1】：

@miroslav-nedyalkov 在这里是正确的。按照他查看 Bootstrap 文档的建议，我发现它使用了 Ruby Gem - jekyll-toc，它允许您将 TOC 放置在布局文件中的任何位置。你在前面启用它。我现在正在成功使用：

<nav aria-label="Table of Contents">
    {{ content | toc_only }}
</nav>

<section itemprop="articleBody">
    {{ content }}
</section>

【讨论】：

【解决方案2】：

我建议您使用Bootstrap website（向下滚动并观察右侧导航区域）正在使用的方法 - 将您的目录作为内容区域的一部分，但将其设置为像主导航一样放置在侧面。我建议您使用这种方法的主要原因是您可能（并且很可能会）拥有不止一页。在这种情况下，您需要为每个页面显示不同的页面导航，并在页面之间显示一些导航。

【讨论】：

我同意，TOC 是页面内容的一部分，而不是主导航。
没有解决 OP 的主要目标，即将 TOC 移到 {{ content }} 之外。

【解决方案3】：

为什么要移动 toc 块？

说这个toc 是页面内容的一部分是正确的。从语义上讲。

您的问题不是在文档结构级别，而是在演示级别。

在这种情况下，建议使用 CSS 来解决您的问题。

【讨论】：

想象一下冗长的文档或查看this 设计以了解在文档的菜单结构中包含TOC 的意义。
我保持对信息架构的立场。您提到的网站没有将主导航与页面导航混合在一起：它是一个单页网站。
感谢您的反对。这真的很有建设性。