如何在GitHub wiki中创建某种内容表？

Question

如果你看这里：http://en.wikipedia.org/wiki/Stack_Overflow

您会注意到有一些“内容”部分，如果您点击其中一个链接，它会将您发送到页面上的特定部分。

我如何在GitHub wiki中执行此操作？使用Markdown或他们使用的任何东西？

Answer 1

在Markdown Cheatsheet的目录中很好地证明了这一点。

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

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

Answer 2

一种可能的（半自动化）解决方案是Eugene Kalinin的github-markdown-toc。这个工具基本上是通过你的README.md文件和snarfs out出#的标题来创建一个TOC。

1. 下载脚本https://github.com/ekalinin/github-markdown-toc
2. 喂你的README.md到剧本（如Eugene的README.md所述） cat README.md | bash github-markdown-toc
3. 剪切并粘贴生成的TOC并将其放在README.md文件的顶部

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

作为旁注，有一个golang implementation，可能更容易上班。

Answer 3

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

• git clone your-repo.wiki.git（在.wiki之前添加.git来克隆维基
• npm i -g markdown-toc
• 在wiki的降价中插入<!-- toc -->（区分大小写）
• markdown-toc -i my-wiki-markdown.md（-i将编辑它到位）
• 利润

---

更新：我想也许https://github.com/thlorenz/doctoc现在更受欢迎。

Answer 4

目前使用markdown语法（not possible）来做.md。在像discussion about automatically generating table of contents TOC这样的渲染降价文件上有持续的非官方README.md列出了一些想法。

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

• 根据AsciiDoc的建议，使用comment。例如：

  :toc: macro
  :toc-title:
  :toclevels: 99
  # Title
  
  toc::[]
  
  ## A
  
  ### A2
  
  ## B
  
  ### B2

  查看littlebits/react-popover (README.adoc)上的示例。
• 在线Table Of Content Generator（raychenon/play-table-of-contents）
• arthurhammer/github-toc - 浏览器扩展，为GitHub repos添加目录

Answer 5

如果您不能坚持使用Markdown，您可以执行以下操作：

• 在GitHub / wiki上：切换到MediaWiki的Markdown。使用__TOC__语法。见sample。
• 在GitHub / repo上：切换到AsciiDoc的Markdown。使用:toc:语法。见demo。

但是，在GitHub / repo中使用Markdown文件，你可以像GitHub Pages一样在Wikipedia上获取它

• 当Jekyll被激活时，它默认使用Kramdown生成GitHub页面
• Kramdown附带Table Of Content。使用{:toc}语法。见the explanation。

Answer 6

由于github不能直接使用TOC，但我们还有其他选择。

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

Generate TOC Table of Contents from GitHub Markdown or Wiki Online

或通过本地工具：

github-markdown-toc

Answer 7

您可以选择编辑模式“MediaWiki”，它将为标题生成一个toc，例如

== First ==

== Second ==

Answer 8

对我来说最简单的解决方案（虽然我总是安装了node.js服务器，因为npm有npx）是通过执行npx markdown-toc。它似乎是这项任务最受欢迎的解决方案之一：

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

输出：