为什么要解析成 token
Markdown 是纯文本，但结构信息（标题层级、列表、代码块、表格）藏在符号里；直接按字符数切分会把标题和它的正文切开，检索到的段落失去上下文。先解析成 token 流，就能按标题层级组织切片、给每段带上标题路径元数据，做到「检索到段落，也知道它属于哪一章」。这是文档站与仓库文档入库的通用做法。
基本信息
| 适用语料 | 技术文档站、仓库 README 与手册、博客归档 |
|---|---|
| 代表库 | Python 用 markdown-it-py；解析器选定后全库统一 |
| 产出 | token 流（heading、list、code、table 等）与标题路径 |
| 方言风险 | CommonMark 与 GFM 对表格、脚注等语法处理不同 |
典型使用场景
- 文档站入库：按二级标题切分，每个切片带上章节路径便于展示与过滤
- 代码块保护：识别 fence 后整块保留，避免在代码中间断句
- 表格处理：抽出表格结构转 Markdown 或按行成条，保留表头语义
- 目录与导航生成：从标题 token 直接生成知识库的章节树
- 多方言兼容：统一解析器版本，避免同一文档在不同工具下切分不一致
解析示例
解析示例
from markdown_it import MarkdownIt
md = MarkdownIt() # 统一用同一解析器与配置
tokens = md.parse("# 标题\n\n- 项目一\n- 项目二") # 得到结构化的 token 列表
for t in tokens[:5]:
print(t.type, t.tag, t.level) # heading_open / bullet_list_open 等
# 实际切分时按 heading_open 建立章节边界，把当前标题路径写进切片元数据常用 token 与处理
| token 类型 | 对应结构 | 入库建议 |
|---|---|---|
| heading_open | 标题层级 | 作为切片边界，标题文本写入标题路径 |
| fence | 代码块 | 整块保留为一个切片，不按长度硬切 |
| table_open | 表格 | 转 Markdown 或按行切分，保留表头 |
| list_item_open | 列表项 | 保持列表项完整，避免从中间断开 |
标题路径元数据的价值在检索侧：命中后可展示所属章节，也支持「只在这个手册里搜」这类过滤，无需再解析原文。
解析与切分是两件事：解析器负责还原结构，切分策略（按标题、按长度、加重叠）单独配置，换切分策略不必换解析器。