一、markdown文档
Markdown 文档本质上是：一个树状结构（Block 级） + 行内结构（Inline 级）
Block 级元素（结构）：
-
heading_open → inline → heading_close
-
paragraph_open → inline → paragraph_close
-
list_open → list_item_open → inline → list_item_close
-
blockquote_open → ...
-
fence（代码块）
Inline 级元素（在一行内出现）：
-
text
-
image
-
link_open → inline → link_close
-
strong_open / strong_close
-
em_open / em_close
md文件结构规律
一个 block 总是成对出现
| Markdown | Token |
|---|---|
# 标题 |
heading_open → inline → heading_close |
| 段落 | paragraph_open → inline → paragraph_close |
| 列表项 | list_item_open → inline → list_item_close |
content 只用于“行内”文本，不用于结构 token
| type | content |
|---|---|
| heading_open | "" |
| inline | 整行文本（包含 md 语法） |
| text | 文本内容 |
| image | alt 文本（即 ![alt] ） |
二、python包：markdown-it
1. markdown-it 将 Markdown 文档解析成一个扁平化的 Token 列表，每个 Token 都有下列属性：
type—— “语法元素类型”（关键），决定 Token 代表哪种 Markdown 结构，常见type包括：
| 语法 | type |
| # 标题 | heading_open, heading_close |
| 段落 | paragraph_open, paragraph_close |
| 行内内容 | inline |
图片 ![]() |
image |
列表 - item |
bullet_list_open, list_item_open 等 |
tag —— 对应 HTML 标签名称（比如 h1, p, img）
| 类型 | tag |
| heading_open（###） | h3 |
| paragraph_open | p |
| image | img |
content —— 文本内容（只有 inline 或 text 子 Token 才有）
-
对于
inline→ content 是整行的原始文本（如"docker images"） -
对于
text→ content 是纯文字（真正的文本节点） -
对于
image→ content 是alt内容（比如"image-2025..."）
attrs —— HTML 属性（图片的 src/alt/title 全在这里）
2. Markdown → Token 映射
假设有markdown原文：
### 语法 docker images
使用代码将文档进行拆解：
from pathlib import Path from markdown_it import MarkdownItmd = MarkdownIt()md_path = Path(r"./docker学习.md") md_text = md_path.read_text(encoding="utf-8")tokens = md.parse(md_text)for t in tokens:print(f"type: {t.type}, tag: {t.tag}, content: {t.content}, attrs: {t.attrs}")
得到语义树：
heading_open (tag h3)inline -> text("语法") heading_close (tag h3)paragraph_openinline -> text("docker images") paragraph_closeparagraph_openinline -> image (alt="image-2025...", src="docker学习-use-images/...") paragraph_close
这套结构适合用代码进行文档分析。
3. markdown-it的一些用法
简要示例
from markdown_it import MarkdownIt# 安装 & 创建解析器 md = MarkdownIt()# 将文本渲染成html格式字符串 text = """ ### 标题这是一个段落，包含 **粗体** 和 *斜体*。 """html = md.render(text) print(html)# 将文本解析成token列表，需要先将md文档逐行读取到变量里面 md_path = Path(r"./docker学习.md") md_text = md_path.read_text(encoding="utf-8")tokens = md.parse(md_text)for t in tokens:print(f"type: {t.type}, tag: {t.tag}, content: {t.content}, attrs: {t.attrs}")