markdown-toc 使用教程

markdown-toc 使用教程

markdown-tocAPI and CLI for generating a markdown TOC (table of contents) for a README or any markdown files. Uses Remarkable to parse markdown. Used by NASA/openmct, Prisma, Joi, Mocha, Sass, Prettier, Orbit DB, FormatJS, Raneto, hapijs/code, webpack-flow, docusaurus, release-it, ts-loader, json-server, reactfire, bunyan, husky, react-easy-state, react-snap, chakra-ui, carbon, alfresco, repolinter, Assemble, Verb, and thousands of other projects.项目地址:https://gitcode.com/gh_mirrors/ma/markdown-toc

项目介绍

markdown-toc 是一个用于生成 Markdown 文件目录（Table of Contents，TOC）的工具。它支持通过 API 和 CLI 两种方式使用，能够帮助用户快速生成 Markdown 文件的目录，使得文档结构更加清晰。该项目由 Jon Schlinkert 开发，广泛应用于多个知名项目，如 NASA/openmct、Prisma、Joi、Mocha 等。

项目快速启动

安装

首先，你需要通过 npm 安装 markdown-toc：

npm install -g markdown-toc

使用

假设你想要为 README.md 文件生成目录，可以按照以下步骤操作：

1. 编辑 README.md 文件，在你希望插入目录的位置插入以下注释：

   <!-- toc -->
   

2. 运行以下命令生成目录：

   markdown-toc -i README.md
   

CLI 使用示例

以下是一个完整的 CLI 使用示例：

markdown-toc [options] <input>

• input: 需要解析的 Markdown 文件路径，或者使用 - 从标准输入读取。
• -i: 直接编辑输入文件，将目录插入到指定位置。

应用案例和最佳实践

应用案例

markdown-toc 广泛应用于各种开源项目的文档中，例如：

• NASA/openmct: 用于生成项目文档的目录，方便开发者快速导航。
• Prisma: 在官方文档中使用，使得用户可以更方便地查找所需信息。

最佳实践

• 自动化集成: 可以在 CI/CD 流程中集成 markdown-toc，确保每次文档更新后目录都是最新的。
• 自定义样式: 通过修改生成的目录样式，使其更符合项目整体风格。

典型生态项目

markdown-toc 作为 Markdown 工具链的一部分，与以下项目紧密相关：

• Remarkable: 一个 Markdown 解析器，markdown-toc 使用它来解析 Markdown 文件。
• Assemble: 一个静态站点生成器，可以与 markdown-toc 结合使用，生成带有目录的静态页面。
• Verb: 一个文档生成工具，可以自动生成项目的 API 文档，并集成 markdown-toc 生成目录。

通过这些生态项目的配合，markdown-toc 能够更好地服务于各种文档生成和管理的场景。

markdown-tocAPI and CLI for generating a markdown TOC (table of contents) for a README or any markdown files. Uses Remarkable to parse markdown. Used by NASA/openmct, Prisma, Joi, Mocha, Sass, Prettier, Orbit DB, FormatJS, Raneto, hapijs/code, webpack-flow, docusaurus, release-it, ts-loader, json-server, reactfire, bunyan, husky, react-easy-state, react-snap, chakra-ui, carbon, alfresco, repolinter, Assemble, Verb, and thousands of other projects.项目地址:https://gitcode.com/gh_mirrors/ma/markdown-toc