jekyll的kramdown不支持[TOC]自动生成目录的方式,目前了解来看有几种方案:

  1. 在正文中添加如下标签,这个方案优点在于不需要额外配置,github pages也默认支持,缺点在于格式看着不太优雅,不符合markdownlint规范,在visual studio code的markdownlint插件下会导致一堆lint告警;

    * TOC
    {:toc}
    
  2. 使用jekyll-toc插件,这种方式实现比较优雅,也不会破坏markdown源文件,缺点在于github pages并不支持自定义插件;

    • 在网站的gemfile里面添加一行 gem 'jekyll-toc',然后执行bundle install
    • 在网站的_config.yml里面添加插件:

      plugins:
        - jekyll-toc
      
    • 在你的markdown文件里面的头部分加上toc: true
  3. 使用jekyll html的解决方案,这是目前在github pages下推荐的方案;

    • 下载toc.html文件,并放到_includes目录;
    • _layouts下用到的html里面,在content前面加上一行% include toc.html html=content %(前后需要加上{ }