前言
在前端开发中，常常需要写文档或者笔记，而 markdown 是一种简洁、清晰、易于书写和阅读的文本格式，因此在编写文档或笔记时广泛应用。同时，由于 markdown 的结构相对简单，它很容易被转换成其他格式的文档，例如 HTML 或 PDF。因此，很多时候我们需要将 markdown 转换成其他格式的文档，这就需要涉及到 markdown 解析器。
在前端领域，有很多优秀的 markdown 解析器，例如 marked、markdown-it 等，它们都非常强大，但在某些情况下，我们可能需要一些更加特殊化的功能。本文要介绍的 npm 包 remark-outline 就是一个这样的 npm 包，它可以帮助我们将 markdown 文档中的标题提取出来，生成一个文档大纲。
安装
首先，我们需要在项目中安装 remark-outline：
npm install remark-outline
使用
基本使用
remark-outline 的使用非常简单，它只提供了一个 Unified 插件，我们只需要在 markdown 解析过程中启用这个插件就可以了。
先看一个基本的示例：
-- -------------------- ---- ------- ----- ------- - ------------------ ----- -------- - ----------------------- ----- ------- - ------------------------- ----- ------------ - - - --- -- ---- -- ---- - --- - ----- --------- - ------------------------------------ ----- - ---- - - ----------------------------------- -------------------------
输出：
-- -------------------- ---- -------
-
-
-------- --
-------- ------
----------- -
-
-------- --
-------- -------
----------- --
--
-
-------- --
-------- -------
----------- --
-
-
--
-
-------- --
-------- ------
----------- --
-
-可以看到，remark-outline 提取出了 markdown 文档中所有的标题，并生成了一个标题树形结构，其中每个标题都包括一个标题文本值（value）和标题层级（depth），同时每个标题还包括若干个子标题，其下标的层级比当前标题的层级深 1 级。
配置选项
remark-outline 提供了几个可选配置选项，可以根据实际需求来调整生成的大纲的效果。
maxDepth
指定大纲中标题的最大层级。默认为 6，即只提取出 1～6 级的标题。
const { data } = processor.processSync(markdownText, { maxDepth: 3 })
console.log(data.outline)输出：
-- -------------------- ---- -------
-
-
-------- --
-------- ------
----------- --
--
-
-------- --
-------- ------
----------- --
-
-可以看到，这里只提取出了 1～3 级的标题。
slug
指定是否在大纲中包含标题的 slug。默认为 false，即不包含 slug。
const { data } = processor.processSync(markdownText, { slug: true })
console.log(data.outline)输出：
-- -------------------- ---- -------
-
-
-------- --
-------- ------
------- ------
----------- -
-
-------- --
-------- -------
------- -------
----------- --
--
-
-------- --
-------- -------
------- -------
----------- --
-
-
--
-
-------- --
-------- ------
------- ------
----------- --
-
-可以看到，在包含了 slug 之后，标题对象多了一个 slug 属性，值为标题的 slug 值。
prefix
指定大纲中标题的前缀。默认为空字符串 ''。
const { data } = processor.processSync(markdownText, { prefix: '目录' })
console.log(data.outline)输出：
-- -------------------- ---- -------
-
-
-------- --
-------- --- -----
----------- -
-
-------- --
-------- --- ------
----------- --
--
-
-------- --
-------- --- ------
----------- --
-
-
--
-
-------- --
-------- --- -----
----------- --
-
-可以看到，在添加了 prefix 之后，大纲中的每个标题都是以 prefix 拼接上原标题文本值得到的。
clean
指定大纲中标题文本是否需要去掉 Markdown 内联代码和链接中的内容。默认为 false，即标题文本会保留内联代码和链接中的内容。
-- -------------------- ---- ------- ----- --------------------- - - - --- ---------------------------------- --- --------- - --- - ----- - ---- - - -------------------------------------------- -------------------------
输出：
-- -------------------- ---- -------
-
-
-------- --
-------- ------
----------- --
--
-
-------- --
-------- ------
----------- --
-
-可以看到，这里的大纲中标题文本中包含了链接和内联代码。
const { data } = processor.processSync(markdownTextWithLinks, { clean: true })
console.log(data.outline)输出：
-- -------------------- ---- -------
-
-
-------- --
-------- ------
----------- --
--
-
-------- --
-------- ------
----------- --
-
-在添加了 clean: true 之后，大纲中的标题文本已经去掉了内联代码和链接中的内容。
总结
remark-outline 是一个非常实用的 npm 包，在前端开发中，用它生成文档大纲可以大大提高我们编写文档的效率，同时还能使整个文档结构更加清晰易懂。本文通过实际的代码示例介绍了 remark-outline 的安装和使用方法，同时也介绍了一些可选的配置选项，供读者调整生成的大纲的效果。希望本文对读者有所启发和帮助。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/60055cbf81e8991b448da576