mdom 0.2.0 → 0.4.0

data/USAGE.md

@@ -0,0 +1,864 @@
+# mdom 使用指南
+
+`mdom` 是 [CSM（Complex Simple Markup）](docs/CSM.md) 的 Ruby 工具链：把 CSM 文档
+解析成一棵文档树（AST），再翻译为 Ruby 源码或 HTML。
+
+本文只讲**怎么用**。语言规格见 [docs/CSM.md](docs/CSM.md)，实现方案见
+[docs/IMPLEMENTATION.md](docs/IMPLEMENTATION.md)，项目状态见 [README.md](README.md)。
+
+> **当前可用范围**：(1) 解析、(2) 翻译、(6) HTML 序列化已经实现；(3)(5) `to_markdown`
+> 未实现；(4) 执行不在 mdom 范围内——它就是宿主的一行 `eval`。
+
+## 目录
+
+- [1. 引入](#1-引入)
+- [2. 五分钟上手](#2-五分钟上手)
+- [3. 解析（(1)）：`MDOM::Parser`](#3-解析1mdomparser)
+- [4. 读树与改树：`MDOM::Node`](#4-读树与改树mdomnode)
+- [5. 行内解析：`MDOM::InlineParser`](#5-行内解析mdominelineparser)
+- [6. 构造：`MDOM::Builder`](#6-构造mdombuilder)
+- [7. 翻译成 Ruby（(2)）：`MDOM::Translator`](#7-翻译成-ruby2mdomtranslator)
+- [8. 执行（(4)）：宿主的一行 `eval`](#8-执行4宿主的一行-eval)
+- [9. 序列化成 HTML（(6)）：`MDOM::HtmlSerializer`](#9-序列化成-html6mdomhtmlserializer)
+- [10. 序列化成 CSM（(3)(5)）：`MDOM::MarkdownSerializer`](#10-序列化成-csm35mdommarkdownserializer)
+- [11. 钩子与回调（CSM §5.3）](#11-钩子与回调csm-53)
+- [12. 错误](#12-错误)
+- [13. 边界与注意事项](#13-边界与注意事项)
+- [14. 配方](#14-配方)
+
+## 1. 引入
+
+可以引总入口，也可以按阶段引：
+
+```ruby
+require "mdom"                 # 总入口：加载全部，并给出 MDOM.parse / MDOM.compile
+
+# 只用到某一段时，用哪个引哪个：
+require "mdom/parser"          # (1) 解析：Parser / Tokenizer / BlockDetector / InlineParser
+require "mdom/translator"      # (2) 翻译
+require "mdom/builder"         # 构造 DSL + 钩子（零 gem 依赖，可在 mruby/WASM 上跑）
+require "mdom/html_serializer" # (6) HTML 序列化（零 gem 依赖）
+```
+
+依赖上分两侧：**解析侧**（`parser` / `translator`）硬依赖
+[`prism`](https://github.com/ruby/prism)（Ruby 3.3 起随发行版提供）；**builder 侧**
+（`builder` / `html_serializer` 及其依赖的节点定义）零 gem 依赖。
+
+## 2. 五分钟上手
+
+```ruby
+require "mdom/parser"
+require "mdom/html_serializer"
+
+document = MDOM::Parser.parse(<<~CSM)
+  # 标题
+
+  正文 **加粗** 与 [链接](https://example.com)。
+
+  - 一
+  - 二
+CSM
+
+document.class            # => MDOM::Node::Document
+document.children.map(&:type)
+# => [:heading, :paragraph, :list]
+
+puts MDOM::HtmlSerializer.serialize(document)
+# <article>
+# <h1 id="标题">标题</h1>
+# <p>正文 <strong>加粗</strong> 与 <a href="https://example.com">链接</a>。</p>
+# <ul>
+# <li>
+# <p>一</p>
+# </li>
+# <li>
+# <p>二</p>
+# </li>
+# </ul>
+# </article>
+```
+
+想让一次调用把三份产物都拿到（并顺便跑钩子），用总入口：
+
+```ruby
+result = MDOM.compile("- 一\n")
+result.class    # => MDOM::Compiled
+result.ruby     # (2) 的 Ruby 源码
+result.html     # (6) 的 HTML
+result.meta     # 文档元数据（Hash）
+```
+
+想要 Ruby 源码，把 `HtmlSerializer` 换成 `Translator`：
+
+```ruby
+require "mdom/translator"
+
+puts MDOM::Translator.to_ruby(MDOM::Parser.parse("- 一\n- 二\n"))
+# builder = MDOM::Builder.new
+# builder.list(ordered: false, task: false, marker: "-") do
+#   builder.item(marker: "-") do
+#     builder.paragraph do
+#       builder.text("一")
+#     end
+#   end
+#   builder.item(marker: "-") do
+#     builder.paragraph do
+#       builder.text("二")
+#     end
+#   end
+# end
+# builder.to_document
+```
+
+## 3. 解析（(1)）：`MDOM::Parser`
+
+```ruby
+document = MDOM::Parser.parse("# 标题\n")
+document.class   # => MDOM::Node::Document
+```
+
+### 3.1 树长什么样
+
+根是 `Document`，`children` 是顶层块。段落、标题等**行内容器**的行内节点挂在
+`children` 上：
+
+```ruby
+heading = MDOM::Parser.parse("# 标题 **粗**\n").children.first
+
+heading.type                # => :heading
+heading.level               # => 1
+heading.text                # => "标题 **粗**"   （原文）
+heading.children.map(&:type) # => [:text, :strong]
+heading.attributes[:text]   # => "标题 **粗**"   （与 text 同源）
+```
+
+`attributes[:text]` 保留**未做行内解析的原文**，行内节点才是给下游用的结构。
+
+### 3.2 FLOW / PHRASING 边界
+
+节点直接承载什么，取决于 CSM 元素表里的**内容策略**：
+
+- **PHRASING 容器**（段落 `paragraph`、标题 `heading`、定义术语 `term`、引用来源
+  `cite`、表格单元格 `table_header_cell` / `table_cell`）直接收**行内节点**；
+- **FLOW 容器**（引用 `blockquote`、列表项 `list_item`、定义 `definition`、节块
+  `div`）只收**块级节点**——正文先成为一个段落。
+
+```ruby
+quote = MDOM::Parser.parse("> 引用 **粗**\n").children.first
+
+quote.children.map(&:type)                # => [:paragraph]
+quote.children.first.children.map(&:type) # => [:text, :strong]
+quote.text                                # => "引用 **粗**"   （派生的便捷读法）
+```
+
+列表项同理，所以 `- 项` 的结构是 `list → list_item → paragraph → text`。
+
+### 3.3 几个有用的选项
+
+```ruby
+# 只做块结构，跳过行内解析（快；代价是行内容器只剩 attributes[:text]）
+MDOM::Parser.parse("# 标题\n", inline: false).children.first.children # => []
+
+# 关掉 A 类（自由块）判定：英文散文文档里逐行交给 Prism 增量 parse 很贵
+MDOM::Parser.parse("list.each do |x|\n  y\nend\n", free_blocks: false)
+  .children.map(&:type)  # => [:paragraph, :paragraph, :paragraph]
+
+# 只对行首标识符命中的行尝试 A 类判定（String 精确相等，Regexp 自己写规则）
+MDOM::Parser.parse(src, free_blocks_allowed: ["list", /^\w+\.each\b/])
+
+# 也可以换掉块判定器——此时开关要配在判定器自己身上
+MDOM::Parser.parse(src, detector: MDOM::BlockDetector.new(free_blocks: false))
+```
+
+**A 类（自由块）判定的开销与闸门。** `list.each do |x| … end` 这类块没有引导
+关键字，只能交给 Prism 判定（CSM §3.5）；而英文散文里「以字母开头的行」比比皆是，
+逐行做增量 parse 会让一篇普通文档产生几百到上万次 Prism 调用。于是 A 类判定可关、
+可白名单：**关掉或未命中白名单的行按排版处理**（CSM §3.5.3，不报错），B 类（引导
+关键字）与 `~` 行**不受影响**。
+
+| 选项 | 默认 | 语义 |
+|------|------|------|
+| `free_blocks:` | `true` | `false` 时不做任何 A 类判定 |
+| `free_blocks_allowed:` | `nil` | 白名单（`Array<String \| Regexp>`）；`nil` 表示不限制，`[]` 等价于 `false` |
+
+白名单的 `String` 元素与**行首标识符**精确相等（大小写严格：`"list"` 命中
+`list.each do`，不命中 `lists.each do`）；`Regexp` 元素对**已剥离 CSM 缩进的整行**
+做 `match?`，要不要锚定行首由自己写的 `\A` 决定。缩进不参与门控——任意层级都按
+同一规则判定。代价是：被关掉的行不再触发 `CrossLevelError` 之类的缩进校验（那是
+「已判定为块」之后的检查，见下一节 §3.4）。
+
+### 3.4 解析期报错
+
+非法输入会抛 `MDOM::ParseError` 的子类,消息里带**文档行号**：
+
+~~~ruby
+MDOM::Parser.parse("    list.each do |x|\n      y\n  end\n")
+# => MDOM::CrossLevelError: ruby block opens with 4 space(s) of indentation (line 1)
+#                            but closes with 2 (line 3)
+
+MDOM::Parser.parse("```ruby\nx = 1\n")
+# => MDOM::UnclosedFenceError: unclosed code fence opened at line 1
+~~~
+
+## 4. 读树与改树：`MDOM::Node`
+
+所有节点都继承 `MDOM::Node::BaseNode`，能力分散在若干 mixin 里（见
+`lib/mdom/node.rb` 的模块说明）。三条**不变式**由变更方法共同维护：
+
+1. 一个子节点在同一时刻只属于一个父节点；
+2. `parent` 与 `children` 双向一致；
+3. 子树的 `depth` 始终与实际位置一致。
+
+### 4.1 导航
+
+```ruby
+document = MDOM::Parser.parse("- 一\n- 二\n")
+list  = document.children.first
+item  = list.children.last
+
+document.root.equal?(document)   # => true      （根节点）
+item.ancestors                   # => [list, document]（由近到远）
+item.position                    # => 1         （在父节点子列表中的下标）
+list.index(item)                 # => 1         （某个子节点的下标；不是子节点则为 nil）
+list.first_child.type            # => :list_item
+list.last_child.equal?(item)     # => true
+item.siblings.map(&:type)        # => [:list_item, :list_item]（含自身的副本）
+item.previous_sibling.equal?(list.first_child) # => true
+
+list.leaf?                       # => false
+list.children?                   # => true
+item.leaf?                       # => false     （它有段落）
+document.ancestor_of?(item)      # => true      （自身不算自己的祖先）
+```
+
+### 4.2 遍历
+
+`each` 是**先序深度优先**，并且**含自身**——所以 `Enumerable` 的 `map` / `select` /
+`count` 覆盖的是**整棵子树**，而不是直接子节点：
+
+```ruby
+document = MDOM::Parser.parse("- 一\n- 二\n")
+
+document.count                   # => 整棵树的节点数
+document.map(&:type).uniq        # => [:document, :list, :list_item, :paragraph, :text]
+document.select(&:leaf?)         # => 所有叶子
+```
+
+只想访问直接子节点时，直接用 `children`。
+
+### 4.3 改树
+
+下面这些是**方法清单**（`node` / `relative` 等是占位符，不是变量）：
+
+~~~text
+doc << para                 # 追加（返回 self，可链式）
+doc.append(a, b)            # 依次追加多个
+doc.prepend(node)           # 插到最前
+doc.insert(0, node)         # 指定位置：支持负索引，0 是最前，children.size 是末尾
+doc.insert_before(node, relative)  # 插到某个**直接子节点**之前
+doc.insert_after(node, relative)   # 之后
+
+doc.remove(node)            # 摘除直接子节点（不是子节点或 nil 时什么都不做）
+doc.extract_at(-1)          # 按下标摘除并返回；越界返回 nil
+node.unlink!                # 让**自己**从父节点完整脱离并重算 depth
+
+doc.replace(child, replacement)    # 顶替一个子节点，保持兄弟顺序
+node.replace_with(other)           # 在父节点里把自己换成 other（返回 other）
+node.wrap_with(wrapper)            # 用 wrapper 包住自己（返回 wrapper）
+node.slide_prev / node.slide_next  # 与前/后一个兄弟交换位置
+~~~
+
+几种常见的错误：
+
+~~~text
+doc << doc                       # => MDOM::Node::CycleError（不能挂到自身或祖先之下）
+doc << nil                       # => ArgumentError
+doc.insert(99, node)             # => IndexError（合法范围是 -children.size-1..children.size）
+MDOM::Node::Document.new.position # => MDOM::Node::RootError（根节点没有位置）
+doc.first_child.slide_prev        # => MDOM::Node::BoundaryError（已是第一个）
+~~~
+
+全部树操作的错误都继承 `MDOM::Node::Error`，可以一次 rescue。
+
+### 4.4 直接用节点类
+
+不想走解析和 DSL 时，各节点类型都能直接构造：
+
+```ruby
+MDOM::Node::Paragraph.new("正文")
+MDOM::Node::Heading.new(2, "标题")
+MDOM::Node::List.new(ordered: true, marker: "1.")
+MDOM::Node::CodeBlock.new("x = 1", lang: "ruby")
+MDOM::Node::TableCell.new("值", align: :right)
+MDOM::Node::Document.new(children: [MDOM::Node::Hrule.new])
+```
+
+完整清单见 `lib/mdom/node/nodes.rb`（块级）与 `lib/mdom/node/inline_nodes.rb`（行内）。
+
+## 5. 行内解析：`MDOM::InlineParser`
+
+把一段**行内文本**解析成节点数组。`Parser` 内部就是用它，也可以单独调用：
+
+```ruby
+MDOM::InlineParser.parse("**粗** 与 `code` 与 [标签](https://a.b)")
+# => [Strong, Text, CodeSpan, Text, Link]
+
+MDOM::InlineParser.parse(%q{[文本](@note) #{Date.today}}).map(&:type)
+# => [:inline_quote, :text, :interpolation]
+```
+
+两个选项：
+
+```ruby
+MDOM::InlineParser.parse("*a*", styles: false)   # 不识别强调/加粗/增删 → 全按字面
+MDOM::InlineParser.parse("a *b*", literal: true) # 只认转义与插值，其余字面
+```
+
+注意它只产出**未求值**的节点：`#{}` 只保存表达式原文，公式只保存 TeX 原文。
+
+## 6. 构造：`MDOM::Builder`
+
+`Builder` 是文档构造 DSL，也可以用来程序化生成文档。
+
+```ruby
+require "mdom/parser"   # 字符串参数要走行内解析，需要解析侧
+require "mdom/builder"
+
+document = MDOM::Builder.build do |b|
+  b.h1 "标题"
+  b.p "正文 *强调*。"
+  b.list do |l|
+    %w[一 二].each { |item| l.item { |i| i.render(item) } }
+  end
+end
+document.children.map(&:type)   # => [:heading, :paragraph, :list]
+```
+
+块参数就是 builder 自身（**显式传参**，不用 `instance_eval`），所以块里既可以用参数
+也可以用外层的 `b`，它们指向同一个对象。
+
+行内内容有两种给法：**字符串参数**（走 `InlineParser`，见 §5），或**结构化构造**
+——给节点参数，或在块里调行内方法。后者不经过解析器，正是翻译产物的形态：
+
+```ruby
+MDOM::Builder.build do |b|
+  b.p do |p|
+    p.text("正文 ")
+    p.strong { |s| s.text("粗") }
+  end
+end.children.first.children.map(&:type)   # => [:text, :strong]
+```
+
+结构化构造的行内容器（段落、标题、术语、引用、单元格）会用 `MDOM::MarkdownSerializer`
+把子节点重建进 `attributes[:text]`，所以 `text` / `cite` 这类读取照常可用。
+
+### 6.1 方法一览
+
+| 组 | 方法 |
+|----|------|
+| 结果 | `to_document`（别名 `finish`）、`document { }` |
+| 标题 | `heading(level, *parts, closed:)`、`h1`–`h6` |
+| 段落 | `paragraph(*parts)`、`p` |
+| 列表 | `list(*items, ordered:, task:, marker:)`、`ul`、`ol` |
+| 列表项 | `item(*parts, marker:, task:, checked:)`、`li`、`task(checked, *parts)` |
+| 引用 | `blockquote(*parts, cite:)`、`quote`、`cite(*parts)` |
+| 代码 | `code_block(code, lang:, params:, fence:)` |
+| 公式 | `math_block(tex)` |
+| 表格 | `table { }`、`row { }`、`header_cell(*parts, align:)`、`cell(*parts, align:)` |
+| 其它块 | `hrule` / `hr`、`division { }` / `div`、`definition_list { }` / `dl`、`term(*parts)`、`definition(*parts)` |
+| 行内 | `text(value)`、`em` / `emphasis`、`strong`、`code_span(value)`、`del`、`ins`、`link(uri, *label, title:)`、`inline_quote(uri, *parts)`、`wiki_link(target, label = nil, *parts)`、`mention(name, kind:)`、`image(uri, *parts, alt:, title:)`、`meter(value, max, *parts)`、`progress(value, max, *parts)`、`math(tex, *parts)`、`hardbreak`、`interpolation(expr)` |
+| 注入 | `render(value, parse:)` |
+
+### 6.2 参数怎么包装
+
+字符串参数的包装方式**取决于容器**（CSM §3.10）：
+
+```ruby
+MDOM::Builder.build { |b| b.p "文本" }.children.first.children.map(&:type)
+# => [:text]        （行内容器 → 文本节点）
+
+MDOM::Builder.build { |b| b.render "文本" }.children.map(&:type)
+# => [:paragraph]   （块级容器 → 段落）
+```
+
+FLOW 容器的 `*parts` 各自成为**一个段落**：
+
+```ruby
+MDOM::Builder.build { |b| b.blockquote("第一段", "第二段", cite: "出处") }
+# blockquote → [paragraph, paragraph, cite]
+```
+
+### 6.3 `render`：值的分派
+
+| 值 | 行内容器中 | 块级容器中 |
+|----|-----------|-----------|
+| `nil` | 忽略 | 忽略 |
+| 节点 | 直接插入（自动从原父脱离） | 同左 |
+| 字符串 | 文本节点 | 段落 |
+| `Array` / `Enumerable` | 逐项递归 | 逐项递归 |
+| 其它 | `to_s` 后同上 | `to_s` 后同上 |
+
+```ruby
+MDOM::Builder.build { |b| b.render %w[a b] }.children.map(&:type)  # => [:paragraph, :paragraph]
+MDOM::Builder.build { |b| b.p { |p| p.render nil } }.children.first.children  # => []
+
+# parse: true 时字符串按 CSM 递归解析，结果的**子节点**逐个插入
+MDOM::Builder.build { |b| b.render "- a\n", parse: true }.children.map(&:type) # => [:list]
+```
+
+### 6.4 `值.render` 与「当前文档」
+
+CSM §3.3 允许在**值**上直接调用 `.render`（`begin ... end.render`）。它靠
+`MDOM::Builder.current` 找到「当前文档」：
+
+```ruby
+builder = MDOM::Builder.new     # 自动成为当前文档
+"文本".render                   # 等价于 builder.render("文本")
+MDOM::Builder.current.equal?(builder)  # => true
+builder.to_document             # 出栈，current 恢复为 nil
+```
+
+**`render` 有没有位置参数都行**（CSM §3.3）：给了位置参数就用它，否则用接收者本身。
+所以块内可以像 `Builder#render` 一样裸写，这正是 `begin ... end` 里最顺手的写法
+（`#{}` 交给 Ruby）：
+
+```ruby
+begin
+  ["a", "b"].each do |item|
+    render "- #{item}", parse: true
+  end
+end
+```
+
+`render(nil)` 仍然是「渲染 nil」（被忽略）；多余的位置参数会抛 `ArgumentError`
+（不静默取第一个）。
+
+`Builder.with(builder) { ... }` 提供显式作用域，`Builder.current` 用来读：
+
+```ruby
+builder = MDOM::Builder.new
+builder.to_document
+
+MDOM::Builder.with(builder) { MDOM::Builder.current.equal?(builder) }  # => true
+MDOM::Builder.current                                                   # => nil
+```
+
+没有当前文档时：
+
+```ruby
+begin
+  "x".render
+rescue MDOM::Error => e
+  e.message   # => "render outside of a document"
+end
+```
+
+> **代价与并发**：`值.render` 定义在 `Object` 上，会给宿主的每个对象加一个 `render`
+> （并覆盖同名方法）；「当前文档」是**类级状态**，所以**并行请用 Ractor**
+> （类实例变量天然隔离），**`Thread` 并行会串上下文**。详见 [13. 边界](#13-边界与注意事项)。
+
+## 7. 翻译成 Ruby（(2)）：`MDOM::Translator`
+
+把 AST 翻成**一段顶层顺序执行的 Ruby 程序字符串**，不绑定执行方式（`eval`、落盘
+`require`、交给 mruby 都行）。
+
+```ruby
+require "mdom/parser"
+require "mdom/translator"
+
+document = MDOM::Parser.parse("- a\n")
+MDOM::Translator.to_ruby(document) == document.to_ruby   # => true
+```
+
+选项：`indent:`（产物缩进宽度，默认 2）、`builder:`（产物里 builder 变量的名字，
+默认 `"builder"`）、`unsafe:`（见下）。
+
+### 7.1 `unsafe`：默认安全
+
+`unsafe` 是**翻译期**参数（CSM §3.14）：
+
+```ruby
+# 源里的 `#{total}` 是 CSM 插值；在 Ruby 字符串里写成 \#{total} 表示「字面的 #」
+source = "~ total = 1\n\n合计 \#{total} 元。\n"
+ast = MDOM::Parser.parse(source)
+
+MDOM::Translator.to_ruby(ast)
+# builder = MDOM::Builder.new
+# # [csm] ruby 嵌入已省略（unsafe: false）
+# builder.paragraph do
+#   builder.text("合计 ")
+#   builder.interpolation("total")
+#   builder.text(" 元。")
+# end
+# builder.to_document
+
+MDOM::Translator.to_ruby(ast, unsafe: true)
+# builder = MDOM::Builder.new
+# total = 1
+# builder.paragraph do
+#   builder.text("合计 ")
+#   builder.interpolation { total }
+#   builder.text(" 元。")
+# end
+# builder.to_document
+```
+
+- **默认 `unsafe: false`（安全）**：嵌入段**不写进产物**——块级嵌入只留一行注释占位，
+  行内插值变成 `builder.interpolation("expr")`（**未求值**的插值节点）。产物静态上
+  不含用户代码。
+- **`unsafe: true`**：嵌入块（`begin…end` / `~` 行）原样注入，行内插值写成
+  `builder.interpolation { expr }`，表达式交 Ruby 求值。
+
+安全模式的产物是**自洽**的：直接执行它不需要外部变量，插值节点保持未求值，于是 HTML
+侧照样按嵌入样式输出（CSM §3.14）。
+
+### 7.2 产物的结构约束
+
+排版段一律经由 `builder.*` 接收者，形式可辨识；嵌入段保持原样、边界明确。所以宿主
+可以判断「这份产物能否在 mruby 上跑」，或者把嵌入段剥离/替换。
+
+## 8. 执行（(4)）：宿主的一行 `eval`
+
+**mdom 不提供求值器**——(4) 就是一次 `eval`：
+
+```ruby
+require "mdom/parser"
+require "mdom/translator"
+require "mdom/builder"   # 产物会用到 MDOM::Builder，也要它来补 Object#render
+
+ast1 = MDOM::Parser.parse("正文\n")
+ast2 = eval(MDOM::Translator.to_ruby(ast1, unsafe: true), binding, "doc.csm", 1)
+
+ast2.class                 # => MDOM::Node::Document
+ast2.children.first.type    # => :paragraph
+```
+
+其它同样合法的途径：写入 `.rb` 后 `require` / `load`；编译成字节码后
+`mrb_load_irep`；或纳入宿主的构建流程。
+
+产物第一行是 `builder = MDOM::Builder.new`，最后一行是 `builder.to_document`，所以
+`eval` 的返回值就是 `Node::Document`（AST2）。
+
+> **安全渲染不需要执行**：默认（`unsafe: false`）时直接拿 AST1 去 `to_html` 就行，
+> 未求值的嵌入会以独立样式输出。
+
+## 9. 序列化成 HTML（(6)）：`MDOM::HtmlSerializer`
+
+```ruby
+require "mdom/parser"
+require "mdom/html_serializer"
+
+document = MDOM::Parser.parse("# 标题\n")
+MDOM::HtmlSerializer.serialize(document) == document.to_html   # => true
+```
+
+AST1 与 AST2 都能喂给它。
+
+### 9.1 自动包裹（CSM §1.2）
+
+- 文档里有 `h1` → 整篇包进 `<article>`；
+- `h2` 把自身到下一个 `h2`（或文末）的内容包进 `<section>`；
+- 标题以**等长** `#` 收尾时（`## 标题 ##`），紧跟的段落与它同处一个 `<hgroup>`。
+
+```ruby
+MDOM::HtmlSerializer.serialize(MDOM::Parser.parse("# 一 #\n\n段落\n\n## 二\n\ntext\n"))
+# <article>
+# <hgroup>
+# <h1 id="一">一</h1>
+# <p>段落</p>
+# </hgroup>
+# <section>
+# <h2 id="二">二</h2>
+# <p>text</p>
+# </section>
+# </article>
+```
+
+标题的 `id` 锚点来自标题的纯文本，空白连成 `-`。
+
+### 9.2 WikiLink 与 `known_targets`
+
+```ruby
+MDOM::HtmlSerializer.serialize(MDOM::Parser.parse("[[目标]]\n"))
+# => "<p><a href="目标">目标</a></p>"
+
+# 给出已知目标集合后，不在其中的链接才带 orphan-link
+MDOM::HtmlSerializer.serialize(MDOM::Parser.parse("[[缺失]]\n"), known_targets: ["别的"])
+# => "<p><a href="缺失" class="orphan-link">缺失</a></p>"
+```
+
+**省略 `known_targets` 时不做判定**（也就不会产生 `.orphan-link`）——目标的“存在与否”
+属于宿主的知识，mdom 不猜。
+
+### 9.3 未求值的嵌入
+
+安全模式下没有求值的嵌入仍然会出现在 HTML 里，用的是**与相应代码块同构**的样式，
+另加 `csm-ruby` class：
+
+```ruby
+MDOM::HtmlSerializer.serialize(MDOM::Parser.parse("~ total = 1\n"))
+# => "<pre><code class=\"csm-ruby\">total = 1</code></pre>"
+
+MDOM::HtmlSerializer.serialize(MDOM::Parser.parse("合计 \#{total} 元。\n"))
+# => "<p>合计 <code class=\"csm-ruby\">total</code> 元。</p>"
+```
+
+`__END__` 之后的 Back Matter 不参与 HTML 输出（CSM §4）。
+
+## 10. 序列化成 CSM（(3)(5)）：`MDOM::MarkdownSerializer`
+
+同一个方法服务两种输入状态（CSM §6）：
+
+| 输入 | 嵌入节点 | 输出 | 保真 |
+|------|----------|------|------|
+| **AST1** | 还留着源码原文 | 原样回吐源码 | **保真往返** |
+| **AST2** | 已被求值结果替换 | 只有结果 | **降级**（无法还原成 Ruby） |
+
+```ruby
+require "mdom/parser"
+require "mdom/markdown_serializer"
+
+document = MDOM::Parser.parse("# 标题\n\n- 一\n- 二\n")
+document.to_markdown
+# => "# 标题\n\n- 一\n- 二"
+
+MDOM::MarkdownSerializer.serialize(document)   # 与上面等价
+```
+
+**从结构重建，不读原文缓存。** `attributes[:text]` 只是缓存，序列化看的是行内节点——
+所以改过的树，输出会反映改动：
+
+```ruby
+heading = document.children.first
+heading.children.replace(MDOM::InlineParser.parse("改过的"))
+document.to_markdown
+# => "# 改过的\n\n- 一\n- 二"
+```
+
+**保守转义。** 文本里凡是可能重新触发解析的字符都会被转义：
+
+```ruby
+MDOM::Parser.parse("含 * 与 ` 与 [ 的文本\n").to_markdown
+# => "含 \\* 与 \\\` 与 \\[ 的文本"
+```
+
+代价是输出比手写的 CSM 更谨慎，换来的是「内容不会被自己的标记重新解析」这一稳定性质。
+
+**缩进按节点深度重建**（4 空格一级）。嵌入块在 AST 里只存「已剥离块首缩进」的字符串
+（CSM §3.6），回吐时按树中位置重新缩进——所以块内相对缩进保留，CSM 层级被剥掉：
+
+```ruby
+MDOM::Parser.parse("    begin\n      q = \"Hi\"\n    end.render\n").to_markdown
+# => "begin\n  q = \"Hi\"\nend.render"
+```
+
+**往返验收是「树形相同 + 序列化幂等」**，不是逐字节还原——软换行、多余缩进本来就不
+承载语义。输出**不带**末尾换行。
+
+## 11. 钩子与回调（CSM §5.3）
+
+`MDOM.compile` 会在**五个点**上触发注册的回调：
+
+| 点 | 时机 | 载荷 |
+|----|------|------|
+| `:after_parse` | 解析完成、行内已解析 | `doc` |
+| `:before_compile` | 翻译之前——**树仍可改写** | `doc` |
+| `:after_compile` | 翻译完成 | `doc`、`ruby` |
+| `:before_serialize` | 序列化之前 | `doc` |
+| `:after_serialize` | 序列化之后 | `html`、`meta` |
+
+```ruby
+require "mdom"
+
+MDOM::Node::Document.register_hook :before_compile do |doc|
+  doc.meta[:generated_at] = "2026-09-25"
+end
+
+MDOM::Node::Document.register_hook :after_serialize do |html, meta|
+  html << "\n<!-- generated_at: #{meta[:generated_at]} -->"
+end
+
+result = MDOM.compile("# 标题\n")
+result.meta   # => { generated_at: "2026-09-25" }
+result.html   # 结尾多出那行注释
+```
+
+**回调的返回值被忽略**——要改东西就往载荷里的可变对象上改（节点树、`ruby` / `html`
+字符串）。`meta` 就是文档的元数据 Hash（`doc.meta`）。
+
+**只想影响一次调用**时用 `hooks:`：
+
+```ruby
+seen = []
+MDOM.compile("正文\n", hooks: { after_parse: [->(doc) { seen << doc.type }] })
+seen                                    # => [:document]
+MDOM::Hooks.registered(:after_parse)    # => []   （临时钩子不进全局注册表）
+```
+
+执行顺序是**全局（按注册顺序）→ 临时**；未知的点名抛 `ArgumentError`；某个回调抛异常
+会直接传播，其后的回调不再执行。注册表本身也可直接操作：
+`MDOM::Hooks.register` / `unregister` / `clear` / `registered`。
+
+## 12. 错误
+
+| 命名空间 | 基类 | 子类 |
+|----------|------|------|
+| 解析 / 翻译 | `MDOM::Error` | `MDOM::ParseError` → `CrossLevelError`、`UnclosedFenceError`、`UnclosedMathError` |
+| 树操作 | `MDOM::Node::Error` | `RootError`、`BoundaryError`、`CycleError` |
+
+~~~ruby
+begin
+  MDOM::Parser.parse("```ruby\nx = 1\n")
+rescue MDOM::ParseError => e
+  warn e.message        # => unclosed code fence opened at line 1
+end
+~~~
+
+## 13. 边界与注意事项
+
+**两个目标平台。** builder 侧（`builder` / `nodes` / `node` / `html_serializer`）
+只用 mruby 子集、零 gem 依赖，可在 WASM 等受限环境运行；解析侧（`parser` /
+`translator` 等）硬依赖 `prism`，只在 CRuby 上运行。两侧没有调用关系。
+
+**「当前文档」是类级状态。** 见 [6.4](#64-值render-与当前文档)：并行请用 **Ractor**
+（类实例变量按 Ractor 隔离）；**`Thread` 并行会串上下文**，不支持。跨文档的并行最终
+应由「按文档依赖关系解算的渲染 DAG」承担，**尚未实现**。
+
+**`render` 的锁。** `Builder#render` 内部持一把互斥锁（CSM §3.3），只保证结构不被
+撕裂、**不保证挂载位置**（「当前容器」是共享的游标栈）；mruby 的默认构建没有
+`Thread`/`Mutex`，那边退化为无锁。
+
+**UTF-8 / CJK。** CSM 的软换行折叠依赖字符级判断，mruby 需以 `MRB_UTF8_STRING` 构建；
+按字节构建时该规则会降级，属已知限制。
+
+**尚未实现。** Linter、跨文档组合；CSM §5.1 的注册宏与 §5.2 的查询引擎。
+`MDOM.compile` 也暂不产出 Markdown（需要时自己调 `node.to_markdown`）。
+
+**heredoc 不能单独成块。** CSM §3.12 的取舍（非 mruby 限制）：写成自由块或在
+`begin...end` 内时，它本身就位于 Ruby 代码中，**自然可用**；单独一行（`sql = <<~SQL`、
+`puts <<~SQL`）则不构成块，按排版处理、不报错。但 heredoc **不能破坏块的缩进**——
+把 body 也缩进到块内，并推荐 Squiggly Heredoc（`<<~`）：它剥掉 body 的公共缩进，
+因此对齐缩进不会改变字符串内容。
+
+## 14. 配方
+
+### 14.1 只做块结构，稍后再解析行内
+
+```ruby
+document = MDOM::Parser.parse("# 标题\n", inline: false)   # 快
+document.children.first.children                             # => []（还没做行内解析）
+document.children.first.attributes[:text]                    # => "标题"（原文仍在）
+
+# 需要行内节点时：重新解析一次原文（或直接用 InlineParser）
+MDOM::Parser.parse("# 标题\n").children.first.children.map(&:type)  # => [:text]
+```
+
+### 14.2 任务列表
+
+```ruby
+ast = MDOM::Parser.parse("- [ ] 待办\n- [x] 完成\n")
+ast.children.first.task?                 # => true
+ast.children.first.children.map(&:checked) # => [false, true]
+
+MDOM::HtmlSerializer.serialize(ast)
+# <ul class="task">
+# <li>
+# <input type="checkbox" />
+# <p>待办</p>
+# …
+```
+
+### 14.3 表格
+
+```ruby
+table = MDOM::Parser.parse("| a | b |\n|:--|--:|\n| 1 | 2 |\n").children.first
+table.children.first.children.map(&:type)   # => [:table_header_cell, :table_header_cell]
+table.children.last.children.map(&:align)   # => [:left, :right]
+
+MDOM::HtmlSerializer.serialize(table)
+# <table>
+# <thead>
+# <tr>
+# <th style="text-align: left;">a</th>
+# <th style="text-align: right;">b</th>
+# </tr>
+# </thead>
+# <tbody>
+# …
+```
+
+### 14.4 公式
+
+```ruby
+# 行内
+MDOM::Parser.parse("$x^2$\n").children.first.children.first.type  # => :math
+# 块级（`$$` 独占一行的包围式也可以）
+MDOM::Parser.parse("$$\nx = 1\n$$\n").children.first.tex           # => "x = 1"
+```
+
+### 14.5 嵌入代码
+
+```ruby
+require "mdom/parser"
+require "mdom/translator"
+require "mdom/builder"
+
+ast = MDOM::Parser.parse(<<~'CSM')
+  ~ total = 1 + 2
+
+  合计 #{total} 元。
+CSM
+
+total = 3
+eval(MDOM::Translator.to_ruby(ast, unsafe: true), binding).to_html
+# => "<p>合计 3 元。</p>"
+```
+
+### 14.6 从已有文档继续构造
+
+```ruby
+document = MDOM::Parser.parse("# 标题\n")
+builder = MDOM::Builder.new(document: document)
+builder.p "追加的段落"
+builder.to_document.children.size   # => 2
+```
+
+### 14.7 程序化生成目录
+
+在 `:before_compile` 里扫标题、造一个列表、插到文档开头——此时树还没被翻译，所以改动能
+同时进 `ruby` 与 `html`：
+
+```ruby
+require "mdom"
+
+MDOM::Node::Document.register_hook :before_compile do |doc|
+  headings = doc.select { |node| node.type == :heading }
+  next if headings.empty?
+
+  toc = MDOM::Builder.build do |b|
+    b.list { |l| headings.each { |h| l.item { |i| i.render(h.text) } } }
+  end
+  doc.prepend(toc.children.first)
+end
+
+result = MDOM.compile("# 一\n\n## 二\n\n正文\n")
+puts result.html
+# <article>
+# <ul>
+# <li>
+# <p>一</p>
+# </li>
+# <li>
+# <p>二</p>
+# </li>
+# </ul>
+# <h1 id="一">一</h1>
+# <section>
+# <h2 id="二">二</h2>
+# <p>正文</p>
+# </section>
+# </article>
+```
+
+`Builder.build` 会返回一个**新文档**，所以取它的 `children.first`（那个列表）再
+`prepend` 到目标文档上；`doc.select` 来自 `Enumerable`，扫的是整棵子树。