使用Markdown创建页面和目录表？

Question

使用Markdown创建页面和目录表？

markdowntableofcontents

687

我开始使用Markdown来进行笔记。

我使用marked来查看我的Markdown笔记，效果很好。

但是随着我的笔记变得越来越长，我发现很难找到我想要的内容。

我知道Markdown可以创建表格，但它是否能够创建带有跳转到章节的目录或在Markdown中定义页面小节呢？

或者，是否有Markdown阅读器/编辑器可以实现这些功能。搜索也是一个很好的功能。

总之，我希望把它变成一个很棒的笔记工具，并像写书一样有很多功能。

- resting

@jonschlinkert你应该将其提交为答案！目前，回答中仅提供了一些非免费或Python的工具。选择范围不太理想。 - Domi

14

我需要提醒一下，在LaTeX中，这可以通过使用\tableofcontents实现。如果要重新发明轮子，最好复制其中的优秀部分。 - Eero Aaltonen

2

GitHub标记语言：https://dev59.com/ymkw5IYBdhLWcg3wrsjn - Ciro Santilli OurBigBook.com

同样，reStructuredText具有内置指令用于目录，最简单的形式只需写成.. contents::。 - saaj

41个回答

434

这里有一个有用的方法，可以在任何MarkDown编辑器中生成可点击的引用：

在每个标题的末尾添加一个空锚点，并选择一个名称 - 例如<a name="foo"></a>。
在文档开头，列出带有指向其锚点的链接的标题 - 例如[Foo](#foo)。

因此，这个：

# Table of contents
1. [Introduction](#introduction)
2. [Some paragraph](#paragraph1)
    1. [Sub paragraph](#subparagraph1)
3. [Another paragraph](#paragraph2)

## This is the introduction <a name="introduction"></a>
Some introduction text, formatted in heading 2 style

## Some paragraph <a name="paragraph1"></a>
The first paragraph text

### Sub paragraph <a name="subparagraph1"></a>
This is a sub paragraph, formatted in heading 3 style

## Another paragraph <a name="paragraph2"></a>
The second paragraph text

生成如下内容：

目录

介绍

某个段落

子段落

另一个段落

这是介绍

一些介绍文本，采用标题2样式格式化

某个段落

第一段文字

子段落

这是一个子段落，采用标题3样式格式化

另一个段落

第二段文字

- Tum

43

我喜欢将锚点标签放在标题上面的一行，这样当链接被点击时，标题会显示在页面上。 - mgarey

9

对我来说，这是唯一有用的。对于标题很长的情况，如果没有锚标签就无法进行。 - Matt Fletcher

2

@mgarey 只需先放置锚点：## <a name="foo" /> Foo - tobias_k

2

在Bitbucket中无法工作，因为它会将<a name="paragraph1"></a>显示为标题文本的一部分。 - Igor Brejc

14

在我的情况下，我需要使用“id”而不是“name”。 - Lucas Brito

显示剩余2条评论

163

对于Visual Studio Code用户，今天（2020）使用的最佳选项是Markdown All in One插件（扩展程序）。

要安装它，请启动VS Code快速打开（Control/⌘+P），粘贴以下命令，然后按Enter。

ext install yzhang.markdown-all-in-one

要生成目录，打开命令面板（Control/⌘+Shift+P），选择 Select Markdown: Create Table of Contents 选项。

另一个选择是Markdown TOC插件。

要安装它，请启动VS Code快速打开（Control/⌘+P），粘贴以下命令，然后按回车键。

ext install markdown-toc

要生成目录，打开命令面板 (Control/⌘+Shift+P)，选择 Markdown TOC:Insert/Update 选项或使用 Control/⌘+MT。

- valdeci

11

注意：我刚发现使用股票VSCode，您可以制作到标题的Markdown链接：[Section Foo](#foo-header-title)，它甚至在预览模式之外也适用（即在普通markdown中）。 - kitsu.eb

5

另一个替代 VSCode 的选择是 vscode-markdown，它拥有多个功能，包括目录（ToC）。 - Ciprian Tomoiagă

1

那个适用于Sublime Text的MarkdownTOC插件真是太棒了！我刚刚学会了如何使用它，并在我的答案中写了一些关于它的内容，链接在这里：https://dev59.com/aWct5IYBdhLWcg3wn-xz#64656967。它还可以在保存时自动更新，这太好了。我还展示了如何使目录可展开/折叠。 - Gabriel Staples

47

MultiMarkdown Composer 似乎会生成一个目录来帮助编辑。

也许还有其他库可以生成目录: 可以看看Python Markdown TOC 扩展。

- mxro

29

MultiMarkdown Composer 只能在 MacOS 上使用。 - chmike

2

Python Markdown 目录链接工作：https://python-markdown.github.io/extensions/toc/ - John

2

该应用程序在英国地区不可用。 - kenorb

TOC扩展程序生成HTML目录，而不是Markdown。值得注意的是，这很困难。 - rjurney

44

在您的Markdown文档中，有两种方法可以创建您的目录（摘要）。

1. 手动方式
# My Table of content - [Section 1](#id-section1) - [Section 2](#id-section2) <div id='id-section1'/> ## Section 1 <div id='id-section2'/> ## Section 2
2. 编程方式

你可以使用一个生成摘要的脚本，例如看一下我在github上的项目 - summarizeMD -

我也尝试过其他的脚本/npm模块（例如doctoc），但没有一个能够产生带有可用锚点的目录。

- Luca Davanzo

``<div id=...` 在 MarkdownPad2 (Windows) 中无法识别。 - chmike

仅适用于相同文件夹，对于setext标题也不起作用。 - gozzilli

31

你可以尝试使用这个 Ruby 脚本从 markdown 文件中生成目录。

 #!/usr/bin/env ruby

require 'uri'

fileName = ARGV[0]
fileName = "README.md" if !fileName

File.open(fileName, 'r') do |f|
  inside_code_snippet = false
  f.each_line do |line|
    forbidden_words = ['Table of contents', 'define', 'pragma']
    inside_code_snippet = !inside_code_snippet if line.start_with?('```')
    next if !line.start_with?("#") || forbidden_words.any? { |w| line =~ /#{w}/ } || inside_code_snippet

    title = line.gsub("#", "").strip
    href = URI::encode title.gsub(" ", "-").downcase
    puts "  " * (line.count("#")-1) + "* [#{title}](\##{href})"
  end
end

- albertodebortoli

太好了！只是想提醒一下，可能需要将ifndef、include和endif等预处理器指令添加到禁用单词列表中。此外，将列表定义在循环范围之外可以避免在每次迭代时重新实例化它。此外，这将捕获任何使用#注释语法的语言（包括Ruby）的注释，这不是很好。如果您愿意，我可以进行编辑。但是这是一个很好的开始，并且对我的目的很有效。非常感谢！ - Jeff Klein

1

这仅适用于atx标题（即以“＃”开头的标题），而不适用于setext标题（下划线）。 - gozzilli

谢谢您的使用。如果您在Rails上使用Redcarpet，建议使用 title.parameterize 作为 href。谢谢！ - Alexis

如果你收到了很多警告，提示URI.escape已过时，请将URI::encode更改为URI::encode_www_form_component。 - digitalronin

29

# Table of Contents
1. [Example](#example)
2. [Example2](#example2)
3. [Third Example](#third-example)

## Example [](#){name=example}
## Example2 [](#){name=example2}
## [Third Example](#){name=third-example}

如果您使用markdown extra，请不要忘记可以为链接、标题、代码框和图像添加特殊属性。https://michelf.ca/projects/php-markdown/extra/#spe-attr

- Greg Bosen

24

你还可以使用 pandoc，它是将一种标记格式转换为另一种的"瑞士军刀"。如果你提供了--toc参数，它可以自动生成输出文档中的目录。

提示： --toc需要使用-s（生成独立文档），否则不会生成目录。

示例shell命令行：

./pandoc -s --toc input.md -o output.md

- M. Geiger

2

谢谢。这对我有用。我需要将输出保存为Markdown文件。所以使用了以下命令：pandoc -s --toc input.md -o input_toc.md [请注意确保输出文件名与输入文件名不同] - Sarfraaz Ahmed

22

如其他答案所提到的，有多种方法可以自动生成目录。大多数都是开源软件，可以根据您的需求进行调整。

然而，我所缺少的是一种在使用Markdown提供的有限选项时表现出视觉吸引力的目录格式。我们想到了以下的解决方案：

代码

## Content

**[1. Markdown](#heading--1)**

  * [1.1. Markdown formatting cheatsheet](#heading--1-1)
  * [1.2. Markdown formatting details](#heading--1-2)

**[2. BBCode formatting](#heading--2)**

  * [2.1. Basic text formatting](#heading--2-1)

      * [2.1.1. Not so basic text formatting](#heading--2-1-1)

  * [2.2. Lists, Images, Code](#heading--2-2)
  * [2.3. Special features](#heading--2-3)

----

在您的文档内，您将会像这样放置目标子部分标记：

<div id="heading--1-1"/>
### 1.1. Markdown formatting cheatsheet

根据您使用Markdown的位置和方式，以下内容也应该有效，并提供更美观的Markdown代码：

### 1.1. Markdown formatting cheatsheet <a name="heading--1-1"/>

示例呈现

内容

1. Markdown

1.1. Markdown格式快速参考表

1.2. Markdown格式详细说明

2. BBCode格式

2.1. 基本文本格式

2.1.1. 不太基本的文本格式

2.2. 列表、图片、代码

2.3. 特殊功能

优点

您可以添加任意多级章节和子章节。在目录中，这些将显示为嵌套的无序列表。
不使用有序列表。这将创建缩进，不会链接数字，并且不能用于创建类似于“1.1.”的十进制分类编号。
第一级不使用列表。在此处，可以使用无序列表，但不是必需的：缩进和符号只会增加视觉杂乱而没有实际作用，因此我们根本不使用列表来表示第一级目录。
通过粗体打印在目录中突出显示第一级部分。
短小、有意义的子部分标记在浏览器的URL栏中看起来“美观”，例如#heading--1-1，而不是包含实际标题转换片段的标记。
代码使用H2标题(## …)表示章节，使用H3标题(### …)表示子标题等。这使得源代码更易于阅读，因为与章节以H1标题(# …)开头的情况相比，## …提供了更强的视觉线索。它仍然在逻辑上是一致的，因为您使用H1标题表示文档标题本身。
最后，在目录和实际内容之间添加一个漂亮的水平线。

关于这种技术及我们如何在论坛软件Discourse中使用它的更多信息，请点击此处，或在这里查看。

- tanius

21

不同的Markdown解析器生成的锚点标签并不相同。

如果您正在使用Markdown解析器GFM（GitHub Flavored Markdown）或Redcarpet，我编写了一个Vim插件来处理目录。

功能

为Markdown文件生成目录。

支持的Markdown解析器：
- GFM（GitHub Flavored Markdown）
- Redcarpet
更新现有目录。
在保存时自动更新现有目录。

截图

vim-markdown-toc

用法

生成目录

将光标移动到您要添加目录的行，然后键入适合您的以下命令。该命令将在光标之后生成标题以形成目录。

:GenTocGFM

以GFM链接样式生成目录。

此命令适用于GitHub存储库中的Markdown文件，例如README.md，以及用于GitBook的Markdown文件。
:GenTocRedcarpet

以Redcarpet链接样式生成目录。

此命令适用于Jekyll或任何其他使用Redcarpet作为其Markdown解析器的地方。

您可以查看此处了解GFM和Redcarpet样式toc链接之间的差异。

手动更新现有目录

通常情况下，您无需执行此操作，现有目录将默认自动在保存时更新。如果要手动更新它，请使用:UpdateToc命令。

下载和文档

https://github.com/mzlogin/vim-markdown-toc

这是一个关于vim下markdown文档的目录生成插件，它能够让你在编辑markdown文件时，自动地为文档生成目录，并且支持多种不同的样式。

- Zhuang Ma

很好。如果围栏没有明确提到“vim”就更好了。这样，您的围栏标记就可以演变成某些支持TOC的Markdown风格的一部分。 - chtenb

@ChieltenBrinke 您可以使用选项 g:vmt_fence_text 和 g:vmt_fence_closing_text 来自定义围栏标记。 - Zhuang Ma

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

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

- Rick · Accepted Answer

683

你可以试一试。

# Table of Contents
1. [Example](#example)
2. [Example2](#example2)
3. [Third Example](#third-example)
4. [Fourth Example](#fourth-examplehttpwwwfourthexamplecom)


## Example
## Example2
## Third Example
## [Fourth Example](http://www.fourthexample.com)

- Rick

32

以上第三个例子无效。至今为止，这是我能够使其吞噬空格的唯一方式。在你的代码片段中，第三个标签无疑会被解释为“#Third”后跟一个空格，然后是单词“Example”吧？连字符根本不起作用。谢谢。 - twobob

#third_example 在我的 Markdown 实现中（Cryogen）可以正常工作。 - user2609980

11

在RStudio中运作良好。只想补充一点，德语语音符号如ü需要在锚点中不带语音符号地书写，即 1. [Einführung](#einfuhrung)。 - steinbock

11

Bitbucket v4.5.2中的标题并不会自动创建锚点。 - Mike Rylander

1

第四个示例就是我要找的。谢谢！ - kenecaswell

显示剩余5条评论