最可靠方式是用 markdown-it-py 解析 AST 并遍历 heading_open 节点提取层级与文本，需手动处理 frontmatter、内联标记及 HTML 实体，正则仅适用于简单预处理。
用 re 提取 Markdown 标题最简单但有局限
直接匹配 # 开头的行能快速拿到一级标题，但真实 Markdown 标题可能带空格、缩进、ATX 后缀（如 # Title {#custom-id}），甚至混在代码块或引用块里。正则不解析上下文，容易误抓。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 仅用于预处理或草稿分析，别用在生产环境做结构化提取
- 基础模式用
^#{1,6}\s+(.+?)(?:\s+#{1,6})?$（需加re.MULTILINE），但要手动过滤掉代码块内的匹配 - 遇到
```包裹的内容必须跳过——正则本身做不到，得先按代码块切分再逐段处理
用 markdown-it-py 解析更可靠，但不是为提取标题设计
markdown-it-py 是目前最接近 CommonMark 规范的 Python 解析器，能准确识别标题层级、属性、嵌套，但它输出的是 AST（抽象语法树），不是现成的标题列表。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 安装后用
MarkdownIt().parse()得到 token 列表，遍历找type === "heading_open"的节点 - 对应内容在下一个
inlinetoken 的children里，需拼接文本并剔除内联标记（如强调、链接） - 性能比正则慢一个数量级，但对复杂文档（含 HTML、数学公式、自定义容器）唯一靠谱
用 mdx_truly_sane_lists 或 mistune 做轻量标题提取
mistune（v2+）默认关闭渲染，可开启 parse_header 插件，直接返回带 level 和 text 的标题字典；mdx_truly_sane_lists 是小众但专注解析的库，API 更直白。
实操建议：
立即学习“Python免费学习笔记（深入）”；
-
mistune.create_markdown(plugins=['parse_header'])后调用.ast(mdx_content)，结果里type == 'heading'的节点即标题 - 注意
mistunev2 不兼容 v1 的插件写法，旧项目升级会报AttributeError: 'Markdown' object has no attribute 'render' - 如果只要标题，别用
html渲染器——它把标题转成<h1></h1>后还得反向解析，纯属绕路
真正需要结构化标题时，优先选 markdown-it-py + 自定义遍历
多数人想“读取 Markdown 并获取所有标题及其层级”，本质是要一份干净的 [{'level': 1, 'text': 'Intro'}, {'level': 2, 'text': 'Setup'}]。没有一行函数能直接返回这个，必须自己走一遍 AST。
关键细节：
- 标题文本里可能含 HTML 实体（如
token.children里的content字段不一定可读，得递归提取text属性 -
markdown-it-py默认不解析 frontmatter，YAML 头部会被当普通段落，需提前用re.split(r'^---\s*$', content, maxsplit=2, flags=re.M)切掉 - 别依赖
token.map推算行号——某些标题（如空行后紧跟##）的map可能是None
