Python-Markdown项目：TOC扩展中忽略[TOC]标记前标题的技巧

在Python-Markdown的TOC（Table of Contents）扩展使用过程中，开发者经常需要控制目录生成的范围。一个典型需求是：希望自动生成的目录只包含文档中[TOC]标记之后出现的标题，而忽略标记前的所有标题内容。

核心问题分析

标准的TOC扩展会扫描整个文档的所有标题层级来生成目录树。但在实际文档结构中，我们经常会在文档开头使用一个顶级标题（如# 文档标题）作为整个页面的名称，这个标题通常不需要出现在后续的目录导航中。

解决方案：toc_depth参数

Python-Markdown的TOC扩展提供了toc_depth参数，通过合理配置这个参数可以实现忽略特定层级标题的效果：

markdown.markdown(text, extensions=['toc'], extension_configs={
    'toc': {'toc_depth': '2-6'}
})

这种配置会：

1. 只显示二级(##)到六级(######)标题
2. 自动跳过一级标题(#)
3. 保持后续标题层级的完整嵌套关系

实现原理

TOC扩展的工作原理是：

1. 扫描文档解析后的抽象语法树(AST)
2. 识别所有标题元素（h1-h6）
3. 根据toc_depth参数过滤符合条件的标题
4. 构建嵌套的目录结构

当设置为'2-6'时，扩展会主动排除所有h1级别的标题节点，无论它们出现在文档的什么位置。

注意事项

这种方案需要注意：

1. 会全局忽略所有h1标题，包括[TOC]标记后可能存在的h1
2. 如果文档结构需要使用多级h1标题，则需要考虑其他方案
3. 可以通过CSS单独设置页面标题样式，而不依赖h1标签

最佳实践建议

对于技术文档编写，推荐：

1. 保持页面标题使用h1
2. 内容章节从h2开始
3. 使用toc_depth='2-6'配置
4. 通过CSS美化页面标题样式

这样既能保持语义化的文档结构，又能获得整洁的目录导航体验。