parseOutlineFromMarkdown 模块契约¶
意图¶
parseOutlineFromMarkdown 与 useOutlineFromMarkdown 从相同的 Markdown 解析配置、有序不可变转换、文本投影以及碰撞分配器(这些配置也用于渲染文档)中派生同文档标题导航。该独立模块只负责这一工具行为,而不决定 Outline 组件的结构或主题。
兼容性与迁移¶
- 发布默认保留:
yes - 兼容性类别:附加解析器选项;不带插件调用时保留已发布的标签、层级、ID 与返回类型
- 迁移决策:
spec:AST-036
所有权边界¶
拥有
- 从 Markdown 标题中派生有序的
OutlineItem值。 - 接受与 Markdown 相同的解析影响选项和有序插件列表。
- 在选择标题之前应用相同的、经过验证的不可变转换。
- 使用与 Markdown 标题渲染相同的扩展文本投影和碰撞安全 slug 分配器。
不拥有 / 非目标
- Outline 组件结构、激活状态、目标、布局或主题。
- 插件渲染、块扩展导航条目或渲染器派生文本。
- 第二个解析器、插件注册表或独立的标题 ID 策略。
公开 API 与概念¶
parseOutlineFromMarkdown(source, options?) 执行直接派生。
useOutlineFromMarkdown(source, options?) 为 React 调用者记忆化同样的派生过程。
options.plugins 使用规范的、不透明的 Markdown 插件条目。在标题选择之前运行相同的有序转换;随后,内联扩展节点的 toText 投影会为标题标签和 ID 提供内容。当同一个第一方条目同时安装在这两个表面上时,本模块消费 module:Markdown/headingLinks 所拥有的投影;它不会复制该模块的选项或行为。
行为契约¶
| ID | 不变量 | 依据 | 验收与实现状态 |
|---|---|---|---|
| FR1 | 两个工具都接受与渲染后的 Markdown 文档相同的 Markdown 解析器选项和有序插件列表。 | spec:AST-036 FR13, FR16 |
当前实现 |
| FR2 | 两个工具在选择标题之前都应用相同的、经过验证的不可变转换,且不允许渲染器输出影响身份。 | spec:AST-036 FR13, FR16 |
当前实现 |
| FR3 | 插件启用的标签和 ID 使用与 Markdown 相同的扩展 toText 投影、slugger 和跨基线碰撞分配器,从而生成唯一匹配的目标。 |
spec:AST-036 FR16 |
当前实现 |
| FR4 | 扩展节点绝不会自行创建 Outline 条目。Outline 选择始终保持在根节点级别;当安装了 module:Markdown/headingLinks 时,本模块消费其独立拥有的身份投影,而不会重述或修改该契约。容器绝不会重启或独立限制所选投影的范围。它也不会在此处产生嵌套的 Outline 条目。 |
module:Markdown/headingLinks |
当前实现 |
| FR5 | 省略插件与传入空列表都会保留已发布的标题选择、标签、层级、ID、返回类型和记忆化行为。 | spec:AST-036 FR2 |
当前实现 |
| FR6 | 该 hook 会根据 source 以及每一个影响解析或影响转换的选项进行记忆化,因此配置变更不会返回过期的标题。 | component:Markdown FR15–FR16 |
当前实现 |
| FR7 | 当转换移除某个标题时,其 Outline 条目也会被移除;当转换插入一个合成标题时,会新增一个条目,且两种表面上的行为一致。标题深度由 source 决定,无法改变,因此条目的层级始终与渲染后的标题匹配。 | spec:AST-036 FR26 |
当前实现 |
| FR8 | 当插件失败时,派生过程使用与渲染文档相同的最后一个有效根节点,因此标签、层级和 ID 仍然保持一致。失败通过共享诊断通道上报;本模块不会添加任何自身的失败模式、回退或抛出行为。 | spec:AST-036 FR12, FR29 |
当前实现 |
| FR9 | 派生过程在规范树上通过共享解析路径运行,且不需要 DOM、渲染器、客户端边界或第二个解析器。由于转换在流式处理下是幂等的,从不断增长的源前缀派生出的 outline 会收敛而非振荡。 | spec:AST-036 FR32, FR33, FR36 |
当前实现 |
转换与优先级顺序¶
Markdown 解析配置 → 有序的不可变转换 → 标题节点 → 共享的可感知文本投影 → 选定的标题投影 → 根标题选择 → Outline 项。
性能与资源¶
- 该 hook 仅在源或解析器/转换配置发生变化时重新计算。
- 渲染器输出不参与标题身份判定。
- 不需要 DOM、渲染器挂载、注册表、Remark 运行时或可选插件资源。
无障碍契约¶
每个派生标签都是用于 Markdown 身份判定的同一可感知标题文本,并且每个派生 ID 都指向匹配的已渲染标题。此模块不添加任何交互或 ARIA 行为;导航呈现由 Outline 组件负责。
设计关系¶
此解析工具不拥有任何视觉呈现。
父级与系统关系¶
component:Markdown负责聚合解析、标题渲染,以及通用的共享投影调用接缝。module:Markdown/headingLinks负责其可选投影;本模块使用该投影,同时保留仅限根级别的 Outline 选择。spec:AST-036负责规范插件协议和跨渲染面一致性。component:Outline负责呈现、结构和主题。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 |
|---|---|---|---|
| FR1–FR6 | Outline 解析器测试、插件转换一致性测试、heading-links 模块测试以及 Core 类型检查 | 省略/空/已安装的插件列表;选定的投影发生变化;经转换和格式化后的根标题;根级/嵌套容器 | 某个转换被跳过、某个根级标签/ID 偏离 Markdown、嵌套标题进入 Outline、选定的投影过期,或默认输出发生改变。 |
| FR7–FR9 | 标题插入/移除一致性、失败一致性,以及流式派生 | 带/不带章节移除标题;插入合成标题;转换失败;不断增长的源前缀;服务端派生 | Outline 与文档不一致、回退出现分歧、抛出异常、ID 过期,或出现流式振荡。 |
决策日志¶
DEC-1 — Markdown 拥有标题身份;Outline 对其进行投影¶
引用: module:Outline/parseOutlineFromMarkdown/DEC-1
决策者: cixzhang, 2026-09-15
Outline 工具使用 Markdown 的解析配置、有序转换、文本投影和冲突分配器,而不是定义第二套标题身份系统。这样可保持标签和链接目标一致,同时避免将插件渲染器输出与导航身份耦合。
DEC-2 — 一次遍历即可应对容器和标题编辑¶
引用: module:Outline/parseOutlineFromMarkdown/DEC-2
决策者: cixzhang, 2026-09-16
扩展容器包含普通 Markdown,但不会选择第二套身份系统。Markdown 与本模块使用由已安装插件列表选定的同一投影,因此 Outline 绝不会链接到 Markdown 未识别的根标题。Outline 结果仍然仅限根级,扩展节点永远不会成为 Outline 条目。
转换可能会移除和插入标题,因此 Outline 跟随渲染后的文档而非源代码:被移除的根标题会消失,被插入的根标题会出现,而基于不可变源的深度可保持层级对齐。两个渲染面运行同一条流水线,而不是各自独立的规则。
已否决:仅容器的遍历例外;扩展节点作为 Outline 条目;仅基于源的派生;模块级插件失败回退。
未决问题¶
无。
内容边界¶
本文件不重复插件协议细节、Markdown 解析器机制、使用方示例,或 Outline 组件的结构与主题契约。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx