RichText 系统规范中的无损 Markdown 往返¶
意图¶
用户在 RichText 编辑器中打开 Markdown,然后再次导出。如果他们没有更改任何内容,返回的字节与打开时完全一致。如果他们只更改了一部分,他们未触及的每个部分都会按他们编写时的原样返回。不会因为编辑器无法表示它而导致任何源文本消失。
非目标¶
- 提供文档编辑服务的编辑器引擎,以及编辑器读取和写入的存储值。本记录规定的是 RichText 的 Markdown 导入和导出返回什么,以及粘贴后代码块中包含什么(FR3),而非规定产品存储的是 Markdown、编辑器状态还是其他内容。
- 以结构形式渲染哪些构造。
spec:AST-061负责受支持构造的外观及其渲染后的含义。 - 用户编写或更改的内容形式。重新生成的 Markdown 使用生成它的转换器的规范形式。
- 协作、持久化和文档托管。
- 只要满足此契约,等价的内部实现仍然有效。
要求¶
- FR1 — 导出未更改内容时返回原始字节。 导入 RichText 后未经编辑即导出的 Markdown,与输入逐字节相同,适用于任何输入:受支持的、不受支持的和格式错误的。这对
markdownToEditorStateJSON后接editorStateJSONToMarkdown,以及编辑器在加载已导入内容后调用getMarkdown()同样成立。编辑是指用户或调用者对文档内容所做的更改。加载、导入规范化、自动链接、已注册的节点转换、选区、历史记录和其他簿记操作都不是编辑,也不会改变导出结果。 - FR2 — 编辑只重新生成被更改的内容。 编辑之后,内容未被编辑更改的每个顶级块都按原始编写形式导出,包括其后跟随的空白行和空白字符。只有编辑更改或创建的块才以规范形式导出。
- FR3 — 重新生成的 Markdown 即编辑器所显示的内容。 被重新生成的块的 Markdown 再次导入时,与编辑器所显示的结构相同:原本是字面文本的仍然是字面文本,因此以转义的
\#开头的已编辑段落绝不会重新加载为标题。代码块只包含代码,因此富文本粘贴到代码块中会变成纯文本:标题、列表、表格、格式或插件节点都不会嵌套其中。 - FR4 — 文档的外围结构和行尾得以保留。 字节顺序标记以及第一个块之前的任何内容都原样保留,最后一个块之后的字节也随其保留。被重新生成的块保持其编写时使用的行尾风格;新块使用文档中的第一个行尾,若没有则使用 LF,因此导出结果永远不会混入输入中本没有的行尾组合。
- FR5 — 不受支持的源内容被保留,绝不丢弃。 RichText 无法表示为结构的源内容会作为可见的字面文本导入。未触及则按原始编写形式导出(FR1、FR2);被编辑后,它导出用户未删除的每个字符。
- FR6 — 每个随附的转换器都符合要求。 FR1–FR5 适用于 RichText 随附的每个转换器、节点和插件,包括它们注册的转换。调用者的自定义转换器对其未更改的块也会获得同样的保留。
平台支持¶
- 受支持的功能/引擎下限:RichText 的 Markdown 导入和导出运行的任何环境,包括在 Node 中的无头模式。
- 不受支持的行为:无;FR1 和 FR5 覆盖所有输入。
- 浏览器证据:不要求。导入和导出都是字符串进、字符串出。FR3 的粘贴条款在挂载的编辑器中得到验证,该编辑器在 jsdom 中接收编辑器的粘贴命令。
当前状态影响¶
RichText 的 Markdown 导入和导出采用 FR1–FR6。在此契约之前导入的内容不带有其原始编写形式的记录,并会以规范形式导出,直到再次导入为止。
验证¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 |
|---|---|---|---|
| FR1 | 至少 30 个文档的一致性语料库,在无头模式以及通过带有随附插件的挂载编辑器中进行无编辑导入和导出 | 2 空格和 3 空格缩进的嵌套列表;反斜杠转义,如 \#;字符引用,如 ©;带信息字符串和元数据的围栏代码;表格;不受支持的 HTML、引用定义和 setext 标题;尾随空白和缺少最终换行符;autolink 插件下的裸 URL |
任何块以规范形式而非其原始字节导出则失败 |
| FR2 | 同一个语料库,仅编辑一个块 | 在第一个、中间和最后一个块中进行编辑;插入一个新块;删除一个块 | 任何一个未触碰的块若改变了一个字节,则失败 |
| FR3 | 将已编辑的块导出并再次导入;在已挂载的编辑器中,将富文本粘贴到代码块内 | 一个以转义 \# 开头、包含转义 * 和 [,或以 1. 开头的已编辑段落;同时包含 HTML 和纯文本的粘贴、仅含 HTML 的粘贴、从编辑器复制的块,以及一个 Markdown 插件节点 |
重新生成的块在导入后结构不同,或者粘贴后在代码块中残留了元素、装饰器或格式化文本,则失败 |
| FR4 | 信封结构和行尾,未编辑与已编辑两种情况 | 包含字节顺序标记;开头空行;CRLF、LF 以及缺少末尾换行符的情况,同时编辑第一个、中间和最后一个块,并添加一个块 | 丢失任何信封结构字节,或在 CRLF 文档中出现 LF,则失败 |
| FR5 | 不受支持的结构,已编辑和未编辑两种情况 | 原始 HTML 块;引用定义;脚注 | 编辑未删除的字符在导出中缺失,则失败 |
| FR6 | 使用默认转换器和内置插件运行语料库,包括表格和自动链接 | 每个内置转换器都有所体现 | 任何绕过保留机制的内置转换器都失败 |
决策日志¶
DEC-1 — 保留作者的字节¶
参考: spec:AST-062/DEC-1
决策者: cixzhang, 2026-10-06
一份在无人编辑时发生变化的文档会破坏差异比较、审查和对编辑器的信任;规范化形式会丢失作者所选择的缩进、转义、引用和围栏元数据。RichText 对未修改的部分保留其作者形式,只对已修改的部分写出规范化 Markdown。已拒绝的方案:在导入时进行规范化,因为每次保存都会重写未触碰的行。
DEC-2 — 顶级块是保留的单位¶
参考: spec:AST-062/DEC-2
决策者: cixzhang, 2026-10-06
人们通常一次编辑一个段落、列表、表格或代码块,顶级块可以在不触碰相邻块的情况下重新生成。对块内任意位置的编辑都会重新生成该块;在已修改块内保留更细粒度的片段是一种兼容的改进,而非强制要求。
未决问题¶
- 无。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx