thlorenz/doctoc

「 生成，markdown 文件(*.md)的超链接目录 」

中文 | english

---

校对 ✅

翻译的原文	与日期	最新更新	更多
commit	⏰ 2018-11-21		中文翻译

贡献

欢迎 👏 勘误/校对/更新贡献 😊 具体贡献请看

生活

If help, buy me coffee —— 营养跟不上了，给我来瓶营养快线吧! 💰

---

DocToc

生成，markdown 文件(*.md)的超链接目录

Contents

• 安装
• 用法
  • 将 TOC 添加到目录和子目录中的所有文件
  • 毫不费力地更新现有的 Doctoc TOCs
  • 将 TOC 添加到单个文件中
  • 使用 Doctoc 生成与其他站点兼容的超链接
  • 指定 TOC 的位置
  • 指定自定义 TOC 标题
  • 指定 TOC 条目的最大 heading 级别
  • 打印到标准输出
  • 作为一个git钩子来使用

安装

npm install -g doctoc

用法

在最简单的用法中，一个或多个文件，或文件夹使用doctoc命令。这会更新每个指定(md)文件的 TOC(超链接目录)。下面是一些例子.

将 TOC 添加到目录和子目录中的所有文件

进入目录:

doctoc .

这将用 md 解析器，生成标点(#)超链接的目录表，更新当前目录及其所有子目录中的所有 md 文件。Doctoc 默认使用 Github 解析器,但可以可以指定其他模式.

毫不费力地更新现有的 Doctoc TOCs

如果您已经通过 doctoc 插入了 TOC 注释，那么它将通过运行命令(而不是插入重复的 toc)自动更新。Doctoc 通过

• <!-- START doctoc -->和
• <!-- END doctoc -->注释

定位 TOC，因此您还可以将生成的 TOC 移动到文档的任何其他部分。

将 TOC 添加到单个文件中

如果希望只转换特定的文件,请执行:

doctoc /path/to/file [...]

实例

doctoc README.md

doctoc CONTRIBUTING.md LICENSE.md

你可以使用这个特性来做更复杂的事情.例如,如果你安装ack,您可以添加<!-- Doctoc SKIP -->到特定文件， 然后使用

ack -L 'Doctoc SKIP' | xargs doctoc

这命令只会重新编译那些没有<!-- Doctoc SKIP -->的文件.

使用 Doctoc 生成与其他站点兼容的超链接

为了添加，兼容的超链接目录表,可添加其他站点的适当参数:

可用模式是:

--bitbucket bitbucket.org
--nodejs    nodejs.org
--github    github.com
--gitlab    gitlab.com
--ghost     ghost.org

例子

doctoc README.md --bitbucket

指定 TOC 的位置

默认情况下,Doctoc 将 TOC 置于文件的顶部。可用以下格式放置在别处:

<!-- START doctoc -->
<!-- END doctoc -->

将此代码直接放在 .md文件中.例如:

// my_new_post.md
Here we are, introducing the post. It's going to be great!
But first: a TOC for easy reference.

<!-- START doctoc -->
<!-- END doctoc -->

# Section One

Here we'll discuss...

运行 Doctoc 将在注释之间的位置插入 TOC.

指定自定义 TOC 标题

使用--title选项指定一个(markdown 格式的)自定义 TOC 标题;doctoc --title '**Contents**' . 。从此,你可以简单doctoc <file>，就让 Doctoc 保留您指定的标题。(正如这个 readme 文件)

或者,你通过使用--notitle选项，用换行符将标题省略。简单地从 TOC 中删除标题.

指定 TOC 条目的最大 heading 级别

如 # == 1, ## == 2 ...

使用--maxlevel将 TOC 项 限制为指定级别;

• doctoc --maxlevel 3 . (比如该 readme 的#### 实例并没有超链接)

默认情况下,

• 没有限制标题,
• 而来自嵌入式 HTML 的标题(heading)限于 第 4 级.

打印到标准输出

您可以使用-s或--stdout选项。

作为一个git钩子来使用

把 Doctoc 作为一个pre-commit钩子来使用，以下配置:

repos:
  - repo: https://github.com/thlorenz/doctoc
    sha: ... # substitute a tagged version
    hooks:
      - id: doctoc

这将在 git commit 文件时，运行doctoc,确保 TOC 保持最新.