一、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 总是成对出现

content 只用于“行内”文本，不用于结构 token

二、python包：markdown-it

1. markdown-it 将 Markdown 文档解析成一个扁平化的 Token 列表，每个 Token 都有下列属性：

type—— “语法元素类型”（关键），决定 Token 代表哪种 Markdown 结构，常见type包括：

tag —— 对应 HTML 标签名称（比如 h1, p, 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 MarkdownIt

md = 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_open
   inline -> text("docker images")
paragraph_close

paragraph_open
   inline -> 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}")