github - 如何在 GitHub wiki 中创建某种目录？

Question

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

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

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

score 154 · Accepted Answer

它在Markdown Cheatsheet的目录中得到了很好的展示。

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

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

score 48 · Accepted Answer

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

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

从 GitHub Markdown 或 Wiki Online 生成 TOC 目录

或通过本地工具：

github-markdown-toc

score 30 · Accepted Answer

视觉工作室代码

如果您碰巧使用Visual Studio Code ，有一个名为 Markdown All in One的易于使用的扩展程序，可以立即为任何 .md 文件生成目录。

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

自动更新会弄乱您编辑的目录？

作为附加提示，您可能希望通过使用关闭“保存时自动 TOC 更新”

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

在您的 Visual Studio 设置中（命令面板 -> 首选项：打开设置 (JSON)）。

score 29 · Accepted Answer

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

下载脚本https://github.com/ekalinin/github-markdown-toc
将您README.md输入到脚本中（如 Eugene's 中所述README.md）

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

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

附带说明一下，有一个 golang实现，可能更麻烦的是开始工作。

score 23 · Accepted Answer

2021 年 8 月更新：

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

Wiki 目录

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

如此处所示：

你维基吗？
我们刚刚在侧边栏中添加了一个自动目录以帮助导航

您现在可以（2021 年 3 月）查看 GitHub 首席执行官 Nat Friedman刚刚宣布的内容

GitHub 现在会自动从您的标题中为您的http://README.md文件创建目录。

经过深思熟虑，我们将此作为查看器的功能，而不是编辑器的关注点：无需插入特殊的降价。

所以......它不会修改您的降价（README.md或其他.md文件）以插入或更新您的文本：它只提供一个菜单，允许基于降价标题快速访问您的测试部分。
这可能是，也可能不是，你所追求的。

score 16 · Accepted Answer

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

git clone your-repo.wiki.git（在克隆维基.wiki之前添加权利.git
npm i -g markdown-toc
在 wiki 的 markdown 中插入（区分大小写）
markdown-toc -i my-wiki-markdown.md（-i将就地编辑它）
利润

更新：我想也许https://github.com/thlorenz/doctoc现在更流行了。

score 15 · Accepted Answer

目前，使用 markdown 语法 ( ) 是不可能.md的。关于在渲染的降价文件上自动生成目录 TOC的非官方讨论正在进行中，README.md其中列出了一些想法。

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

AsciiDoc根据此评论的建议改用。例如：
```
:toc: macro
:toc-title:
:toclevels: 99
# Title

toc::[]

## A

### A2

## B

### B2
```
检查littlebits/react-popover( README.adoc)处的示例。
在线目录生成器( raychenon/play-table-of-contents )
arthurhammer/github-toc - 将目录添加到 GitHub 存储库的浏览器扩展

score 8 · Accepted Answer

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

在GitHub/wiki上：将Markdown切换到MediaWiki。使用__TOC__语法。见样本。

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

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

但是，使用GitHub/repo中的Markdown文件，您可以在GitHub 页面上获取它，例如在Wikipedia中

Jekyll激活后，默认使用Kramdown生成GitHub Pages

Kramdown附带Table Of Content. 使用{:toc}语法。见说明。

score 3 · Accepted Answer

由于 github 有自己的方式在 h1、h2、h3 等中生成 id=".." 属性...在处理 Markdown 后的 html 版本中的标头（例如 Bitbucket 使用很少不同的模式来缓和标头标题id="slug") 不要重新发明轮子并使用对这个过程进行逆向工程的库是很方便的。

我为这项任务找到了一个非常好的库，称为markdown-toc。

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

只需执行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

输出：

score 2 · Accepted Answer

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

== First ==

== Second ==

score 1 · Accepted Answer

1

你可以使用mdtoc（我是作者）。

安装后，只需运行：

mdtoc path/to/file.md

于 2021-09-01T22:53:17.333 回答

score 1 · Accepted Answer

Pandoc是标记的瑞士军刀。它可以将与 GitHub 兼容的目录添加到README.md使用以下命令调用的 markdown 文件中：

pandoc --from markdown --to markdown --table-of-contents --standalone  README.md

--from和--to选项是必需的，并且--table-of-contents需要--standalone. 这些选项有简短的版本，所以这是等效的：

pandoc -f markdown -t markdown --toc -s README.md

默认情况下，该命令会添加目录并将结果写入标准输出。由于您可能只需要目录本身，因此您可能希望通过管道连接到寻呼机以查看文件的顶部。例如：

pandoc -f markdown -t markdown --toc -s README.md | less

其他有用的选项是：

--toc-depth=NUMBER指定要包含的标题级别。默认值为 3。
--output=FILE写入文件而不是标准输出。

有关安装和更多使用说明，请参见https://pandoc.org。

score 0 · Accepted Answer

例子：

[Go to Delete](#delete_lines)

#delete_lines

code here, will be pointed here

见：https ://guides.github.com/features/mastering-markdown/

并且，要制作嵌套轮廓：

* 1\. [Go to Delete](#delete_lines)
    * 1.1\. item
    * 1.2\. item
        * 1.2\. item
* 2\. item

请参阅：https ://meta.stackexchange.com/questions/85474/how-to-write-nested-numbered-lists

有关更多信息和复杂链接：

https://stackoverflow.com/questions/6695439/how-to-link-to-a-named-anchor-in-multimarkdown#:~:text=In%20standard%20Markdown%2C%20place%20an,%5Blink% 20 文本%5D(%23abcd)%20。

score 0 · Accepted Answer

另一个在 Perl 之上实现的与 TOC 降价相关的工具（它始终随 Linux/Git-for-Windows 一起提供，并且可选地与 Cygwin 一起提供，并且不依赖于额外的包）

https://github.com/ildar-shaimordanov/git-markdown-toc

我猜我的工具的工作原理与上面其他人提到的 ekalinin/git-markdown-toc 相似或几乎相似。我从来没有比较过 tham，因为他的工具是作为 Go-Lang 实现的，而我的系统上不存在。我的脚本的主要目标是提供在本地创建 TOC 的良好解决方案——没有与任何外部主机等的任何连接，只读取本地文件（默认为 README.md）并创建 TOC 并将其嵌入到文件。

github - 如何在 GitHub wiki 中创建某种目录？

14 回答 14

视觉工作室代码

自动更新会弄乱您编辑的目录？

Wiki 目录

Related

Reference