# @atomictech/rehype-toc 中文文档

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

版本：3\.1\.3
npm 元数据更新时间：2022-04-04T16:15:17.557Z
中文译文更新时间：2026-11-08T07:42:46.569Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40atomictech/rehype-toc
原文对照：https://npmcn.com/package/%40atomictech/rehype-toc/?lang=original
项目主页：https://jstools.dev/rehype-toc
源码仓库：https://github.com/JS-DevTools/rehype-toc

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

- 包体积（解压后）：56.8 kB，40 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=10
- 运行依赖：0 个
- 首次发布：2021-01-07T23:46:45.518Z
- 最新版本发布：2021-03-30T17:37:22.359Z
- 近 30 天下载量：1864（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 0 个）

## 中文简介

在页面中添加目录( TOC) 的重排插件

## 安装

```sh
npm install @atomictech/rehype-toc
```

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

## README

# Rehype 的目录插件

A 类 [复韵](https://github.com/rehypejs/rehype) 在页面上添加目录( TOC) 的插件

[![Cross-Platform Compatibility](https://jstools.dev/img/badges/os-badges.svg)](https://github.com/JS-DevTools/rehype-toc/actions) [![Build Status](https://github.com/JS-DevTools/rehype-toc/workflows/CI-CD/badge.svg)](https://github.com/JS-DevTools/rehype-toc/actions)

[![Coverage Status](https://coveralls.io/repos/github/JS-DevTools/rehype-toc/badge.svg?branch=master)](https://coveralls.io/github/JS-DevTools/rehype-toc) [![Dependencies](https://david-dm.org/JS-DevTools/rehype-toc.svg)](https://david-dm.org/JS-DevTools/rehype-toc)

[![npm](https://img.shields.io/npm/v/@jsdevtools/rehype-toc.svg)](https://www.npmjs.com/package/@jsdevtools/rehype-toc) [![License](https://img.shields.io/npm/l/@jsdevtools/rehype-toc.svg)](https://npmcn.com/package/%40atomictech/rehype-toc/LICENSE) [![Buy us a tree](https://img.shields.io/badge/Treeware-%F0%9F%8C%B3-lightgreen)](https://plant.treeware.earth/JS-DevTools/rehype-toc)

## 特征

-   添加一个 `<nav>` 财务报告和审定财务报表 `<ol>` 列表,列出页面上的所有标题
-   与 [重击- slug](https://github.com/rehypejs/rehype-slug) 创建每个标题的链接
-   忽略标题 `<main>` 如果它存在的话
-   您可以自定义包含哪些标题( 默认为 `<h1>` - 说吧 `<h6>`(中文(简体) )
-   您可以在每个 TOC 元素上自定义 CSS 类
-   Hooks 使您完全定制生成的 HTML

## 示例

**输入.html**  
以下是HTML的原始文件. 标题分为三个层次:`<h1>` - 说吧 `<h3>`他们中没有一个有身份证.

```html
<html>
  <body>
    <h1>Apple Pie Recipe</h1>
    <p>This is the world's best apple pie recipe...</p>

    <div>
      <h2>Filling</h2>
      <p>The filling is the best part...</p>

      <h3>Preparing the apples</h3>
      <p>Cut the apples into 1/4 inch slices...</p>

      <h3>Preparing the spice mix</h3>
      <p>In a mixing bowl, combine sugar, cinnamon...</p>
    </div>

    <div>
      <h2>Crust</h2>
      <p>How to make the perfect flaky crust...</p>

      <h3>Preparing the dough</h3>
      <p>Combine flour, sugar, salt...</p>

      <h3>The criss-cross top</h3>
      <p>Cut the top crust into 1/2 inch strips...</p>
    </div>
  </body>
</html>
```

**实例.js**  
此脚本读取 `input.html` 上方文件将结果写入 `output.html` (下划线). 脚本使用 [统一](https://unifiedjs.com/), (中文(简体) ), [复韵区](https://github.com/rehypejs/rehype/tree/master/packages/rehype-parse), (中文(简体) ), [重击- slug](https://github.com/rehypejs/rehype-slug),以及 [重排字符串](https://github.com/rehypejs/rehype/tree/master/packages/rehype-stringify)。 。 。 .

```javascript
const unified = require("unified");
const parse = require("rehype-parse");
const slug = require("rehype-slug");
const toc = require("@jsdevtools/rehype-toc");
const stringify = require("rehype-stringify");
const fs = require("fs");

async function example() {
  // Create a Rehype processor with the TOC plugin
  const processor = unified()
    .use(parse)
    .use(slug)
    .use(toc)
    .use(stringify);

  // Read the original HTML file
  let inputHTML = await fs.promises.readFile("input.html");

  // Process the HTML, adding heading IDs and Table of Contents
  let outputHTML = await processor.process(inputHTML);

  // Save the new HTML
  await fs.promises.writeFile("output.html", outputHTML);
}
```

**输出.html**  
以下是上面的脚本所创建的HTML. 注意目录已添加到 `<body>`,并附有页面上每个标题的链接。 这些标题现在也有身份证,因为 [重击- slug](https://github.com/rehypejs/rehype-slug)。 。 。 .

```html
<html>
  <body>
    <nav class="toc">
      <ol class="toc-level toc-level-1">
        <li class="toc-item toc-item-h1">
          <a class="toc-link toc-link-h1" href="#apple-pie-recipe">
            Apple Pie Recipe
          </a>

          <ol class="toc-level toc-level-2">
            <li class="toc-item toc-item-h2">
              <a class="toc-link toc-link-h2" href="#filling">
                Filling
              </a>

              <ol class="toc-level toc-level-3">
                <li class="toc-item toc-item-h3">
                  <a class="toc-link toc-link-h3" href="#preparing-the-apples">
                    Preparing the apples
                  </a>
                </li>
                <li class="toc-item toc-item-h3">
                  <a class="toc-link toc-link-h3" href="#preparing-the-spice-mix">
                    Preparing the spice mix
                  </a>
                </li>
              </ol>
            </li>

            <li class="toc-item toc-item-h2">
              <a class="toc-link toc-link-h2" href="#crust">
                Crust
              </a>

              <ol class="toc-level toc-level-3">
                <li class="toc-item toc-item-h3">
                  <a class="toc-link toc-link-h3" href="#preparing-the-dough">
                    Preparing the dough
                  </a>
                </li>
                <li class="toc-item toc-item-h3">
                  <a class="toc-link toc-link-h3" href="#the-criss-cross-top">
                    The criss-cross top
                  </a>
                </li>
              </ol>
            </li>
          </ol>
        </li>
      </ol>
    </nav>

    <h1 id="apple-pie-recipe">Apple Pie Recipe</h1>
    <p>This is the world's best apple pie recipe...</p>

    <div>
      <h2 id="filling">Filling</h2>
      <p>The filling is the best part...</p>

      <h3 id="preparing-the-apples">Preparing the apples</h3>
      <p>Cut the apples into 1/4 inch slices...</p>

      <h3 id="preparing-the-spice-mix">Preparing the spice mix</h3>
      <p>In a mixing bowl, combine sugar, cinnamon...</p>
    </div>

    <div>
      <h2 id="crust">Crust</h2>
      <p>How to make the perfect flaky crust...</p>

      <h3 id="preparing-the-dough">Preparing the dough</h3>
      <p>Combine flour, sugar, salt...</p>

      <h3 id="the-criss-cross-top">The criss-cross top</h3>
      <p>Cut the top crust into 1/2 inch strips...</p>
    </div>
  </body>
</html>
```

## 安装

您可以通过 Rehype TOC 安装 [无](https://docs.npmjs.com/about-npm/)。 。 。 .

```bash
npm install @jsdevtools/rehype-toc
```

你可能会想安装 [统一](https://unifiedjs.com/), (中文(简体) ), [复韵区](https://github.com/rehypejs/rehype/tree/master/packages/rehype-parse), (中文(简体) ), [重排字符串](https://github.com/rehypejs/rehype/tree/master/packages/rehype-stringify),以及 [重击- slug](https://github.com/rehypejs/rehype-slug) 还有.

```bash
npm install unified rehype-parse rehype-stringify rehype-slug
```

## 使用量

使用Rehype TOC插件需要了解如何使用United和Rehype. [这里有一个优秀的指南](https://unifiedjs.com/using-unified.html) 学习基础.

Rehype TOC插件和任何其他的Rehype插件一样有效. 传过来 [页:1 `.use()` 方法](https://github.com/unifiedjs/unified#processoruseplugin-options),可选择使用 [选项对象](https://npmcn.com/package/%40atomictech/rehype-toc/#readme-options)。 。 。 .

```javascript
const unified = require("unified");
const toc = require("@jsdevtools/rehype-toc");

// Use the Rehype TOC plugin with its default options
unified().use(toc);

// Use the Rehype TOC plugin with custom options
unified().use(toc, {
  headings: ["h1", "h2"],     // Only include <h1> and <h2> headings in the TOC
  cssClasses: {
    toc: "page-outline",      // Change the CSS class for the TOC
    link: "page-link",        // Change the CSS class for links in the TOC
  }
});
```

## 选项

Rehype TOC 插件支持以下选项:

| 选项 | 类型 | 默认 | 说明 |
| :-- | :-- | :-- | :-- |
| `nav` | 布尔 | 真实 | 确定目录是否以 `<nav>` 键. |
| `position` | 字符串 | "之后开始" | 相对于 `<main>` 或者说 `<body>` 键。 可以是"开始前","开始后","开始后",也可以是"开始后". 见 [页:1 `insertAdjacentElement()` 文档](https://developer.mozilla.org/en-US/docs/Web/API/Element/insertAdjacentElement) 用于解释每个值. |
| `placeholder` | 字符串 |  | 以目录替换的可选占位符字符串 . |
| `headings` | 字符串数组 | h1, h2, h3, h4, h5, h6 (英语) | 在目录中包含的 HTML 标题标签 |
| `cssClasses.toc` | 字符串 | 目标c | 顶级的 CSS 类名称 `<nav>` 或者说 `<ol>` 包含整个目录的元素. |
| `cssClasses.list` | 字符串 | c 级 | CSS 类名 `<ol>` 目录中的元素,包括顶级元素. |
| `cssClasses.listItem` | 字符串 | 托克项目 | CSS 类名 `<li>` 目录中的元素. |
| `cssClasses.link` | 字符串 | toc 链接 | CSS 类名 `<a>` 目录中的元素. |
| `customizeTOC` | 函数(toc) |  | 允许您在添加到页面之前自定义目录.  
  
该函数接收到TOC节点树并可以任意修改. 或者你可以返回一个新的节点树来取而代之. 或者回来 `false` 以防止TOC被添加到页面中. |
| `customizeTOCItem` | 函数(toc,标题) |  | 允许您在添加到页面之前自定义目录中的每个项目.  
  
该函数接收 TOC 项目的节点树和它所指的标题节点. 你可以随意修改节点. 或者你可以返回一个新的节点树来取而代之. 或者回来 `false` 以防止TOC被添加到页面中. |

## 捐款

欢迎贡献、增强和错误修正! [打开一个问题](https://github.com/JS-DevTools/rehype-toc/issues) 关于 GitHub 和 [提交拉动请求](https://github.com/JS-DevTools/rehype-toc/pulls)。 。 。 .

#### 大楼

要在您的计算机上本地构建工程:

1.  **克隆这个还原**  
    `git clone https://github.com/JS-DevTools/rehype-toc.git`
    
2.  **安装依赖关系**  
    `npm install`
    
3.  **构建代码**  
    `npm run build`
    
4.  **运行测试**  
    `npm test`
    

## 许可证

Rehype TOC是100%的自由和开放源码,在 [麻省理工学院许可证](https://npmcn.com/package/%40atomictech/rehype-toc/LICENSE)随意使用.

这个软件包是 [树件](http://treeware.earth/)如果你把它用于生产,那么我们要求你 [**给世界买一棵树**](https://plant.treeware.earth/JS-DevTools/rehype-toc) 感谢我们的工作。 将会为当地家庭创造就业机会.

## 谢谢

感谢这些优秀的公司对开源开发商的支持 QQ

[![Travis CI](https://jstools.dev/img/badges/travis-ci.svg)](https://travis-ci.com/) [![SauceLabs](https://jstools.dev/img/badges/sauce-labs.svg)](https://saucelabs.com/) [![Coveralls](https://jstools.dev/img/badges/coveralls.svg)](https://coveralls.io/)

## 常见问题

### @atomictech/rehype-toc 是什么？

在页面中添加目录\( TOC\) 的重排插件

### 如何安装 @atomictech/rehype-toc？

在项目目录运行 npm install @atomictech/rehype-toc，或使用 pnpm add / yarn add / bun add。

### @atomictech/rehype-toc 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @atomictech/rehype-toc 支持 ESM 还是 CommonJS？

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

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

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

### @atomictech/rehype-toc 可以商用吗？

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

### @atomictech/rehype-toc 的下载量有多少？

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

### @atomictech/rehype-toc 还在维护吗？

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