自动TOC在github风味markdown

小开

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

* auto-gen TOC:
{:toc}

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

这将使用文档中的头文件生成一组嵌套的无序列表。

注意:这应该适用于GitHub页面，而不是在评论或wiki页面中使用的GitHub调味Markdown (GFM)。我想这个问题没有解决办法。

小开

Github调味Markdown使用红地毯作为他们的Markdown引擎。从RedCarpet回购:

:with_toc_data -添加HTML锚到输出HTML中的每个头，允许链接到每个节

似乎你需要在渲染器级别设置这个标志，这在Github上显然是不可能的。然而，最新更新到Github页面，似乎自动锚定是为标题打开的，创建可链接的标题。这不是你想要的，但它可能会帮助你更容易地为你的文档创建一个TOC(尽管是手动的)。

小开

最佳答案

我创建了两个选项来生成一个toc的github风味markdown:

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

安装:

npm install -g doctoc

用法:

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

<罢工> DocToc WebApp

如果你想先在线试试，去doctoc网站，粘贴标记页面的链接，它将生成一个表可以插入markdown文件顶部的内容。

. txt

Github维基和锚

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

更新:但是，他们修复了这个问题。

小开

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

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

小开

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

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

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

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

-##
-

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

-#
-

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

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

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

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

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

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

删除链接中无用的字符:

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

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

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

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

小开

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和史蒂文!世界毁灭回复通常:

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

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

另一个解决方法是使用Asciidoc代替Markdown，哪个渲染toc。现在我的内容已经采用了这种方法。

小开

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

npm install -g coryfklein/doctoc

小开

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');

你既可以把它作为一个单独的脚本，也可以把它作为构建脚本例程的一部分(比如狼吞虎咽地吃)。

小开

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

与docc等解决方案相比，其优势在于它集成到GitHub的wiki编辑器中，不需要用户使用命令行(并要求用户安装node.js等工具)。在Chrome中，它通过拖拽到扩展页面来工作，在Firefox中，你需要安装GreaseMonkey扩展。

它将与普通markdown工作(即它不能正确处理代码块，因为这是一个GitHub扩展markdown)。贡献的欢迎。

小开

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

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

截图:

vim-markdown-toc

特点:

为Markdown文件生成toc。(支持GitHub调味Markdown和Redcarpet)

更新现有的toc。

保存时自动更新toc。

小开

这并不是对这个问题的直接回答，因为很多人都提供了变通方法。我认为到目前为止，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 . io/" rel="nofollow noreferrer">Atom . io/" rel="nofollow noreferrer，请查看这个很棒的插件(或atom术语中的“包”)，它会生成“从解析markdown标题的TOC(目录)”文件:

markdown-toc

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

截图:

原子键

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

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

插件的功能(来自项目的README)

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

小开

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

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

小开

下面是我今天为此编写的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行动完成这一点:

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

小开

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

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

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

小开

更新2022 - 02年

在VSCode中，查看扩展“Markdown All In one”。自动生成并更新减记的TOC。

安装扩展。
将光标放在您想要插入TOC的位置。
运行命令“Markdown All in One: Create Table of content”;
享受吧!

小开

无耻的“borrow"这个SO答案。

你可以用Pandoc来实现。

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

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