github-flavored-markdown中的自动TOC

是否可以使用Github风味Markdown生成自动目录？

我创建了两个选项来为github-flavored-markdown生成toc：

DocToc命令行工具（源）需要node.js

npm install doctoc

npx doctoc . 将目录添加到当前目录和所有子目录中的所有markdown文件中。

DocToc WebApp

如果您想先在线尝试，请访问doctoc网站，粘贴markdown页面的链接，它会生成一个目录，您可以将其插入markdown文件的顶部。

Github Wiki和锚点

正如Matthew Flaschen在下面的评论中所指出的那样，GitHub以前没有为其Wiki页面生成doctoc依赖的锚点。

更新：但是，他们解决了这个问题。

GitHub Pages（基本上是Jekyll的包装器）似乎使用kramdown，它实现了Maruku的全部功能，因此支持通过属性自动生成的目录toc：

* auto-gen TOC:
{:toc}

第一行只是开始一个无序列表，实际上已被丢弃。

使用文档中的标题，这将导致嵌套的一组无序列表。

注意：这应该适用于GitHub Pages，而不是注释或Wiki页面中使用的GitHub Flavored Markdown（GFM）。AFAIK尚无解决方案。

如果使用Vim编辑Markdown文件，则可以尝试使用此插件vim-markdown-toc。

用法很简单，只需将光标移至要添加目录的位置即可运行:GenTocGFM，完成！

屏幕截图：

特征：

1. 生成Markdown文件的目录。（支持GitHub Flavored Markdown和Redcarpet）

2. 更新现有目录。

3. 保存时自动更新目录。

它不是自动的，但是它使用Notepad ++正则表达式：

将所有第一行替换为第二行（删除所有没有标题的行）

^##(#?)(#?)(.*?)$(.|\r|\n)*?(?=^##|\z)
-\1\2 [\3](#\3)\n

然后（将标头III转换为空格）

-##
        -

然后（将标题II转换为空格）

-#
    -

然后（删除链接标题开头和结尾的未使用字符）

\[ *((?:(?![ .:#!\?;]*\])[^#])*)[ #:!\?;]*\]
[\1]

然后（将最后一个标记转换为小写和破折号而不是空格）

\]([^ \r\n]*) ([^\r\n ]*)
]\L\1-\2

删除未使用的最终磅和初始破折号：

(?:()[-:;!\?#]+$|(\]#)-)
\1\2

删除链接中无用的字符：

(\].*?)(?:\(|\))
\1

最后在最终链接周围添加括号：

\](?!\()(.*?)$
\]\(\1\)

和瞧！如果重复足够的时间，您甚至可以将其放在全局宏中。

除建议的解决方法外，这是不可能的。

我向support@github.com和Steven 提出了 Kramdown TOC扩展和其他可能性！Ragnarök的回答是：

感谢您的建议和链接。我将其添加到我们的内部功能请求列表中，以供团队查看。

让我们投票这个问题，直到它发生为止。

另一个解决方法是使用Asciidoc而不是Markdown 来渲染TOC。如今，我已经将这种方法用于我的内容。

Github风味Markdown使用RedCarpet作为Markdown引擎。从RedCarpet仓库：

：with_toc_data-将HTML锚点添加到输出HTML中的每个标头，以允许链接到每个部分。

看来您需要进入渲染器级别才能设置此标志，显然在Github上是不可能的。但是，Github Pages 的最新更新似乎为页眉打开了自动锚定，从而创建了可链接的标题。并非完全符合您的要求，但它可能会帮助您为文档创建目录（更容易）（尽管是手动操作）。

使用Visual Studio Code时，为mardown文件获取目录的一种非常方便的方法是扩展Markdown-TOC。

它可以将toc添加到现有的markdown文件中，甚至可以使toc在保存时保持最新状态。

可以使用http://documentup.com/从README.md文件自动生成一个网页。它并不是在创建TOC，但是对于许多人来说，它可能可以解决创建TOC的原因。

另一种替代Documentup的方法是Flatdoc：http: //ricostacruz.com/flatdoc/

Gitdown是Github的markdown预处理器。

使用Gitdown，您可以：

• 生成目录
• 查找无效的URL和片段标识符
• 包含变量
• 包含文件
• 获取文件大小
• 产生徽章
• 列印日期
• 打印有关存储库本身的信息

Gitdown简化了与维护GitHub存储库文档页面相关的常见任务。

使用起来很简单：

var Gitdown = require('gitdown');

Gitdown
    // Gitdown flavored markdown.
    .read('.gitdown/README.md')
    // GitHub compatible markdown.
    .write('README.md');

您既可以将其作为单独的脚本，也可以将其作为构建脚本例程的一部分（例如Gulp）。

使用coryfklein / doctoc，这是thlorenz / doctoc的一个分支，不会向每个目录添加“ DocToc 生成的 ”。

npm install -g coryfklein/doctoc

我和我的同事@schmiedc创建了一个GreaseMonkey脚本，该脚本在TOC按钮的左侧安装了一个新按钮，该h1按钮使用优秀的markdown-js库来添加/刷新目录。

与doctoc之类的解决方案相比，其优势在于，它可以集成到GitHub的Wiki编辑器中，并且不需要用户在命令行上工作（并且要求用户安装诸如 node.js。在Chrome浏览器中，只需将其拖放到“扩展程序”页面即可。在Firefox中，您需要安装GreaseMonkey扩展程序。

它将与纯markdown一起使用（即，它不能正确处理代码块，因为这是markdown的GitHub扩展）。欢迎捐款。

这并不是对这个问题的直接答案，因为许多人提供了解决方法。我认为到目前为止，Github尚未正式支持生成TOC。如果您希望GitHub在其GFM预览页面上自动呈现目录，请参与有关官方功能请求问题的讨论。

当前无法使用markdown语法（请参阅GitHub上正在进行的讨论），但是您可以使用一些外部工具，例如：

• 在线目录生成器（raychenon / play-table-of-contents）
• arthurhammer / github-toc-浏览器扩展，向GitHub存储库添加目录

替代使用AsciiDoc（例如README.adoc），例如

:toc: macro
:toc-title:
:toclevels: 99
# Title

## A

### A2

## B

### B2

如此评论中所建议。在此处查看演示。

对于Github的Texteditor Atom，请查看这个很棒的插件（或Atom-lingo中的“包”），该插件会从“解析后的降价”中生成“标题的TOC（目录）”文件：

降价

安装为Atom软件包后，您可以使用快捷方式ctrl-alt-c在当前光标位置基于markdown-doc-结构插入TOC。

屏幕截图：

原子键绑定

markdown-toc为您提供以下默认键绑定，以控制Atom中的插件：

• ctrl-alt-c =>在光标位置创建目录
• ctrl-alt-u =>更新目录
• ctrl-alt-r =>删除目录

插件功能（来自项目的自述文件）

• 通过锚标记自动链接，例如 # A 1→#a-1
• 用depthFrom:1和控制深度[1-6]depthTo:6
• 启用或禁用以下链接 withLinks:1
• 刷新保存清单 updateOnSave:1
• 结合使用有序列表（1. ...，2. ...） orderedList:0

这是我今天为此编写的shell脚本。可能需要根据您的需要进行调整，但这应该是一个很好的起点。

cat README.md \
    | sed -e '/```/ r pf' -e '/```/,/```/d' \
    | grep "^#" \
    | tail -n +2 \
    | tr -d '`' \
    | sed 's/# \([a-zA-Z0-9`. -]\+\)/- [\1](#\L\1)/' \
    | awk -F'(' '{for(i=2;i<=NF;i++)if(i==2)gsub(" ","-",$i);}1' OFS='(' \
    | sed 's/^####/      /' \
    | sed 's/^###/    /' \
    | sed 's/^##/  /' \
    | sed 's/^#//'

如果有人知道更好的方法来进行这些最终的＃更换，请添加评论。我尝试了各种各样的事情，但对任何事情都不满意，所以我只是蛮力地强迫了它。

现在有一个GitHub Action完成此任务：

https://github.com/marketplace/actions/toc-generator

1. 指定目录的位置（选项），例如 README.md

<!-- START doctoc -->
<!-- END doctoc -->

2. 设置工作流程，例如 .github/workflows/toc.yml

on: push
name: TOC Generator
jobs:
  generateTOC:
    name: TOC Generator
    runs-on: ubuntu-latest
    steps:
      - uses: technote-space/toc-generator@v2

大多数其他答案都需要安装一些工具。我找到了一个快速简便的在线解决方案https://imthenachoman.github.io/nGitHubTOC。

对于任何降价输入，它都会生成内容输出表。您可以指定最小和最大标题级别。

源代码位于https://github.com/imthenachoman/nGitHubTOC