# @effect/markdown-toc 中文文档

规范地址：https://npmcn.com/package/%40effect/markdown-toc/

版本：0\.1\.0
npm 元数据更新时间：2026-09-18T21:17:36.918Z
中文译文更新时间：2026-11-13T08:25:37.640Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40effect/markdown-toc
原文对照：https://npmcn.com/package/%40effect/markdown-toc/?lang=original
项目主页：https://github.com/jonschlinkert/markdown-toc
源码仓库：https://github.com/jonschlinkert/markdown-toc

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：30.5 kB，7 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>=0\.10\.0
- 运行依赖：12 个
- 首次发布：2024-04-10T21:17:46.179Z
- 最新版本发布：2024-04-10T21:17:46.468Z
- 近 30 天下载量：95267（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：1（近 12 个月 0 个）

## 中文简介

生成可标记的 TOC(目录) .

## 安装

```sh
npm install @effect/markdown-toc
```

也可以使用：`pnpm add @effect/markdown-toc`、`yarn add @effect/markdown-toc`、`bun add @effect/markdown-toc`

## README

# 页:1 [![NPM version](https://img.shields.io/npm/v/markdown-toc.svg?style=flat)](https://www.npmjs.com/package/markdown-toc) [![NPM monthly downloads](https://img.shields.io/npm/dm/markdown-toc.svg?style=flat)](https://npmjs.org/package/markdown-toc) [![NPM total downloads](https://img.shields.io/npm/dt/markdown-toc.svg?style=flat)](https://npmjs.org/package/markdown-toc)

> 生成可标记的 TOC(目录) .

请考虑跟随这个项目的作者, [乔恩·斯林克特](https://github.com/jonschlinkert),并考虑主演该项目以显示你的:心:和支持.

-   [要点](https://npmcn.com/package/%40effect/markdown-toc/#readme-highlights)
-   [使用量](https://npmcn.com/package/%40effect/markdown-toc/#readme-usage)
-   [API 密码](https://npmcn.com/package/%40effect/markdown-toc/#readme-api)
    -   [托克插剂](https://npmcn.com/package/%40effect/markdown-toc/#readme-tocplugin)
    -   [托克·杰森(签名)](https://npmcn.com/package/%40effect/markdown-toc/#readme-tocjson)
    -   [输入](https://npmcn.com/package/%40effect/markdown-toc/#readme-tocinsert)
    -   [工具函数](https://npmcn.com/package/%40effect/markdown-toc/#readme-utility-functions)
-   [选项](https://npmcn.com/package/%40effect/markdown-toc/#readme-options)
    -   [选项](https://npmcn.com/package/%40effect/markdown-toc/#readme-optionsappend)
    -   [选项。 过滤器](https://npmcn.com/package/%40effect/markdown-toc/#readme-optionsfilter)
    -   [选项](https://npmcn.com/package/%40effect/markdown-toc/#readme-optionsslugify)
    -   [选项。 子弹](https://npmcn.com/package/%40effect/markdown-toc/#readme-optionsbullets)
    -   [选项。最大深度](https://npmcn.com/package/%40effect/markdown-toc/#readme-optionsmaxdepth)
    -   [选项](https://npmcn.com/package/%40effect/markdown-toc/#readme-optionsfirsth1)
    -   [选项。字符串标题标签](https://npmcn.com/package/%40effect/markdown-toc/#readme-optionsstripheadingtags)
-   [关于](https://npmcn.com/package/%40effect/markdown-toc/#readme-about)

_(技术选择委员会生成的 [动词](https://github.com/verbose/verb) 使用 [页:1](https://github.com/jonschlinkert/markdown-toc)(中文(简体) )_

## 安装

安装方式 [无](https://www.npmjs.com/)数字 :

```sh
$ npm install --save markdown-toc
```

# 发起人

感谢下列公司、组织和个人支持持续维持和发展减记托克! [成为发起人](https://github.com/sponsors/jonschlinkert) 将您的标志添加到此 README 或任何 [我的其他项目](https://github.com/jonschlinkert?tab=repositories&q=&type=&language=&sort=stargazers)

## 黄金赞助商

| [![https://jaake.tech/](https://github.com/jonschlinkert/clone-deep/assets/383994/98036489-2cae-48a2-8d29-7dec58ea05c4)](https://jaake.tech/) |
| --- |
| [https://jaake.tech/ (英语)](https://jaake.tech/) |

  

## 快速启动

假设您要在 README.md 中添加 TOC :

1.  `$ npm install -g markdown-toc`
2.  编辑 README.md 并在您想要插入 TOC 的地方插入下行 :  
    `<!-- toc -->`
3.  `$ markdown-toc -i README.md`

## 国 际

```
Usage: markdown-toc [options] <input>

  input:        The Markdown file to parse for table of contents,
                or "-" to read from stdin.

  -i:           Edit the <input> file directly, injecting the TOC at - [Highlights](#highlights)
- [Usage](#usage)
- [API](#api)
  * [toc.plugin](#tocplugin)
  * [toc.json](#tocjson)
  * [toc.insert](#tocinsert)
  * [Utility functions](#utility-functions)
- [Options](#options)
  * [options.append](#optionsappend)
  * [options.filter](#optionsfilter)
  * [options.slugify](#optionsslugify)
  * [options.bullets](#optionsbullets)
  * [options.maxdepth](#optionsmaxdepth)
  * [options.firsth1](#optionsfirsth1)
  * [options.stripHeadingTags](#optionsstripheadingtags)
- [About](#about)

_(TOC generated by [verb](https://github.com/verbose/verb) using [markdown-toc](https://github.com/jonschlinkert/markdown-toc))_;
                (Without this flag, the default is to print the TOC to stdout.)

  --json:       Print the TOC in JSON format

  --append:     Append a string to the end of the TOC

  --bullets:    Bullets to use for items in the generated TOC
                (Supports multiple bullets: --bullets "*" --bullets "-" --bullets "+")
                (Default is "*".)

  --maxdepth:   Use headings whose depth is at most maxdepth
                (Default is 6.)

  --no-firsth1: Include the first h1-level heading in a file

  --no-stripHeadingTags: Do not strip extraneous HTML tags from heading
                         text before slugifying

  --indent:     Provide the indentation to use - defaults to '  '
                (to specify a tab, use the bash-escaped $'\t')
```

## 要点

**特征**

-   可选择用作 [显著](https://github.com/jonschlinkert/remarkable) 插件
-   与制成的 TOC 返回对象( 在 `content`(a) 以及a `json` 带有原始 TOC 对象的属性,所以您可以使用模板或任意生成自己的 TOC
-   与 [重复标题](https://gist.github.com/jonschlinkert/ac5d8122bfaaa394f896)
-   使用理智默认,所以不需要定制,但需要时可以.
-   [过滤器](https://npmcn.com/package/%40effect/markdown-toc/#readme-filter-headings) 退出标题
-   [改进](https://npmcn.com/package/%40effect/markdown-toc/#readme-titleize) 您想要的标题
-   使用自定义 [拼写](https://npmcn.com/package/%40effect/markdown-toc/#readme-optionsslugify) 函数以改变链接的创建方式

**安全无虞!**

-   在 gfm 代码块中的代码示例中, 不会将标记下移到其它 TOC 生成器错误为实际标题的代码块中( 当标记下移标题显示于 _实例_意思是,它们实际上不是标题 应该是在toc。 也会发生在 yaml 和咖啡标注的评论, 或任何使用 `#`(中文(简体) )
-   将不会像其他 TOC 生成器一样处理前题或错误前题属性

## 使用量

```js
var toc = require('markdown-toc');

toc('# One\n\n# Two').content;
// Results in:
// - [One](#one)
// - [Two](#two)
```

为了允许对输出进行定制,一个对象的返回具有以下属性:

-   `content` **{string}(string ) , \[ 弦叫 \]**: 生成的目录. 除非你想自定义渲染, 这就是你所需要的.
-   `highest` **{数目}**: 找到的最高水平标题 。 此用于调整缩进 .
-   `tokens` **{箭头}**: 可用于自定义渲染的标题符号

## API 密码

### 托克插剂

用作一个 [显著](https://github.com/jonschlinkert/remarkable) 插件 .

```js
var Remarkable = require('remarkable');
var toc = require('markdown-toc');

function render(str, options) {
  return new Remarkable()
    .use(toc.plugin(options)) // <= register the plugin
    .render(str);
}
```

**用法实例**

```js
var results = render('# AAA\n# BBB\n# CCC\nfoo\nbar\nbaz');
```

成果:

```
- [AAA](#aaa)
- [BBB](#bbb)
- [CCC](#ccc)
```

### 托克·杰森(签名)

创建自定义 TOC 对象 .

```js
toc('# AAA\n## BBB\n### CCC\nfoo').json;

// results in
[ { content: 'AAA', slug: 'aaa', lvl: 1 },
  { content: 'BBB', slug: 'bbb', lvl: 2 },
  { content: 'CCC', slug: 'ccc', lvl: 3 } ]
```

### 输入

紧接后插入目录 _打开_ `<!-- toc -->` 代码注释,或如果两者兼有,则替换现有的 TOC _打开_ 评论和a _结束_ 评论意见(`<!-- tocstop -->`已找到.

_(这一策略效果良好,因为下标中的代码注释在被看做HTML时被隐藏起来,比如在GitHub README上查看一个README时._

**示例**

```
<!-- toc -->
- old toc 1
- old toc 2
- old toc 3
<!-- tocstop -->

## abc
This is a b c.

## xyz
This is x y z.
```

会导致一些类似的东西:

```
<!-- toc -->
- [abc](#abc)
- [xyz](#xyz)
<!-- tocstop -->

## abc
This is a b c.

## xyz
This is x y z.
```

### 工具函数

为了方便想要创建定制TOC的人

```js
var toc = require('markdown-toc');
```

-   `toc.bullets()`: 从一系列符号中制取出一个圆形列表
-   `toc.linkify()`: 链接标题 `content` 字符串
-   `toc.slugify()`: 打字头 `content` 字符串
-   `toc.strip()`: 从标题上取出单词或字符 `content` 字符串

**示例**

```js
var result = toc('# AAA\n## BBB\n### CCC\nfoo');
var str = '';

result.json.forEach(function(heading) {
  str += toc.linkify(heading.content);
});
```

## 选项

### 选项

将字符串附加到 TOC 的末尾 .

```js
toc(str, {append: '\n_(TOC generated by Verb)_'});
```

### 选项。 过滤器

类型 : `Function`

默认 : `undefined`

参数 :

-   `str` **{string}(string ) , \[ 弦叫 \]** 实际标题字符串
-   `ele` **{\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}你觉得呢** 标题符号对象
-   `arr` **{箭头}** 所有标题对象

**示例**

时不时地,我们可能会在技工中心里搞到这种垃圾.

```
[.aaa([foo], ...) another bad heading](#-aaa--foo--------another-bad-heading)
```

除非你喜欢这种东西, 你可能会想 过滤这些坏标题.

```js
function removeJunk(str, ele, arr) {
  return str.indexOf('...') === -1;
}

var result = toc(str, {filter: removeJunk});
//=> beautiful TOC
```

### 选项

类型 : `Function`

默认:基本非单词字符替换.

**示例**

```js
var str = toc('# Some Article', {slugify: require('uslug')});
```

### 选项。 子弹

类型 : `String|Array`

默认 : `*`

用于生成的 TOC 中每个项目的子弹 。 如果以数组方式传递( I)`['*', '-', '+']`),弹出点字符串将根据头部深度使用.

### 选项。最大深度

类型 : `Number`

默认 : `6`

使用深度最高的标题 .

### 选项

类型 : `Boolean`

默认 : `true`

不包括文件中的第一个 h1 级标题 。 例如,这阻止了README中的第一个标题出现在TOC中.

### 选项。字符串标题标签

类型 : `Boolean`

默认 : `true`

在拼写前从标题中取出不相干 HTML 标记 。 这类似于GitHub markdown行为.

## 关于

**捐款**

拉出请求和星星总是受欢迎的. 对于错误和特性请求, [请创建一个问题](https://npmcn.com/package/issues/new)。 。 。 .

**运行测试**

运行和审查单元测试是熟悉图书馆及其API的好办法。 您可以使用以下命令安装依赖性并运行测试:

```sh
$ npm install && npm test
```
**大楼文件**

_(此工程的 readme.md 由 [动词](https://github.com/verbose/verb-generate-readme)请不要直接编辑读取器。 读取器的任何改动必须在 [动词 md](https://npmcn.com/package/%40effect/markdown-toc/.verb.md) 读取我的模板。 )_

要生成读取, 请运行以下命令 :

```sh
$ npm install -g verbose/verb#dev verb-generate-readme && verb
```

### 相关项目

您可能也对这些项目感兴趣:

-   [gfm 码块](https://www.npmjs.com/package/gfm-code-blocks): 从字符串取出 gfm (GitHub Flavored Markdown) 栅栏的代码块. | [主页](https://github.com/jonschlinkert/gfm-code-blocks "Extract gfm (GitHub Flavored Markdown) fenced code blocks from a string.")
-   [下行链接](https://www.npmjs.com/package/markdown-link): 用于生成单一标记下链接的微用户端. QQ [主页](https://github.com/jonschlinkert/markdown-link "Micro util for generating a single markdown link.")
-   [降级使用量](https://www.npmjs.com/package/markdown-utils): 微小的帮助者,用于创建有结构化的平分标记片段. | [主页](https://github.com/jonschlinkert/markdown-utils "Tiny helpers for creating consistenly-formatted markdown snippets.")
-   [相当显著](https://www.npmjs.com/package/pretty-remarkable): 用于使用自定义渲染器规则预加标记的插件 。\\\\\\ x [主页](https://github.com/jonschlinkert/pretty-remarkable "Plugin for prettifying markdown with Remarkable using custom renderer rules.")
-   [显著](https://www.npmjs.com/package/remarkable)Markdown 解析器,完成对了。 100%的通用标记支持,扩展,语法插件,高速 - 全部在 [更多](https://github.com/jonschlinkert/remarkable) | [主页](https://github.com/jonschlinkert/remarkable "Markdown parser, done right. 100% Commonmark support, extensions, syntax plugins, high speed - all in one.")

### 贡献者

| **提交** | **贡献者** |
| --- | --- |
| 199 (韩语) | [扬施林克特](https://github.com/jonschlinkert) |
| 第9条 | [鸽子](https://github.com/doowb) |
| 页:1 | [dbooth - 波士顿](https://github.com/dbooth-boston) |
| 3个 | [s](https://github.com/sapegin) |
| 3个 | [马苏普](https://github.com/Marsup) |
| 2个 | [dvcrn 数据](https://github.com/dvcrn) |
| 2个 | [最大](https://github.com/maxogden) |
| 2个 | [黄2218](https://github.com/twang2218) |
| 2个 | [齐克](https://github.com/zeke) |
| 1个 | [阀门 375](https://github.com/Vortex375) |
| 1个 | [{\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}这太糟糕了](https://github.com/chendaniely) |
| 1个 | [丹尼尔-米德申](https://github.com/Daniel-Mietchen) |
| 1个 | [费德罗1co5ave](https://github.com/Feder1co5oave) |
| 1个 | [绿色](https://github.com/garygreen) |
| 1个 | [泰克史莱克](https://github.com/TehShrike) |
| 1个 | [公民马特](https://github.com/citizenmatt) |
| 1个 | [克伦霍夫](https://github.com/mgroenhoff) |
| 1个 | [拉法埃尔斯泰尔](https://github.com/rafaelsteil) |
| 1个 | [理查德·布莱德利](https://github.com/RichardBradley) |
| 1个 | [设置](https://github.com/sethvincent) |
| 1个 | [沙内胡斯3](https://github.com/shanehughes3) |
| 1个 | [布乔](https://github.com/bcho) |
| 1个 | [卢22道](https://github.com/lu22do) |

### 作者

**乔恩·斯林克特**

-   [GitHub 配置文件](https://github.com/jonschlinkert)
-   [推特简介](https://twitter.com/jonschlinkert)
-   [链接到配置文件](https://linkedin.com/in/jonschlinkert)

### 许可证

版权 2023, [乔恩·斯林克特](https://github.com/jonschlinkert)。 。 。 . 释放 [MIT 许可证](https://npmcn.com/package/%40effect/markdown-toc/LICENSE)。 。 。 .

* * *

_此文件由 [动词基因读取器](https://github.com/verbose/verb-generate-readme),v0.8.0,于2023年7月12日查阅._

## 常见问题

### @effect/markdown-toc 是什么？

生成可标记的 TOC\(目录\) \.

### 如何安装 @effect/markdown-toc？

在项目目录运行 npm install @effect/markdown-toc，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 markdown-toc，可以用 npx markdown-toc 直接运行。

### @effect/markdown-toc 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/effect\_\_markdown-toc 是否存在。

### @effect/markdown-toc 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @effect/markdown-toc 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=0\.10\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @effect/markdown-toc 可以商用吗？

@effect/markdown-toc 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @effect/markdown-toc 的下载量有多少？

根据 npm 官方下载统计，@effect/markdown-toc 在 2026/10/13 – 2026/11/11 这 30 天内被下载 95,267 次，日均约 3,176 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @effect/markdown-toc 还在维护吗？

最新版本 0\.1\.0 发布于 2024/04/11（2 年前）；至今共发布 1 个版本，其中过去 12 个月发布了 0 个；首次发布于 2024/04/11。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。