Markdown-it-toc-done-right 使用指南

Markdown-it-toc-done-right 使用指南

markdown-it-toc-done-rightA table of contents (TOC) plugin for Markdown-it with focus on semantic and security. Made to work gracefully with markdown-it-anchor.项目地址:https://gitcode.com/gh_mirrors/ma/markdown-it-toc-done-right

---

项目介绍

Markdown-it-toc-done-right 是一个高度可配置且强大的 Markdown TOC (目录) 插件，专为那些寻求对自动生成的目录具有完全控制权的开发者设计。它基于著名的 Markdown-it 解析器，确保了与 Markdown 格式的完美兼容性。通过这个插件，您可以轻松地在 Markdown 文档中插入一个精确且样式灵活的目录。

项目快速启动

要快速开始使用 markdown-it-toc-done-right，首先确保您的项目环境中已安装 Node.js。然后，遵循以下步骤：

安装插件

在项目根目录下，使用 npm 或 yarn 添加该插件：

npm install markdown-it-toc-done-right --save

或

yarn add markdown-it-toc-done-right

集成到 Markdown 解析流程

在您的代码中引入 Markdown-it 和此插件，并进行配置：

const markdownIt = require('markdown-it');
const tocPlugin = require('markdown-it-toc-done-right');

// 初始化 Markdown-it 实例
const md = markdownIt();
// 添加 TOC 插件并配置（例如，设置最大深度）
md.use(tocPlugin, {
  maxDepth: 3, // 只列出 h1, h2, h3 的 TOC
  anchorlink: true, // 启用自动添加锚点链接
});

// 示例：处理 Markdown 字符串
const mdString = '# 标题\n\n## 子标题';
const html = md.render(mdString);
console.log(html);

这样，当您解析 Markdown 时，插件就会在适当的位置生成目录。

应用案例和最佳实践

在博客、技术文档或任何长篇 Markdown 内容中，使用 markdown-it-toc-done-right 可以大大增强导航体验。最佳实践包括：

• 在文档开头使用 <!-- toc --> 标签来指示 TOC 的位置。
• 通过插件配置，确保 TOC的层级结构清晰反映文档逻辑。
• 利用自动锚点链接提升用户体验，使直接跳转至特定章节变得简单快捷。

典型生态项目

虽然本插件专注于为 Markdown 提供强大的 TOC 支持，但其广泛应用于各种内容管理系统(CMS)、静态站点生成器如 Jekyll、Hugo 中，以及个人博客和技术文档项目里。结合这些工具，可以实现高效的内容管理和优雅的在线展示，尤其适合那些重度依赖 Markdown 编辑的开源项目或个人网站。

通过将 markdown-it-toc-done-right 纳入您的工作流程，您不仅提升了文档的组织性和易读性，还能够享受到开源社区持续更新和支持的好处。是否下一个精彩的故事，就从这里开始？

markdown-it-toc-done-rightA table of contents (TOC) plugin for Markdown-it with focus on semantic and security. Made to work gracefully with markdown-it-anchor.项目地址:https://gitcode.com/gh_mirrors/ma/markdown-it-toc-done-right