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

1. 项目目录结构及介绍

markdown-toc 是一个用于生成 Markdown 文件中有序目录的 Node.js 工具。其核心源代码位于 lib 目录下，主要包括以下子目录：

• index.js: 主入口文件，提供了命令行接口（CLI）和 API。
• parse.js: 解析 Markdown 文件并获取标题信息的模块。
• create.js: 生成 TOC 的逻辑实现。

此外，bin 目录包含了可执行的 markdown-toc 脚本，可以直接在终端中运行。examples 目录提供了使用示例，test 目录存储测试用例，而 package.json 文件定义了项目的依赖和元数据。

2. 项目的启动文件介绍

安装

首先确保你的系统已经安装了 Node.js 和 npm。接着，你可以通过 npm 来安装 markdown-toc：

$ npm install --save markdown-toc

命令行使用

安装完成后，可以通过全局安装使 markdown-toc 可在任何地方使用，或者在本地项目目录中直接调用：

# 全局安装
$ npm install -g markdown-toc

# 或者在本地项目中使用
$ npx markdown-toc

执行 markdown-toc 命令，它会在标准输入 (stdin) 读取 Markdown 文件，然后在标准输出 (stdout) 输出 TOC。

示例

在你想要插入 TOC 的 Markdown 文件顶部添加 <!-- toc --> 标记，然后运行以下命令：

$ markdown-toc -i path/to/your/file.md

这将会在指定位置插入 TOC。

3. 项目的配置文件介绍

markdown-toc 提供了一些命令行选项来定制 TOC 的生成方式：

• -i, --insert: 更新现有 Markdown 文件，将 TOC 插入到 <!-- toc --> 或 <!-- tocstop --> 标记之间。
• -s, --space: 设置标题缩进空格数量，默认是 2。
• -l, --maxdepth: 限制 TOC 的最大深度，默认是 6。
• -f, --fixed: 使用固定格式的序号，而不是递增序号。
• -n, --numbered: 为所有标题添加编号。
• --no-autoh1: 避免自动将第一个标题识别为 H1。
• --brackets: 自定义链接括号 [ ]，例如 --brackets '（）'。

这些选项可以通过在运行命令时传递参数来设置，或者在你的项目中创建一个名为 .markdown-toc.json 的配置文件来保存默认设置。例如：

{
  "space": 4,
  "maxDepth": 4,
  "fixed": true
}

当你使用此配置文件时，只需执行 markdown-toc file.md，工具就会根据文件中的设置生成 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