在GitHub维基中如何创建目录表？

Question

在GitHub维基中如何创建目录表？

githubwiki

203

如果您看这里：http://en.wikipedia.org/wiki/Stack_Overflow，您会注意到有一个小的“内容”部分。如果您单击其中一个链接，它将把您发送到页面上的特定部分。

我如何在GitHub wiki中做到这一点？使用Markdown或任何其他可用的方式？

- Evan

3

相关但不完全相同的内容，更加详细：https://dev59.com/ymkw5IYBdhLWcg3wrsjn - Jon Adams

2

2021年3月更新（近8年后）：GitHub可以自动创建README.md的目录。请参见我的答案。 - VonC

1

2021年8月更新：GitHub可以自动创建您的wiki的目录！请参见下面我编辑过的答案。 - VonC

GitHub现在会根据标题自动生成Wiki的目录表。https://github.blog/changelog/2021-08-19-table-of-content-for-wikis/ - dipree

14个回答

72

Visual Studio Code

如果您使用 Visual Studio Code，有一个名为 Markdown All in One 的易于使用的扩展程序可以在瞬间为任何 .md 文件创建目录。

只需打开命令面板 (Ctrl-Shift-P) -> Markdown: Create Table of Contents

自动更新搞乱了您编辑的目录？

作为额外提示，您可能希望通过使用以下方法将“保存时自动更新目录”设置为OFF

  "markdown.extension.toc.updateOnSave": false,

在您的 Visual Studio 设置中(Command Palette -> Preferences: Open Settings (JSON))。

- np8

11

非常有帮助，从查看你的答案到在我的GitHub仓库上创建目录约耗时3分钟。非常好的回答，非常感谢。期待在其他情况下也能使用这个插件。 - twknab

65

由于github无法直接使用TOC，但我们有其他替代方案。

你可以通过在线工具自动生成TOC：

从GitHub Markdown或Wiki在线生成目录表格

或者通过本地工具实现：

github-markdown-toc

- Bravo Yeung

在线工具无法处理这样的标题：“＃第1章：介绍某事”。符号“：”被替换为连字符，但根据说明，应该完全删除。编辑：已向Github项目报告了错误。 - Mr.Robot

32

2021年8月更新:

在README中的ToC之后（请参见下面的2021年3月），您现在有：

Wikis的目录

对于Wikis，我们现在根据Markdown标题自动生成目录。

如此处所示：

你使用Wiki吗？
我们刚刚将侧边栏添加了一个自动目录以帮助导航

现在（2021年3月）您可以查看GitHub CEO Nat Friedman 刚刚宣布的消息

GitHub现在会根据标头自动为您的http://README.md文件创建目录。

经过深思熟虑，我们将其作为查看器的功能而不是编辑器的问题：没有特殊的markdown要插入。

因此...它不会修改您的Markdown（README.md或其他.md文件）以插入或更新您的文本：它仅提供了一个菜单，允许快速访问基于markdown标题的文本部分。

这可能是你需要的，也可能不是。

- VonC

7

请注意，这也适用于其他 .md 文件，而不仅仅是 README 文件。 - Kraigolas

1

@Kraigolas 很好！那很方便。 - VonC

1

注意：2021年6月：GitLab也支持它：https://twitter.com/tonka_2000/status/1399772594568638465 - VonC

@Kraigolas，能否让这个也在gist的.md文件中工作？ - abu

@abu 我现在还没有在gist中看到那个。 - VonC

显示剩余3条评论

30

提供一种（半自动化）解决方案是Eugene Kalinin的github-markdown-toc。该工具基本上通过您的README.md文件，并筛选出#标题，以创建目录。

下载脚本https://github.com/ekalinin/github-markdown-toc
将您的README.md文件提供给脚本（如Eugene的README.md中所述）

cat README.md | bash github-markdown-toc
剪切并粘贴生成的目录，并将其放置在README.md文件的顶部

请注意，此bash实现仅适用于Linux（据我所知）。

另外，还有一个Go语言的实现，可能更麻烦。

- John Tran

19

https://github.com/jonschlinkert/markdown-toc

git clone your-repo.wiki.git（将 .wiki 添加到 .git 之前克隆Wiki）
npm i -g markdown-toc（全局安装markdown-toc）
在你的Wiki的Markdown中插入（大小写敏感）
markdown-toc -i my-wiki-markdown.md（-i 在原地进行编辑）
收益

更新：我认为https://github.com/thlorenz/doctoc现在更受欢迎。

- corysimmons

16

目前使用Markdown语法（.md）不可能做到这一点。有人正在非官方地讨论在呈现的Markdown文件中自动生成目录TOC，例如README.md，其中列出了一些想法。

但是还有一些其他解决方法，例如：

Use AsciiDoc instead as per suggestion from this comment. For example:
```
:toc: macro
:toc-title:
:toclevels: 99
# Title

toc::[]

## A

### A2

## B

### B2
```
Check the example at littlebits/react-popover (README.adoc).
Online Table Of Content Generator (raychenon/play-table-of-contents)
arthurhammer/github-toc - browser extension that adds a table of contents to GitHub repos

- kenorb

1

是的，我主要已经转换为使用asciidoc格式，因为它可以很好地生成目录并链接到标题。我已经厌倦了等待Markdown赶上的过程。 - Ciro Santilli OurBigBook.com

8

如果您无法使用Markdown，可以按照以下方法操作：

在GitHub / wiki上：将Markdown切换到MediaWiki。使用__TOC__语法。请参见示例。

在GitHub / repo上：将Markdown切换到AsciiDoc。使用:toc:语法。请参见演示。

在GitHub / repo上：将Markdown切换到reStructuredText。使用.. contents::语法。

然而，在GitHub / repo中使用Markdown文件，您可以像维基百科一样在GitHub Pages上获得它

当激活Jekyll时，默认情况下会使用Kramdown生成GitHub Pages。

Kramdown带有目录。使用{:toc}语法。请参见说明。

- eQ19

3

您可以选择编辑模式“MediaWiki”，这将为标题生成目录，例如：

== First ==

== Second ==

- Stefan

True。请参考https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki的示例。 - Agis

3

由于github在处理Markdown后生成html版本时，对h1、h2、h3等标题的id属性有其独特的生成方式（例如Bitbucket使用不同的标题生成方式来创建id="slug"），因此使用反向工程化这个过程的库非常方便，避免重复造轮子。

我发现了一个很好的库markdown-toc用于这个任务。

对我来说，它似乎是最好的解决方案，因为我总是在我的机器上安装了node。

只需执行npx markdown-toc -i file.md即可。

看起来这是该任务中比较受欢迎的工具之一，至少在node.js生态系统中是这样。

ls
cat <<EOF >> test.md | tee 
## Table of Contents

<!-- toc -->
- old toc 1
- old toc 2
- old toc 3
<!-- tocstop -->

## abc
This is a b c.

## xyz
This is x y z.
EOF
ls
cat test.md
npx markdown-toc -i test.md
cat test.md

输出：

- stopsopa

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- RyPeck · Accepted Answer

204

在Markdown速查表的目录中很好地展示了这一点。

##### Table of Contents  
[Headers](#headers)  
[Emphasis](#emphasis)  
...snip...    
<a name="headers"/>
## Headers

如果你将鼠标悬停在 GitHub Markdown 文件中的标题上，你会看到它左边有一个小样本链接，你也可以使用该链接。该链接的格式为 <project URL#<header name>。其中的 <header name> 必须全部小写。

- RyPeck

76

肯定有一种像MediaWiki的__TOC__那样自动生成的方法吧？ - LB--

34

如果您编辑了 GitHub 的 Wiki 页面，并将 "editing style" 下拉菜单更改为 "MediaWiki"，那么您可以直接使用 MediaWiki 的 __TOC__。明显的自动生成逻辑已经存在。但是这个功能似乎在他们的 Markdown 编辑风格中没有暴露出来。非常遗憾。让我们开始提交功能请求，也许他们会开启它。 - Andrew Janke

6

我反悔关于“底层自动生成逻辑”存在的说法；看起来不同的“编辑样式”通过不同的渲染器进行处理。尽管如此，将其添加到 Markdown 版本中仍然是很好的选择，因为那相当受欢迎而且并不难实现。 - Andrew Janke

7

我看了一下，似乎 Markdown 格式不支持自动生成目录，而且他们对此感到自豪。 - LB--

8

创建链接有一个注意点，链接必须是小写字母。我不知道这一点，一直在想为什么我的目录没有效果。我使用了 #Headers 而不是 #headers。我以为这是你答案中的笔误。也许你可以在你的回答中加入这个信息。 - t3chb0t

显示剩余2条评论