📜  在 readme.md 中生成目录 (1)

📅  最后修改于: 2023-12-03 14:51:09.786000             🧑  作者: Mango

在 readme.md 中生成目录

在 README.md 文件中添加目录可以让文档更加清晰、易读和易于导航。本文将介绍如何使用 Markdown 语法和一些工具来自动生成目录。

使用 Markdown 锚点

Markdown 支持锚点(Anchors)语法,在 Markdown 中使用锚点可以创建一个目标位置,之后通过链接到该锚点位置的方式创建目录项。

例如,在 README.md 文件中的某个标题下添加一个锚点:

## 示例标题 <!-- anchor: example -->

这是一个示例标题。

之后,在该文件中使用锚点链接的方式创建一个目录项:

- [示例标题](#example)

这里的 #example 表示锚点的名称。

使用 markdown-toc 工具

markdown-toc 是一个 Node.js 模块,可以通过命令行在 README.md 中自动生成目录。

使用 markdown-toc 首先需要在本地安装 Node.js 和 npm。之后在项目根目录执行以下命令安装 markdown-toc:

npm install -g markdown-toc

安装完成之后,在 README.md 文件所在目录下执行以下命令即可自动生成目录:

markdown-toc README.md --bullets='-' --maxdepth=2

这里 --bullets 参数表示使用何种符号作为列表项的标识,--maxdepth 参数表示生成目录的最大深度(默认为 3),如果不想加深度限制可以使用 --no-max 参数。

markdown-toc 生成的目录项格式如下:

- [示例标题](#example)
结论

在 README.md 中添加目录可以让文档更加清晰、易读和易于导航。使用 Markdown 锚点或 markdown-toc 工具都可以完成自动生成目录的任务。