在GitHub风格的Markdown中自动生成目录

Question

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

- Roberto Aloi

---

如果您使用Linux并且不想安装任何其他软件，请尝试github-markdown-toc（仅在底层使用awk）。 - shorrty

我正在将多个Markdown文件渲染到Jade模板中，生成HTML。因此，我的目录需要包含比单个Markdown文件中找到的更多信息。我的解决方案是使用node.js库toc从HTML代码本身生成TOC。 - Plato

我创建了三个不同的Markdown TOC生成器，试图“搞定它”，包括上面列出的marked-toc。markdown-toc是我最喜欢的，它使用真正的Markdown解析器(remarkable)，遵循commonmark规范，允许更新TOC，具有CLI和API，并且现在被用于数千个项目。 - jonschlinkert

Answer 1

我创建了两个选项来为Github风格的Markdown生成目录：

DocToc命令行工具 (源码) 需要 node.js

安装:

npm install -g doctoc

使用方法:

doctoc . 为当前目录及其所有子目录中的所有Markdown文件添加目录。

DocToc WebApp

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

Github Wikis和锚点

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

更新：然而，他们解决了这个问题。

- Thorsten Lorenz

---

我开发了GitHub Wikifier：一个预提交Git Hook，它将生成您所需的所有目录。只需编写内容，让它接管即可。值得一试。https://github.com/kuroir/GitHub-Wikifier - MarioRicalde

这是一个不错的起点，但它不能生成标准代码。而且，没有有效的锚点。 - Luca Davanzo

DocToc网页应用无法正常工作。我使用了markdown-toc。 - DynamicDan

有一个非常容易设置的操作，可以使用Doctoc: https://github.com/marketplace/actions/toc-generator。 - pietroppeter

Answer 2

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

* auto-gen TOC:
{:toc}

第一行仅开始了一个无序列表，实际上会被忽略。

这将导致使用文档中的标题形成嵌套的无序列表。

注意：这适用于GitHub Pages，而不适用于评论或Wiki页面中使用的GitHub Flavored Markdown（GFM）。据我所知，目前没有解决方案。

- Rebecca Scott

---

这个不起作用。它只是呈现了那段文字。你能否链接一个使用这样的目录的文件？ - Geoffrey De Smet

请注意，这是Maruku的功能，不是Markdown本身，可能甚至不是GH Flavored Markdown。但是，GH-pages确实使用了Maruku。 - Rebecca Scott

@KevinSuttle 你确定吗？Jekyll包括redcarpet，但是maruku仍然看起来像默认设置（除非GH使用不同的jekyll配置）https://github.com/mojombo/jekyll/blob/master/lib/jekyll.rb#L66 - Rebecca Scott

看起来你的解决方案只适用于 GitHub Pages。你知道 GitHub Wiki 的解决方案吗？ - reprogrammer

@reprogrammer 不好意思，我不知道有没有针对维基页面中使用的GFM的任何东西，这很遗憾。 - Rebecca Scott

Answer 3

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

使用方法很简单，只需将光标移动到想要添加目录的位置，运行 :GenTocGFM 命令，完成！

截图：

特性：

1. 为 Markdown 文件生成 TOC。 （支持 GitHub Flavored Markdown 和 Redcarpet）

2. 更新现有的 TOC。

3. 保存时自动更新 TOC。

- Zhuang Ma

---

请确保在协作.md文件时找到一个常见的TOC样式，并涉及不同的编辑器/插件，以避免在每个其他提交中更改TOC。 可能添加到 ~/.vimrc 的内容：使用 let g:vmt_list_item_char = "-" 更改列表字符，在TOC之前包含标题，使用 let g:vmt_include_headings_before = 1。 有关更多信息，请参见文档选项部分，例如如何更改栅栏文本。 - Wolfson

Answer 4

2021年三月更新：GitHub已添加官方解决方案

现在，当您向下滚动查看README文件时，会显示类似于此的目录：

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

它不会像我想要的那样在文档内呈现，以便更好地进行 Ctrl + F，但总比没有好。

现在也适用于非 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扩展和其他可能性来支持@github.com，Steven！Ragnarök做出了如下回复：

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

让我们投票支持这个问题，直到它实现为止。

另一个解决方法是使用Asciidoc而不是Markdown，它可以渲染TOCs。 我现在已经转向这种方法来创建我的内容。

- Ciro Santilli OurBigBook.com

---

我更希望GFM有一天能够提供它。这对我来说真的很奇怪，因为SourceForge的Markdown语法默认生成此TOC。 - eQ19

现在似乎对非readme文件也有效。 - dharmatech

哦，那很好。无论我是使用GitHub还是GitLab，我至少都具备了最小的功能和最少的标记工具。 - Benjamin

Answer 5

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

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

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

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

-##
        -

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

-#
    -

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

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

然后（将最后的单词转换为小写并用破折号代替空格）。

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

删除未使用的末尾井号和初始短横线：

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

去除链接中无用的字符：

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

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

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

现在大功告成了！如果你重复这个过程多次，甚至可以将其放在全局宏中。

- Mikaël Mayer

Answer 6

使用Visual Studio Code编写Markdown文件时，一个非常方便的目录生成方式是使用扩展Markdown-TOC。它可以为现有的Markdown文件添加目录，甚至在保存时保持目录最新。

- Mathias Dpunkt

---

另一个不错的 VS Code 插件（具有出色的 .md 支持，包括 GitHub 和 GitLab 风格的 TOC 等不错的功能）是 markdown-all-in-one。 - Wolfson

Answer 7

Github Flavored Markdown使用RedCarpet作为他们的Markdown引擎。 来自RedCarpet repo:

:with_toc_data-在输出HTML中为每个标题添加HTML锚点，以允许链接到每个部分。

看起来你需要在渲染器级别上设置此标志，但在Github上显然不可能。然而，最新更新到Github Pages，似乎自动锚定已经打开了头，创建可链接标题。不完全是你想要的，但它可能会帮助你更轻松地为你的文档创建目录（尽管手动）。

- Kevin Suttle

Answer 8

可以使用http://documentup.com/从README.md文件自动生成网页。它不会创建目录，但对于许多人来说，这可能是创建目录的原因。

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

- Nils

Answer 9

大多数其他答案需要安装一些工具。 我找到了一个快速简便的在线解决方案：https://imthenachoman.github.io/nGitHubTOC。 对于任何markdown输入，它都可以生成目录输出。 您可以指定标题级别的最小和最大值。

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

- Michael Freidgeim

---

太喜欢了。我200%赞同你的“工具越少越好”的方法。 - Carlo

非常喜欢这个。谢谢。 - programmar

Answer 10

Gitdown是Github的Markdown预处理器。

使用Gitdown，您可以：

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

Gitdown简化了维护GitHub存储库文档页面所涉及的常见任务。

使用它很简单：

var Gitdown = require('gitdown');

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

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

- Gajus