235

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

4

18 回答 18

154

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

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

安装：

npm install -g doctoc

用法：

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

DocToc WebApp

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

Github Wiki 和锚点

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

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

于 2012-05-27T02:37:45.800 回答
26

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

* auto-gen TOC:
{:toc}

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

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

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

于 2012-03-27T22:16:28.913 回答
15

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

用法很简单，只需将光标移动到要追加目录的地方，运行:GenTocGFM，大功告成！

截图：

vim-markdown-toc

特征：

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

  2. 更新现有目录。

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

于 2016-09-18T10:25:42.257 回答
11

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。我现在已经转向这种方法来处理我的内容。

于 2014-06-22T06:46:39.550 回答
10

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

将所有第一个替换为第二个（删除所有没有标题的行）

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

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

-##
        -

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

-#
    -

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

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

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

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

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

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

删除链接中的无用字符：

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

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

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

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

于 2014-03-24T16:00:38.660 回答
8

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

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

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

于 2012-05-24T17:44:34.150 回答
7

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

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

在此处输入图像描述

于 2018-02-05T13:15:53.370 回答
4

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

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

于 2013-04-09T19:45:54.000 回答
3

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）。

于 2014-11-22T15:50:35.823 回答
2

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

npm install -g coryfklein/doctoc
于 2014-11-20T16:50:15.713 回答
1

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

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

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

于 2015-03-12T14:25:06.247 回答
1

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

于 2016-12-22T21:33:11.133 回答
1

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

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

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

于 2020-05-03T07:10:36.373 回答
0

目前无法使用 markdown 语法（请参阅 GitHub 上正在进行的讨论），但是您可以使用一些外部工具，例如：

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

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

## A

### A2

## B

### B2

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

于 2017-07-27T19:43:46.413 回答
0

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

降价目录

安装为 Atom 包后，您可以使用快捷方式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
于 2017-11-28T18:29:57.097 回答
0

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

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

于 2019-08-17T05:38:30.223 回答
0

现在有一个 GitHub Action 来完成这个：

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

  1. 指定目录（选项）的位置，例如README.md
<!-- START doctoc -->
<!-- END doctoc -->
  1. 设置工作流程，例如.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
于 2020-04-04T11:26:49.547 回答
0

2022-02 更新

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

  1. 安装扩展。
  2. 将光标放在要插入 TOC 的位置。
  3. 运行命令“Markdown All in One：创建目录”
  4. 享受！
于 2022-02-04T03:06:24.450 回答