github-flavored-markdown 中的自动 TOC

Question

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

Answer 1

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

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

安装：

npm install -g doctoc

用法：

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

DocToc WebApp

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

Github Wiki 和锚点

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

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

Answer 2

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

* auto-gen TOC:
{:toc}

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

这会使用文档中的标题生成一组嵌套的无序列表。

注意：这应该适用于 GitHub Pages，而不适用于评论或 wiki 页面中使用的 GitHub Flavored Markdown (GFM)。 AFAIK 对此不存在解决方案。

Answer 3

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

用法很简单，只需将光标移动到要附加目录的位置并运行:GenTocGFM ，完成！

截图：

特征：

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

2. 更新现有目录。

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

Answer 4

2021 年 3 月更新：GitHub 添加了官方解决方法

当您向下滚动到自述文件时，自述文件现在会显示这样的 ToC：

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

它不会像我想要的那样在文档中呈现更好的 Ctrl + F，但总比没有好。

现在也适用于非自述文件，例如： https ://github.com/cirosantilli/test-git-web-interface/blob/master/md.md

他们还添加了一个存储库设置来启用禁用它。 这太奇怪了，谁会想要禁用它？ 在https://github.com/cirosantilli/test-git-web-interface/settings下功能：

目录

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

原始答案

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

我向 support@github.com 和Steven提出了Kramdown TOC 扩展和其他可能性！ 诸神黄昏以平常的方式回答：

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

让我们支持这个问题，直到它发生。

另一种解决方法是使用 Asciidoc 而不是 Markdown， 后者会渲染 TOC 。 我现在已经转向这种方法来处理我的内容。

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\)

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

Answer 6

Github Flavored Markdown 使用 RedCarpet 作为他们的 Markdown 引擎。 从红地毯回购：

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

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

Answer 7

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

它可以将目录添加到现有的降价文件中，甚至可以在保存时使目录保持最新。

Answer 8

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

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

Answer 9

Gitdown是 Github 的降价预处理器。

使用 Gitdown，您可以：

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

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

使用它很简单：

var Gitdown = require('gitdown');

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

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

Answer 10

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

npm install -g coryfklein/doctoc

Answer 11

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

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

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

Answer 12

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

与 doctoc 之类的解决方案相比，它的优势在于它集成到 GitHub 的 wiki 编辑器中，并且不需要用户在他们的命令行上工作（并且需要用户安装诸如node.js之类的工具）。 在 Chrome 中，它通过拖放到扩展页面中来工作，在 Firefox 中，您需要安装 GreaseMonkey 扩展。

它将与普通的降价一起工作（即它不能正确处理代码块，因为那是降价的 GitHub 扩展）。 欢迎投稿。

Answer 13

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

Answer 14

这个 SO 答案的无耻“借用”。

你可以用Pandoc做到这一点。

pandoc -s --toc input.md -o input_toc.md 

注意：输入和输出文件的顺序在这里很重要。

Answer 15

目前无法使用 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

正如本评论中所建议的那样。 在此处查看演示。

Answer 16

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

降价目录

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

截图：

原子键绑定

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

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

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

• 通过锚标签自动链接，例如# A 1 → #a-1
• 深度控制 [1-6] 与depthFrom:1和depthTo:6
• 使用withLinks:1启用或禁用链接
• 使用updateOnSave:1在保存时刷新列表
• 使用有序列表 (1. ..., 2. ...) 和orderedList:0

Answer 17

这是我今天为此编写的一个 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/^#//'

如果有人知道更好的方法来完成最后的 # 替换，请添加评论。 我尝试了各种各样的事情，但对任何事情都不满意，所以我只是蛮力的。

Answer 18

现在有一个 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

Answer 19

2022-02 更新

在 VSCode 中，查看扩展“Markdown All in One”。 它会自动生成和更新markdown的TOC。

1. 安装扩展。
2. 将光标放在要插入 TOC 的位置。
3. 运行命令“Markdown All in One：创建目录”
4. 享受！