Github-flavoured-markdown中的自动TOC

Question

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

Answer 1

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

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

安装:

npm install -g doctoc

用法:

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

DocToc WebApp

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

Github Wikis和主持人

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

更新:但是,他们解决了这个问题.

Answer 2

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

* 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,完成!

截图:

特征:

1. 为Markdown文件生成toc.(支持GitHub Flavored Markdown和Redcarpet)

2. 更新现有的toc.

3. 保存时自动更新toc.

Answer 5

Github Flavored Markdown使用RedCarpet作为他们的Markdown引擎.来自RedCarpet回购:

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

看起来你需要在渲染器级别设置这个标志,这在Github上是不可能的.但是,对Github Pages 的最新更新,似乎为标题打开了自动锚定,创建了可链接的标题.不完全是你想要的,但它可能会帮助你更轻松地为你的文档创建一个TOC(尽管是手动).

Answer 6

除了提出的解决方法之外,这是不可能的.

我向support@github.com和史蒂文提出了 Kramdown TOC扩展和其他可能性!Ragnarök回答说:

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

让我们提出这个问题直到它发生.

另一种(通常是不可接受的)解决方法是使用asciidoc而不是Markdown,它确实渲染TOC.

Answer 7

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

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