DOC-102 实现 Markdown 解析为 DocumentBlock #7

New Issue

wangdl · 2026-05-30T19:49:00+08:00

wangdl commented

2026-05-30 19:49:00 +08:00

把 Markdown 文件解析成统一 DocumentBlock 列表。

使用 comrak。支持 heading/paragraph/list/code block/blockquote/table/image/link/horizontal rule。每个 block 必须有稳定 block_id。

非目标：不要求完整富文本编辑、不要求直接输出最终 UI。

验收标准：能读取 .md 文件、能输出 DocumentBlock[]、heading/list/code/table/image 有基础支持、block_id 稳定生成、有 fixture 测试

把 Markdown 文件解析成统一 DocumentBlock 列表。使用 comrak。支持 heading/paragraph/list/code block/blockquote/table/image/link/horizontal rule。每个 block 必须有稳定 block_id。非目标：不要求完整富文本编辑、不要求直接输出最终 UI。验收标准：能读取 .md 文件、能输出 DocumentBlock[]、heading/list/code/table/image 有基础支持、block_id 稳定生成、有 fixture 测试

wangdl added this to the M1：Document Core v0.1 milestone 2026-05-30 19:49:00 +08:00

wangdl added the

priority:p0

type:implementation

area:markdown

labels 2026-05-30 19:49:00 +08:00

wangdl commented

2026-05-30 20:51:26 +08:00

完成项

✅ parse_markdown(md_content) 已实现，返回 Vec
✅ GFM 扩展已启用：表格、删除线、任务列表、tagfilter
✅ 11 种 block 类型全部支持

Block 支持

Block	状态	说明
Heading	✅	1-6 级标题
Paragraph	✅	空段落跳过
List (ordered)	✅	有序列表
List (unordered)	✅	无序列表
CodeBlock	✅	带语言标注
Quote	✅	引用块
Table	✅	GFM 表格，自动跳过分隔行
Image	✅	从段落中提取独立图片块，含 alt 文本
HorizontalRule	✅	---
InlineImage	✅	段落中仅含图片时提升为独立 Image block

技术细节

添加 gfm_options() 启用 comrak extension: table/strikethrough/tagfilter/tasklist
block_id() 使用 UUID v4
collect_text() 遍历子树提取纯文本（处理 SoftBreak/LineBreak/Code）
extract_image_from_paragraph() 检测段落中仅有图片的情况，提升为独立 block

测试

20 个单元测试全部通过（11 个 markdown + 9 个 material_type）
覆盖：空文档、标题、段落、有序/无序列表、代码块、引用、表格、分割线、图片、复合文档

待跟进

⬜ DOC-103 TXT 文本读取
⬜ 后续可增加 100+ 行 Markdown fixture 测试

## 完成项 ✅ parse_markdown(md_content) 已实现，返回 Vec<DocumentBlock> ✅ GFM 扩展已启用：表格、删除线、任务列表、tagfilter ✅ 11 种 block 类型全部支持 ## Block 支持 | Block | 状态 | 说明 | |-------|------|------| | Heading | ✅ | 1-6 级标题 | | Paragraph | ✅ | 空段落跳过 | | List (ordered) | ✅ | 有序列表 | | List (unordered) | ✅ | 无序列表 | | CodeBlock | ✅ | 带语言标注 | | Quote | ✅ | 引用块 | | Table | ✅ | GFM 表格，自动跳过分隔行 | | Image | ✅ | 从段落中提取独立图片块，含 alt 文本 | | HorizontalRule | ✅ | --- | | InlineImage | ✅ | 段落中仅含图片时提升为独立 Image block | ## 技术细节 - 添加 gfm_options() 启用 comrak extension: table/strikethrough/tagfilter/tasklist - block_id() 使用 UUID v4 - collect_text() 遍历子树提取纯文本（处理 SoftBreak/LineBreak/Code） - extract_image_from_paragraph() 检测段落中仅有图片的情况，提升为独立 block ## 测试 - 20 个单元测试全部通过（11 个 markdown + 9 个 material_type） - 覆盖：空文档、标题、段落、有序/无序列表、代码块、引用、表格、分割线、图片、复合文档 ## 待跟进 ⬜ DOC-103 TXT 文本读取 ⬜ 后续可增加 100+ 行 Markdown fixture 测试

wangdl closed this issue

2026-05-30 22:00:57 +08:00

wangdl commented

2026-06-02 19:56:01 +08:00

补充：FFI 已暴露

✅ parseMarkdown(content:) → [DocumentBlock] 已通过 UDL 导出
✅ Swift 可调用，返回 8 种 block 枚举值
✅ DocumentBlock 已在 UDL 定义为 [Enum] interface

Swift 调用示例：

let blocks = try parseMarkdown(content: mdString)
for block in blocks {
    switch block {
    case .heading(_, let level, let text): ...
    case .paragraph(_, let text): ...
    case .list(_, let ordered, let items): ...
    case .codeBlock(_, let language, let code): ...
    case .quote(_, let text): ...
    case .table(_, let headers, let rows): ...
    case .imageBlock(_, let src, let alt): ...
    case .horizontalRule: ...
    }
}

## 补充：FFI 已暴露 ✅ ``parseMarkdown(content:)`` → ``[DocumentBlock]`` 已通过 UDL 导出 ✅ Swift 可调用，返回 8 种 block 枚举值 ✅ ``DocumentBlock`` 已在 UDL 定义为 ``[Enum] interface`` Swift 调用示例： ```swift let blocks = try parseMarkdown(content: mdString) for block in blocks { switch block { case .heading(_, let level, let text): ... case .paragraph(_, let text): ... case .list(_, let ordered, let items): ... case .codeBlock(_, let language, let code): ... case .quote(_, let text): ... case .table(_, let headers, let rows): ... case .imageBlock(_, let src, let alt): ... case .horizontalRule: ... } } ```

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: wangdl/zhixi-document-runtime#7