Question

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

Answer 1

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

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

安装：

npm install -g doctoc

用法：

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

DocToc WebApp

~~如果您想先在线试用，请转到doctoc网站，粘贴降价页面的链接，它将生成一个表格您可以在降价文件顶部插入的内容。~~

Github Wikis和Anchors

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

更新：但是，他们修复了this issue。

Answer 2

GitHub Pages（基本上是Jekyll的包装）appears to use kramdown，implements all of Maruku，因此通过toc属性支持automatically generated table of contents：

* auto-gen TOC:
{:toc}

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

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

注意：这应该适用于GitHub页面，而不是评论或维基页面中使用的GitHub Flavored Markdown（GFM）。 AFAIK不存在解决方案。

Answer 3

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

首先将所有内容全部替换为秒（删除所有没有标题的行）

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

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

-##
        -

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

-#
    -

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

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

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

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

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

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

删除链接中无用的字符：

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

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

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

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

Answer 4

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

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

截图：

vim-markdown-toc

特点：

为Markdown文件生成toc。（支持GitHub Flavored Markdown和Redcarpet）
更新现有的toc。
保存时自动更新toc。

Answer 5

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

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

看起来你需要在渲染器级别设置这个标志，这在Github上是不可能的。但是，latest update到Github页面，似乎为标题打开了自动锚定，创建了可链接的标题。不完全是你想要的，但它可能会帮助你更轻松地为你的文档创建一个TOC（尽管是手动的）。

Answer 6

除了提出的解决方法之外，它是不可能的。

我proposed Kramdown TOC扩展以及support@github.com的其他可能性和Steven! Ragnarök通常回复：

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

让这个问题直到它发生。

另一种（通常是不可接受的）解决方法是使用asciidoc而不是Markdown，which does render TOCs。

Answer 7

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

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

Answer 8

Gitdown是Github的降价预处理器。

使用Gitdown你可以：

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

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

使用它很简单：

var Gitdown = require('gitdown');

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

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

Answer 9

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

它可以为现有的降价文件添加一个toc，甚至可以使toc保持最新状态。

Answer 10

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

npm install -g coryfklein/doctoc

Answer 11

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

与doctoc等解决方案相比，它的优势在于它集成到GitHub的wiki编辑器中，并且不需要用户在其命令行上工作（并且需要用户安装node.js等工具）。在Chrome中，它可以拖放到Extensions页面，在Firefox中你需要安装GreaseMonkey扩展。

它将使用简单的markdown（即它不能正确处理代码块，因为这是Markdown的Markit扩展）。欢迎捐款。

Answer 12

目前它not possible使用降价语法（请参阅正在进行的discussion at GitHub），但您可以使用一些外部工具，例如：

在线Table Of Content Generator（raychenon/play-table-of-contents）
arthurhammer/github-toc - 向GitHub repos添加目录的浏览器扩展

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

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

## A

### A2

## B

### B2

正如comment中所述。查看演示here。

Answer 13

对于 Github的Texteditor Atom ，请查看这个非常棒的插件（或＃34;包＆＃34;在Atom-lingo中），它会生成＆＃ 34;来自已解析的markdown＆＃34; 文件的标题的TOC（目录）：

<强> markdown-toc

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

<强>截图：

Atom键绑定

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

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

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

通过锚标签自动链接，例如# A 1→#a-1
使用depthFrom:1和depthTo:6
启用或停用withLinks:1
使用updateOnSave:1
使用有序列表（1. ...，2。...）和orderedList:0

Answer 14

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

Answer 15

这是我今天为此整理的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 16

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

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

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

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

设置工作流程例如.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 17

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

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

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

Github-flavoured-markdown中的自动TOC

17 个答案:

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

DocToc WebApp

Github Wikis和Anchors