是否有可能生成一个自动目录使用Github调味Markdown?


当前回答

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

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

其他回答

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

* auto-gen TOC:
{:toc}

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

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

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

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

您可以将其作为一个单独的脚本,也可以将其作为构建脚本例程的一部分(例如Gulp)。

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

:with_toc_data -添加HTML锚的每个头在输出HTML, 允许链接到每个部分。

似乎你需要在渲染器级别设置这个标志,这在Github上显然是不可能的。然而,Github Pages的最新更新,似乎自动锚定是为标题打开的,创建可链接的标题。这不是你想要的,但它可能会帮助你更容易地为你的文档创建一个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/^#//'

如果有人知道更好的方法来做这些最终的#替换,请添加评论。我尝试了各种各样的方法,但都不满意,所以我就硬着硬着。

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

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

Installation:

NPM install -g doctoc

Usage:

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

DocToc WebApp

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

Github维基和锚

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

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