在Just-the-Docs中全局排除H1标题的TOC生成方法

Just-the-Docs是一个基于Jekyll的文档主题，它提供了自动生成目录(TOC)的功能。在实际使用中，开发者可能会遇到需要从目录中排除所有一级标题(H1)的需求。

问题背景

许多开发者使用LSP(Language Server Protocol)工具进行Markdown编辑时，这些工具会自动在标题后添加换行符。这导致无法直接在H1标题后添加{: .no_toc }类来排除该标题从目录中显示。手动为每个H1标题添加排除标记不仅繁琐，而且影响文档的整洁性。

解决方案

通过修改Jekyll配置文件_config.yml，可以全局设置目录生成规则：

kramdown:
  toc_levels: 2..6

这个配置利用了Kramdown(Just-the-Docs使用的Markdown解析器)提供的选项功能。toc_levels参数指定了应该包含在目录中的标题级别范围，这里设置为从2级(H2)到6级(H6)，从而自动排除所有1级标题(H1)。

技术原理

1. Kramdown解析器：作为Jekyll默认支持的Markdown解析器之一，提供了丰富的文档处理选项
2. 目录级别控制：toc_levels参数接受一个范围值，确定哪些级别的标题应该出现在生成的目录中
3. 全局配置优势：相比逐个标题添加排除标记，这种方法更加简洁且易于维护

实际效果

应用此配置后：

• 所有H1标题将不会出现在页面目录中
• 无需在每个H1标题后手动添加{: .no_toc }
• 保持文档源文件的整洁性
• 与各种编辑器和LSP工具兼容性更好

最佳实践建议

1. 对于文档网站，通常建议保留H1标题作为页面主标题，而使用H2-H6构建内容结构
2. 如果确实需要显示某些H1标题在目录中，可以单独为其添加{:toc}标记
3. 此配置不会影响页面内容的显示，只会影响目录生成行为

这种方法简化了文档维护工作流程，特别是对于大型文档项目，能够显著提高开发效率。