Markdown 源代码行模块契约¶
契约一览¶
| 领域 | 契约 |
|---|---|
| 公开契约 | markdownSourceLinesPlugin 是一个固定的第一方插件值,从 @astryxdesign/core/Markdown/plugins 导出。安装后,components 块渲染器会收到可选的 sourceLines prop。 |
| 行为 | 每个 Markdown 渲染的块(包括嵌套块)都携带 data-source-line 和 data-source-line-end:即它们被解析自的、基于 1 的、包含首尾在内的源代码行。内联元素不携带任何此类属性。 |
| 最终用户影响 | 使用宿主的按行寻址功能(查找、高亮、审阅评论)的读者会得到指向确切 Markdown 行的结果,包括列表和引用内部的场景。没有该插件时,一切不变。 |
| 构建者影响 | 构建者通过在 plugins 中添加一个值选择启用。拥有自定义块渲染器的构建者将收到的 sourceLines 放到自己的元素上;插件块渲染器从其节点的 position 读取行。 |
| 兼容性/就绪状态 | 增量且可选启用。省略的或空的插件列表会保持已发布的 AST、DOM、解析成本和流式复用不变。 |
| 审查检查 | 拒绝以下情况:引入 Markdown prop、在内联元素上打标记、在没有插件时提供行功能、Markdown 在自定义或插件输出周围添加包装元素、完整解析与流式解析之间不一致的行,或 DOM 中的偏移。 |
| 管理规则 | spec:AST-036 FR3, FR9, FR15, FR40;component:Markdown FR3, FR12, FR15。 |
此表是审查投影;以下正文具有权威性。
意图¶
将渲染后文档中的某些内容映射回其 Markdown 源代码的宿主(选区、搜索命中、diff 块、评论锚点)需要知道每个渲染块来自哪些源代码行。行是单位,因为 diff、blame 和编辑都按行寻址,而且因为嵌套在列表项或引用中的块虽然有行,却没有连续的字符范围。该模块为 Markdown 渲染的每个块提供其行,因此宿主可以将这些功能构建为插件和宿主代码,而无需分叉渲染器。
兼容性与迁移¶
- 已发布默认值保留:
yes - 兼容性类别:增量且可选启用
- 迁移决策:
module:Markdown/sourceLines/DEC-1
使用方迁移说明属于使用方文档和发布说明。
所有权边界¶
拥有
- 导出的插件值及其稳定的插件名称。
- 在安装了插件时,Markdown 渲染的块上的
data-source-line和data-source-line-end属性,以及传递给components块渲染器的sourceLinesprop。 - 在安装了插件时,带源代码支持的块节点(包括嵌套块)的规范
position上的行号。 - 这些行的完整解析、流式解析和服务端渲染证据。
不拥有 / 非目标
- 聚合插件协议、排序和组合——由
component:Markdown和spec:AST-036拥有。 - 将 DOM 选区或搜索命中映射到行、高亮或任何其他基于这些标记构建的宿主功能——由产品调用点拥有。
- 内联节点、表行或表单元格上的行或列位置。
- DOM 中的字符偏移,以及已发布的
range投影——parseMarkdown(source, {sourceRanges: true})保持其已发布行为。 - 自定义渲染器或插件渲染器拥有的元素;Markdown 不会添加包装元素来在其上放置标记。
公开 API 与概念¶
| 概念 | 封闭值或状态 | 含义 | 默认值 | 所有者 | 稳定性 |
|---|---|---|---|---|---|
markdownSourceLinesPlugin |
一个 MarkdownPluginEntry<never> |
为它被传入到的 Markdown、解析器或 Outline 调用启用源代码行。 | 不存在 | module:Markdown/sourceLines |
稳定 |
| 源代码行 | {start, end}:基于 1 的、包含首尾在内的行号,指向解析器收到的字符串。 |
一个块的自身源所占用的行,从其第一行到最后一个非空行。 | 无 | module:Markdown/sourceLines |
稳定 |
| 带标记的块 | 默认路径上的标题、段落、列表项、代码块、引用、表格、分隔线和块级图片。 | 携带 data-source-line="<start>" 和 data-source-line-end="<end>"。 |
无 | module:Markdown/sourceLines |
稳定 |
sourceLines prop |
在 heading、paragraph、code、blockquote、hr、image 和块级 math 渲染器上的 {start: number, end: number}。 |
被替换块的源代码行,供渲染器放置在自己的元素上。 | 不存在 | module:Markdown/sourceLines |
稳定 |
行为契约¶
| ID | 不变量 | 依据 | 草稿评审状态 |
|---|---|---|---|
| FR1 | 安装插件后,处于任意嵌套深度的每个已标记块都会携带 data-source-line 和 data-source-line-end,其源码行号以十进制整数表示。行内元素、表格行和表格单元格均不携带这两个属性。 |
宿主基于行寻址的功能 | 已确定 |
| FR2 | 行号统计的是解析器所接收的原始字符串中的 LF 和 CRLF 行尾,包括原生 frontmatter 块所占用的行;因此第 1 行就是该字符串的第一行。 | spec:AST-036 FR9 |
已确定 |
| FR3 | 一个块的源码行范围从其首个源码行延伸至最后一个非空源码行,包括其自身的容器标记(>)、列表标记、惰性延续行,以及代码围栏的开闭行。 |
component:Markdown FR23 |
已确定 |
| FR4 | 提供的 components 块渲染器会接收 sourceLines,并由其决定元素是否以及在哪里携带这些属性。Markdown 不会添加包装元素,也不会强制在替换元素上使用这些属性。对于行内数学(display: 'inline')和短语内容中的图片,sourceLines 不存在,因为两者都不是块。 |
component:Markdown FR3 |
已确定 |
| FR5 | 规范树中由源码支持的块节点(包括扩展块和语义围栏提案的节点)会在 position.start 和 position.end 上携带 line,因此插件块渲染器和转换都可以从节点读取行号。 |
spec:AST-036 FR9 |
已确定 |
| FR6 | 流式解析在每个分块边界处都会收敛到同一文本完整解析所产生的行号;当更多文本到达时,已确定的块会保持其行号及其渲染后的元素。 | spec:AST-036 FR15, FR21 |
已确定 |
| FR7 | 未安装插件时,规范树不携带 line,DOM 不携带源行属性,components 渲染器不会收到 sourceLines,解析过程也不会执行任何行号处理。安装后,源码行来自 Markdown 已经执行的唯一一次解析所产生的位置:插件不增加解析遍次,也不进行逐块重新分词;未安装时,不会运行任何位置或行号处理。 |
spec:AST-036 FR2, FR3 |
已确定 |
| FR8 | 该插件不引入任何扩展节点、渲染器、元素、主题目标或源码变更,并且可以按任意顺序与其他所有插件组合使用。 | spec:AST-036 FR40, DEC-11 |
已确定 |
转换与优先级顺序¶
- ORD1 — 行号是解析输出。 核心在解析过程中生成这些行号;转换只能观察由源码支持的节点上的行号,不能生成、移动或伪造它们(
spec:AST-036FR11)。转换创建的节点没有位置,其渲染出的块也不携带标记。
性能与资源¶
- PR1 — 有界成本。 行号处理在既有解析过程中记录,并在完整模式和流式模式下保持在
spec:AST-036FR23 为单个 helper 设置的第一方 helper 预算之内。安装插件时的流式解析与未安装时一样,会精确复用已确定的块。
无障碍契约¶
- AR1 — 仅数据属性。 这些标记不会添加角色、名称、焦点目标或文本,也不会改变阅读顺序。
设计关系¶
该模块不添加任何结构、样式或主题目标。
父级与系统关系¶
component:Markdown负责解析、渲染、components接缝以及回退。spec:AST-036负责插件协议、规范position以及第一方插件规则;DEC-11 允许本模块使用的内部接缝,因为本记录拥有该结果,且空管线保持不变。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 |
|---|---|---|---|
| FR1–FR3 | sourceLines.test.tsx DOM 与 AST 测试夹具 |
每种已标记的块类型;嵌套列表和引用块;惰性延续;CRLF;frontmatter;行内强调;表格 | 缺失、移位或行内的标记会导致失败。 |
| FR4–FR5 | sourceLines.test.tsx 渲染器测试夹具 |
每个 components 块渲染器;插件块渲染器;已认领的语义围栏 |
缺少 sourceLines 的渲染器、由 Markdown 添加的包装器,或没有行的节点,均会导致失败。 |
| FR6 | sourceLines.test.tsx 逐字符流式 |
在每个字符处拆分的顶层、嵌套和围栏块 | 流式行与完整解析结果不一致,或重新挂载已定稿块,均会导致失败。 |
| FR7–FR8 | sourceLines.test.tsx 及现有 Markdown 测试套件 |
省略插件、空列表、带标题链接和软换行的插件 | 未安装插件时出现的任何行、属性或 prop、被改变的默认 DOM,或使用插件再次解析,均会导致失败。 |
| 性能 | Markdown 性能:空/插件配对运行 | 完整模式和流式模式 | 超出单一 helper 预算或丢失已定稿块复用,将阻止验收。 |
决策日志¶
DEC-1 — 源码行作为固定插件值交付¶
参考: module:Markdown/sourceLines/DEC-1
决策者: cixzhang, 2026-10-09
需要源码行的宿主功能会像所有其他 Markdown 功能一样安装一个插件,且该插件只有单一含义,无需任何配置。Markdown 为其渲染的块打上标记,并将这些行交给替换其块的渲染器,因为这些是它唯一拥有的元素;宿主或插件渲染器则将这些行放在自己的元素上。到达 DOM 的是行而非偏移量,因为嵌套块没有连续的范围。
已拒绝的方案:在 Markdown 上添加布尔 prop;在默认路径上为所有渲染器提供 position(这会增加每个调用方的成本);插件 DOM hook(spec:AST-036 已将其排除)。
未决问题¶
无。
内容边界¶
本记录不重复消费者签名或示例、父级解析或渲染机制、基于这些标记构建的宿主功能,或当前的审计结果。它链接到这些内容的规范拥有者。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx