markdown文档格式分析，再使用python对md文件进行结构化拆解

一、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![image-2025xxxx](docker学习-use-images/image-2025xxxx.png)

使用代码将文档进行拆解：

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 = """
### 标题这是一个段落，包含 **粗体** 和 *斜体*。![图1](images/img1.png "图1标题")
"""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}")