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