一、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 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 = """ ### 標題 這是一個段落，包含 **粗體** 和 *斜體*。  """ 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}")
