Markdown 创建页面和目录？

您可以尝试 this ruby script 从降价文件生成目录。

 #!/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

---

# 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，请不要忘记您可以为链接、标题、代码围栏和图像添加特殊属性。
https://michelf.ca/projects/php-markdown/extra/#spe-attr

---

不同 Markdown 解析器生成的锚标签是不均匀的。

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

特征

为 Markdown 文件生成目录。支持的 Markdown 解析器：GFM (GitHub Flavored Markdown) Redcarpet 更新现有目录。保存时自动更新现有目录。

截图

https://raw.githubusercontent.com/mzlogin/vim-markdown-toc/master/screenshots/english.gif

用法

生成目录

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

:GenTocGFM 以 GFM 链接样式生成目录。此命令适用于 GitHub 存储库中的 Markdown 文件，例如 README.md，以及 GitBook 的 Markdown 文件。 :GenTocRedcarpet 以 Redcarpet 链接样式生成目录。此命令适用于 Jekyll 或其他任何使用 Redcarpet 作为其 Markdown 解析器的地方。您可以在此处查看以了解 GFM 和 Redcarpet 样式目录链接之间的区别。

手动更新现有目录

通常你不需要这样做，现有的目录默认会在保存时自动更新。如果您想手动操作，只需使用 :UpdateToc 命令。

下载和文件

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

---

您也可以使用 pandoc，即 "swiss-army knife" for converting "one markup format into another"。如果您提供 --toc 参数，它可以在输出文档中自动生成目录。

提示：如果您想在 html 输出中提供目录，您还需要提供 -s 以生成独立文档。

示例 shell 命令行：

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

---

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

然而，我缺少的是使用 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.”这样的十进制分类编号。

第一级不使用列表。在这里，使用无序列表是可能的，但不是必需的：缩进和项目符号只是增加了视觉上的混乱，在这里没有任何功能，所以我们根本不使用第一个 ToC 级别的列表。

用粗体字突出目录中的第一级部分。

简短、有意义的子部分标记，在浏览器的 URL 栏中看起来“漂亮”，例如 #heading--1-1，而不是包含实际标题转换片段的标记。

该代码使用 H2 标题 (## ...) 表示部分，使用 H3 标题 (### ...) 表示子标题等。这使得源代码更易于阅读，因为与部分以 H1 标题 (# …) 开头的情况。当您使用 H1 标题作为文档标题本身时，它在逻辑上仍然是一致的。

最后，我们添加了一个很好的水平规则来将目录与实际内容分开。

有关此技术以及我们如何在论坛软件 Discourse、see here 中使用它的更多信息。

---

在 Gitlab 上，markdown 支持这一点：[[_TOC_]]

---

在 Visual Studio Code (VSCode) 中，您可以使用扩展程序 Markdown All in One。

安装后，请按照以下步骤操作：

按 CTRL+SHIFT+P 选择 Markdown：创建目录

编辑：现在我使用 DocToc 生成目录，有关详细信息，请参阅 my other answer。

---

作为手工制作链接列表的替代方案，让我们概述所有可用的开箱即用解决方案以插入目录（请评论并扩展以保持最新）：

在 Gollum v5 中，markdown 支持这一点：

<!-- assure you have a blank line before -->
[[_TOC_]]

这也适用于 Azure DevOps wiki。

由于 Gitlab 切换了 from Redcarpet to Kramdown as markdown engine，它们现在支持以下语法

- TOC
{:toc}

见https://about.gitlab.com/handbook/markdown-guide/#table-of-contents-toc

MultiMarkdown as of 4.7 具有以下宏：

{{TOC}}

根据 Jannik's answer：
如果要在 bitbucket.org 上的存储库中显示您的 Markdown 文件，您可以在您想要目录的位置使用以下内容（更多信息here):

[TOC]

根据 Paul Jurczak's aswer：
Markdown 编辑器Typora 还会在您在文档中写入 [TOC] 时生成目录。

我知道，我这个答案有点晚了。但是，我自己错过了这样的概述。我的 Edit of Nicolas Thery's answer 将其扩展到概述被拒绝了。

---

为了我们这些在 Atom 中制作 README.md 文件的人的利益（我是如何找到这个线程的）：

apm install markdown-toc

https://atom.io/packages/markdown-toc

---

您可以使用这个 bash one-liner 来生成它。假设您的降价文件名为 FILE.md。

echo "## Contents" ; echo ; 
cat FILE.md | grep '^## ' | grep -v Contents | sed 's/^## //' | 
  while read -r title ; do 
    link=$(echo $title | tr 'A-Z ' 'a-z-') ; 
    echo "- [$title](#$link)" ; 
    done

---

如果您想使用 javascript/node.js 工具，请查看 markdown-toc。

---

我刚刚为 python-markdown 编写了一个扩展，它使用它的解析器来检索标题，并将一个 TOC 输出为带有本地链接的 Markdown 格式的无序列表。该文件是

md_toc.py（原为 md_toc.py）

...它应该放在markdown安装的markdown/extensions/目录中。然后，您所要做的就是键入带有 id="..." 属性的锚 <a> 标记作为参考 - 所以对于这样的输入文本：

$ cat test.md 
Hello
=====

## <a id="sect one"></a>SECTION ONE ##

something here

### <a id='sect two'>eh</a>SECTION TWO ###

something else

#### SECTION THREE

nothing here

### <a id="four"></a>SECTION FOUR

also...

...扩展名可以这样调用：

$ python -m markdown -x md_toc test.md 
* Hello
    * [SECTION ONE](#sect one)
        * [SECTION TWO](#sect two)
            * SECTION THREE
        * [SECTION FOUR](#four)

...然后您可以将此目录粘贴回您的降价文档中（或在您的文本编辑器中有一个快捷方式，调用当前打开的文档上的脚本，然后将生成的目录插入同一文档中）。

请注意，旧版本的 python-markdown 没有 __main__.py 模块，因此，上述命令行调用不适用于这些版本。

---

Typora 通过将 [TOC] 添加到您的文档来生成目录。

---

如果使用 Sublime Text 编辑器，MarkdownTOC 插件效果很好！看：

https://packagecontrol.io/packages/MarkdownTOC https://github.com/naokazuzerada/MarkdownTOC

安装后，转到首选项-->包设置 --> MarkdownTOC -->设置——用户，自定义您的设置。以下是您可以选择的选项：https://github.com/naokazuterada/MarkdownTOC#configuration。

我推荐以下内容：

{
  "defaults": {
    "autoanchor": true,
    "autolink": true,
    "bracket": "round",
    "levels": [1,2,3,4,5,6],
    "indent": "\t",
    "remove_image": true,
    "link_prefix": "",
    "bullets": ["-"],
    "lowercase": "only_ascii",
    "style": "ordered",
    "uri_encoding": true,
    "markdown_preview": ""
  },
  "id_replacements": [
    {
      "pattern": "\\s+",
      "replacement": "-"
    },
    {
      "pattern": "&lt;|&gt;|&amp;|&apos;|&quot;|&#60;|&#62;|&#38;|&#39;|&#34;|!|#|$|&|'|\\(|\\)|\\*|\\+|,|/|:|;|=|\\?|@|\\[|\\]|`|\"|\\.|\\\\|<|>|{|}|™|®|©|%",
      "replacement": ""
    }
  ],
  "logging": false
}

要插入目录，只需单击文档顶部要插入目录的位置，然后转到工具 --> Markdown TOC --> 插入目录。

它将插入如下内容：

<!-- MarkdownTOC -->

1. [Helpful Links:](#helpful-links)
1. [Sublime Text Settings:](#sublime-text-settings)
1. [Packages to install](#packages-to-install)

<!-- /MarkdownTOC -->

请注意它为您插入的 <!-- --> HTML 注释。这些是特殊标记，可帮助程序了解 ToC 的位置，以便每次保存时它都会自动为您更新！因此，请保持这些原样。

要获得额外的花哨，请在其周围添加一些 <details> 和 <summary> HTML 标签以使 ToC 可折叠/可展开，如下所示：

<details>
<summary><b>Table of Contents</b> (click to open)</summary>
<!-- MarkdownTOC -->

1. [Helpful Links:](#helpful-links)
1. [Sublime Text Settings:](#sublime-text-settings)
1. [Packages to install](#packages-to-install)

<!-- /MarkdownTOC -->
</details>

现在，你得到了这个超酷的效果，如下图所示。在我的 main eRCaGuy_dotfiles readme here 或我的 Sublime_Text_editor readme here 中查看它的实际效果。

折叠：展开：

有关其用法和限制的更多信息，请务必阅读我在 that readme 中关于 MarkdownTOC 插件的说明。

---

我编写了一个解析markdown文件并将目录输出为markdown列表的python脚本：md-to-toc

与我发现的其他脚本不同，md-to-toc 正确支持重复标题。它也不需要互联网连接，因此它适用于任何 md 文件，而不仅仅是那些可从公共 repo 获得的文件。

---

只需使用带有插件的文本编辑器即可。

您的编辑器很可能有一个 package/plugin 来为您处理这个问题。例如，在 Emacs 中，您可以安装 markdown-toc TOC 生成器。然后在您编辑时，只需重复调用 M-x markdown-toc-generate-or-refresh-toc。如果您想经常这样做，那值得一键绑定。它擅长生成简单的 TOC，而不会用 HTML 锚污染您的文档。

其他编辑器也有类似的插件，所以流行的列表是这样的：

Emacs：降价目录

Vim: 降价目录

原子：markdown-toc

VSCode：降价目录

---

我刚开始做同样的事情（在 Markdown 中做笔记）。我使用带有 MarkdownPreview plugin 的 Sublime Text 2。内置的 markdown 解析器支持 [TOC]。

---

如果要在 bitbucket.org 上的存储库中显示您的 Markdown 文件，您应该在您想要目录的位置添加 [TOC]。然后它将自动生成。更多信息在这里：

https://confluence.atlassian.com/bitbucket/add-a-table-of-contents-to-a-wiki-221451163.html

---

我不确定，markdown 的官方文档是什么。交叉引用可以只写在方括号 [Heading] 中，也可以写在空方括号 [Heading][] 中。

两者都使用 pandoc。所以我创建了一个快速的 bash 脚本，它将 md 文件中的 $__TOC__ 替换为其 TOC。 （您将需要 envsubst，这可能不是您的发行版的一部分）

#!/bin/bash
filename=$1
__TOC__=$(grep "^##" $filename | sed -e 's/ /1. /;s/^##//;s/#/   /g;s/\. \(.*\)$/. [\1][]/')
export __TOC__
envsubst '$__TOC__' < $filename

---

这是一个用于生成目录的简单 bash 脚本。不需要特殊的依赖项，但需要 bash。

https://github.com/Lirt/markdown-toc-bash

它可以很好地处理标题中的特殊符号、标题中的降价链接并忽略代码块。

---

基于 albertodebortoli 答案创建了具有附加检查和替换标点符号的功能。

# @fn       def generate_table_of_contents markdown # {{{
# @brief    Generates table of contents for given markdown text
#
# @param    [String]  markdown Markdown string e.g. File.read('README.md')
#
# @return   [String]  Table of content in markdown format.
#
def generate_table_of_contents markdown
  table_of_contents = ""
  i_section = 0
  # to track markdown code sections, because e.g. ruby comments also start with #
  inside_code_section = false
  markdown.each_line do |line|
    inside_code_section = !inside_code_section if line.start_with?('```')

    forbidden_words = ['Table of contents', 'define', 'pragma']
    next if !line.start_with?('#') || inside_code_section || forbidden_words.any? { |w| line =~ /#{w}/ }

    title = line.gsub("#", "").strip
    href = title.gsub(/(^[!.?:\(\)]+|[!.?:\(\)]+$)/, '').gsub(/[!.,?:; \(\)-]+/, "-").downcase

    bullet = line.count("#") > 1 ? " *" : "#{i_section += 1}."
    table_of_contents << "  " * (line.count("#") - 1) + "#{bullet} [#{title}](\##{href})\n"
  end
  table_of_contents
end

---

MultiMarkdown 4.7 有一个用于插入目录的 {{TOC}} 宏。

---

对我来说，@Tum 提出的解决方案就像一个有 2 个级别的目录的魅力。但是，对于第 3 级，它不起作用。它没有像前 2 个级别那样显示链接，而是显示纯文本 3.5.1. [bla bla bla](#blablabla) <br>。

我的解决方案是对@Tum 解决方案（非常简单）的补充，适用于需要 3 级或更多级目录的人。

在第二层，一个简单的制表符将为您正确缩进。但它不支持 2 个选项卡。相反，您必须使用一个选项卡并根据需要自己添加尽可能多的   才能正确对齐第 3 级。

这是一个使用 4 个级别的示例（级别越高，越糟糕）：

# Table of Contents
1. [Title](#title) <br>
    1.1. [sub-title](#sub_title) <br>
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;1.1.1. [sub-sub-title](#sub_sub_title)
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;1.1.1.1. [sub-sub-sub-title](#sub_sub_sub_title)

# Title <a name="title"></a>
Heading 1

## Sub-Title <a name="sub_title"></a>
Heading 2

### Sub-Sub-Title <a name="sub_sub_title"></a>
Heading 3

#### Sub-Sub-Sub-Title <a name="sub_sub_sub_title"></a>
Heading 4

这给出了以下结果，其中目录的每个元素都是指向其相应部分的链接。另请注意 <br> 以便添加新行而不是在同一行上。

目录

标题 1.1。小标题 1.1.1。子标题 1.1.1.1。子子子标题

标题

标题 1

字幕

标题 2

子子标题

标题 3

标题 4

---

有一个名为 mdtoc.rb 的 Ruby 脚本可以自动生成 GFM Markdown 目录，它与此处发布的其他一些脚本相似但略有不同。

给定一个输入 Markdown 文件，例如：

# Lorem Ipsum

Lorem ipsum dolor sit amet, mei alienum adipiscing te, has no possit delicata. Te nominavi suavitate sed, quis alia cum no, has an malis dictas explicari. At mel nonumes eloquentiam, eos ea dicat nullam. Sed eirmod gubergren scripserit ne, mei timeam nonumes te. Qui ut tale sonet consul, vix integre oportere an. Duis ullum at ius.

## Et cum

Et cum affert dolorem habemus. Sale malis at mel. Te pri copiosae hendrerit. Cu nec agam iracundia necessitatibus, tibique corpora adipisci qui cu. Et vix causae consetetur deterruisset, ius ea inermis quaerendum.

### His ut

His ut feugait consectetuer, id mollis nominati has, in usu insolens tractatos. Nemore viderer torquatos qui ei, corpora adipiscing ex nec. Debet vivendum ne nec, ipsum zril choro ex sed. Doming probatus euripidis vim cu, habeo apeirian et nec. Ludus pertinacia an pro, in accusam menandri reformidans nam, sed in tantas semper impedit.

### Doctus voluptua

Doctus voluptua his eu, cu ius mazim invidunt incorrupte. Ad maiorum sensibus mea. Eius posse sonet no vim, te paulo postulant salutatus ius, augue persequeris eum cu. Pro omnesque salutandi evertitur ea, an mea fugit gloriatur. Pro ne menandri intellegam, in vis clita recusabo sensibus. Usu atqui scaevola an.

## Id scripta

Id scripta alterum pri, nam audiam labitur reprehendunt at. No alia putent est. Eos diam bonorum oportere ad. Sit ad admodum constituto, vide democritum id eum. Ex singulis laboramus vis, ius no minim libris deleniti, euismod sadipscing vix id.

它生成这个目录：

$ mdtoc.rb FILE.md 
#### Table of contents

1. [Et cum](#et-cum)
    * [His ut](#his-ut)
    * [Doctus voluptua](#doctus-voluptua)
2. [Id scripta](#id-scripta)

另请参阅我关于此主题的博客 post。

---

您可以使用 DocToc 从命令行生成目录：

doctoc /path/to/file

要使链接与 Bitbucket 生成的锚点兼容，请使用 --bitbucket 参数运行它。

---