Github 页面：带有 jekyll-theme-minimal 或其他可以轻松切换到的页面上的自动目录？

Question

我有一个使用 Github Pages 的博客，并且是从 jekyllnow 分叉的。

我在_config.yml中使用了jekyll-theme-minimal（我认为这可能是从jekyllnow继承的，我不记得了）。

在每个页面上，我想要使用所有

#, ##, ###

标签自动生成目录 (TOC)。

这对于 jekyll-theme-minimal 来说是可能的吗？如果不是，那么可以通过其他一些可以轻松移动到的主题。我有很多现有页面，并且我不想以需要进行大量更改才能使现有页面正常工作的方式更改主题。

Answer 1

您可以使用插件（但您需要调整构建过程），或者在您的 jekyll-now fork 中自行添加 ToC（默认构建就足够了）。

使用插件

在 GitHub Pages 上托管的 Jekyll 站点上使用

jekyll-toc

或任何非白名单插件需要不同的方法，因为出于安全原因，GitHub Pages 仅支持一组有限的插件。您将需要更改

jekyll-now

分支的构建过程。

为此，您可以使用 GitHub Actions 构建站点并将生成的

_site

目录部署到

gh-pages

分支。

• 在存储库中创建一个新文件：

  .github/workflows/jekyll_build.yml

  。

• 将以下内容添加到

  jekyll_build.yml

  文件中：

  name: Build and deploy Jekyll site to GitHub Pages
  
  on:
  push:
      branches:
      - master
  
  jobs:
  build:
      runs-on: ubuntu-latest
  
      steps:
      - name: Checkout repository
      uses: actions/checkout@v2
  
      - name: Set up Ruby
      uses: ruby/setup-ruby@v1
      with:
          ruby-version: 2.7
  
      - name: Build Jekyll site
      run: |
          gem install bundler
          bundle install
          bundle exec jekyll build
  
      - name: Deploy to GitHub Pages
      uses: peaceiris/actions-gh-pages@v3
      with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./_site
  

然后需要配置 Jekyll TOC 插件

将

jekyll-toc

gem 添加到您的

Gemfile

:

group :jekyll_plugins do
  gem "jekyll-toc"
end

然后运行

bundle install

。

然后更新

_config.yml

以包含该插件：

plugins:
  - jekyll-toc

在布局中使用该插件：例如，在

_layouts/post.html

中，您希望目录出现的位置：

{{ content | toc }}

当您将更改推送到

master

分支时，GitHub 操作将触发。它将使用该插件构建您的 Jekyll 站点，然后将其部署到

gh-pages

分支。
确保您的 GitHub Pages 设置设置为从

gh-pages

分支提供服务（请参阅“为 GitHub Pages 站点配置发布源”）。

现在，每次推送到

master

时，该站点都会使用 TOC 插件构建并部署到

gh-pages

分支。

手动添加目录

该方法不依赖于任何插件，并且不需要构建更改。
您可以使用简单的脚本从标头生成目录。将其添加到帖子布局的末尾 (

_layouts/post.html

):

<script>
document.addEventListener("DOMContentLoaded", function() {
    var toc = "";
    var level = 0;

    document.getElementById("post-content").innerHTML =
        document.getElementById("post-content").innerHTML.replace(
            /<h([\d])>([^<]+)<\/h\1>/g,
            function (str, openLevel, titleText, closeLevel) {
                if (openLevel > level) {
                    toc += (new Array(openLevel - level + 1)).join("<ul>");
                } else if (openLevel < level) {
                    toc += (new Array(level - openLevel + 1)).join("</ul>");
                }
                level = parseInt(openLevel);

                var anchor = titleText.replace(/ /g, "_");
                toc += "<li><a href='#" + anchor + "'>" + titleText + "</a></li>";

                return "<h" + openLevel + "><a name='" + anchor + "'>" + titleText + "</a></h" + openLevel + ">";
            }
        );

    if (level) {
        toc += (new Array(level + 1)).join("</ul>");
    }

    document.getElementById("toc").innerHTML += toc;
});
</script>

然后准备您的内容。确保您的帖子内容包含在

div

中，且

id

为“

post-content

”：

<div id="post-content">
    {{ content }}
</div>

为目录添加占位符：无论您希望目录出现在何处，请添加一个空的

div

，其 id 为“

toc

”：

<div id="toc">
    <strong>Contents:</strong>
</div>

您可以选择设置目录样式：将其包含在主样式表中或头部的

<style>

标签内。

#toc ul {
    list-style-type: none;
}
#toc li {
    margin: 5px 0;
}
#toc a {
    text-decoration: none;
}

它使用 JavaScript 和 CSS 的组合来根据标题生成目录 (

#, ##, ###, ...

)。它不需要任何 Jekyll 插件，因此与 Jekyll Now 完全兼容，并且无需任何额外设置即可在 GitHub Pages 上运行。