Gitdown是Github的markdown预处理器。

使用Gitdown你可以:

生成目录 查找失效的url和片段标识符 包括变量 包含文件 获取文件大小 生成徽章 打印日期 打印关于存储库本身的信息

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

使用它很简单:

var Gitdown = require('gitdown');

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

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

对于Github的Texteditor Atom，请查看这个很棒的插件(或Atom术语中的“包”)，它可以从解析的markdown文件生成“标题的TOC(目录)”文件:

降价目录

一旦安装为Atom-package，您可以使用快捷键ctrl-alt-c在当前光标位置插入基于markdown-doc-structure的TOC…

截图:

原子Keybindings

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

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

插件特性(来自项目的README)

通过锚标记自动链接，例如# A 1→# A -1 深度控制[1-6]使用depthFrom:1和depthTo:6 使用withLinks使能或禁用链接 使用updateOnSave保存时刷新列表 使用有序列表(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/^#//'

如果有人知道更好的方法来做这些最终的#替换，请添加评论。我尝试了各种各样的方法，但都不满意，所以我就硬着硬着。

2021年3月更新:GitHub增加了一个官方解决方案

readme现在显示一个ToC，就像你向下滚动它们:

演示:https://github.com/cirosantilli/test-git-web-interface/tree/master/d

它没有在文档中呈现，因为我想要更好的Ctrl + F，但总比没有强。

Also现在也适用于非readme，例如:https://github.com/cirosantilli/test-git-web-interface/blob/master/md.md

他们还添加了一个存储库设置来启用禁用该功能。太奇怪了，谁会想让它失效呢?在https://github.com/cirosantilli/test-git-web-interface/settings下面

目录 自动生成此存储库中Markdown文件的目录。目录将显示在文件顶部附近。

原来的答案

这是不可能的，除了建议的变通办法。

我建议Kramdown TOC扩展和其他可能性support@github.com和Steven!Ragnarök的回复一如既往:

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

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

另一种解决方法是使用Asciidoc而不是Markdown，后者会渲染toc。现在我的内容已经采用了这种方法。

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

用第二个替换所有第一个(删除所有没有标题的行)

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

然后(将头III转换为空格)

-##
        -

然后(将标题II转换为空格)

-#
    -

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

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

然后(转换最后一个符号小写和破折号而不是空格)

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

删除未使用的最后磅和初始破折号:

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

删除链接中无用的字符:

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

最后在最后链接的周围加上圆括号:

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

瞧!如果你重复足够多的时间，你甚至可以把它放在一个全局宏中。

这并不是对这个问题的直接回答，因为很多人都提供了变通方法。我认为到目前为止，Github还没有正式支持生成TOC。如果你想让GitHub在他们的GFM预览页面上自动呈现一个目录，请参加关于官方功能请求问题的讨论。