跳转至

Markdown 软换行模块契约

契约一览

领域 契约
公开契约 markdownSoftBreaksPlugin 是 @astryxdesign/core/Markdown/plugins 导出的一种持久的第一方插件值。
行为 符合条件的短语内容中,每个软 LF、CRLF 或独立 CR 行结尾都会成为规范的 Markdown break 节点,并通过 Astryx 的适配器与真实插件保持一致。
最终用户影响 读者能看到作者预期的换行,而无需两个尾随空格,同时受保护的内容保持原样且可复制。
构建者影响 构建者只需向 plugins 添加一个值即可启用;无需设置项或渲染器插槽。
兼容性 增量和可选;省略或空的插件列表保留已发布的解析器、DOM、可访问性和流式行为。
审查检查 拒绝缺少 remark-breaks 链接标签对等性的情况;拒绝在代码、图片、引用、数学或扩展节点内部进行匹配;拒绝源代码预处理;拒绝自定义渲染器;或拒绝在完整输入与流式输入之间行为不一致的情况。
治理规则 spec:AST-036 FR1–FR17, FR21–FR24, FR36, FR38, FR40;component:Markdown FR12–FR16, FR21。

此表是审查投影;正文为权威内容。

意图

收到带有有意义的单行结尾的正文的构建者,应能在不重写源代码或更改 Markdown 解析器的情况下,将这些结尾渲染为换行(break)。该插件被刻意固定:一种稳定的行为使其易于识别、基准测试,并可替换为经过适配的 remark-breaks 变换。

兼容性与迁移

  • 已发布默认行为保留:yes
  • 兼容性类别:增量和可选
  • 迁移决策:spec:AST-036/DEC-11

所有权边界

拥有

  • 导出的插件值及其稳定插件名称。
  • 将符合条件的软行结尾转换为内置的 break 节点。
  • 完整、流式、SSR、Storybook 对等性和浏览器性能证据。

不拥有 / 非目标

  • 解析或渲染新的扩展节点。
  • 内联/围栏代码、图片、引用、数学或扩展节点中的不透明行结尾。
  • CSS 空白行为或源代码预处理。
  • 已使用 Markdown 的两个空格或反斜杠语法编写的硬换行(hard breaks)。

公共 API 与概念

概念 封闭值或状态 含义 默认值 所有者 稳定性
markdownSoftBreaksPlugin 一个 MarkdownPluginEntry<never> 通过公共变换协议转换符合条件的软结尾。 不存在 module:Markdown/softBreaks 稳定
符合条件的结尾 短语文本内的 LF、CRLF 或独立 CR,包括链接标签 替换为一个内置的 break 节点。 字面软结尾 module:Markdown/softBreaks 稳定
不透明上下文 代码、图片、引用、数学或扩展内容 保持为逐字节内容,而不是变成换行。 受保护 component:Markdown 稳定

行为契约

ID 不变量 依据
FR1 每个符合条件的 LF、CRLF 或独立 CR 结尾都会恰好成为一个规范的 break 节点。 spec:AST-036 FR1, FR9
FR2 该插件仅使用 createMarkdownPlugin() 和公共的不可变变换契约,不引入任何扩展节点或渲染器。 spec:AST-036 FR1, FR40
FR3 链接标签正文进行变换以实现 remark-breaks 对等性;内联和围栏代码、图片、引用、数学和扩展节点保持不透明。 spec:AST-036 FR7, FR15
FR4 省略或空的插件列表保留已发布的软结尾行为。 spec:AST-036 FR2, FR3
FR5 每个流式前缀都是确定性的,最终的流式树等同于相同输入的完整解析结果。 spec:AST-036 FR13, FR36
FR6 没有换行的输入返回原始树,且不分配替换节点。 spec:AST-036 FR21, FR23
FR7 原生输出与针对所支持 Astryx 子集的适配后 remark-breaks 转换相匹配。 spec:AST-036 FR20, FR40

可访问性约定

  • AR1 — 阅读顺序保持源顺序。 软换行不会添加焦点目标,也不会在语义容器之间移动文本。
  • AR2 — 链接含义保持完整。 链接目标和可访问名称保留其源文本,而视觉换行与 remark-breaks 匹配。

设计关系

软换行不增加任何结构或样式。现有的 Markdown 段落和换行渲染仍保持权威性。

父级与系统关系

  • component:Markdown 负责解析、受保护上下文、渲染和回退。
  • spec:AST-036 负责插件协议和第一方对等性要求。
  • module:Markdown/remark 负责适配后的 remark-breaks 对比路径。

内容边界

本模块仅识别符合条件的规范措辞文本中已存在的 LF、CRLF 和孤立 CR 字符。它不会检查或保留转换调用之外的文档内容。

验证映射

契约 验证 代表性状态 失败预期
FR1–FR4 softBreaks.test.tsx AST 与 SSR 测试夹具 LF、CRLF、孤立 CR、散文、强调、多行链接、行内代码、围栏、作者编写的硬换行、无插件 额外、缺失、不透明上下文、双倍硬换行或默认路径换行均会导致失败。
FR5 softBreaks.test.tsx 前缀序列 流式行结束之前、之时和之后 输出振荡或最终不匹配会导致失败。
FR6 softBreaks.test.tsx 同一性覆盖与 Markdown Perf 无声明配置 无换行 对不存在的源分配已更改的树会导致失败。
FR7 Storybook 原生/适配对等性故事 散文、强调、多行链接、受保护代码 若 DOM 出现分歧则失败。
性能 针对软换行工作负载的 Markdown Performance 成对空/插件运行 无、稀疏和密集声明;完整模式和流式模式 成对运行间源不同、缺少基线增量或缺少密度控制会阻止验收。

决策日志

DEC-1 — 交付一个固定插件值

参考: module:Markdown/softBreaks/DEC-1 决策者: cixzhang, 2026-09-22

软换行只有一种既定含义,不需要产品特定的数据或呈现。固定值使 API 比工厂函数更小,因为后者的选项不会改变行为。

被拒绝的方案:源预处理;Markdown 上的布尔值;渲染器回调;没有有意义配置的工厂函数。

未决问题

无。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx