跳转至

RichText 系统中的 Markdown 插件规格

意图

一个用插件扩展 Markdown 的产品只需编写一次插件。相同的内联语法,以及文档顶层相同的块级语法,都会变成相同的节点,由相同的渲染器绘制,无论用户是在 Markdown 中阅读文档、在 RichTextView 中查看,还是在 RichTextEditor 中编辑。每个界面只使用其调用方提供给它的插件;RichText 无法完全支持某个插件时,会拒绝该插件而不是部分应用。界面未采用的语法会保持为作者编写时的原样。

非目标

  • 嵌套在列表项、引用或表格单元格内的块级扩展语法。它在 RichText 中保持为字面文本。
  • 在扩展节点内部进行编辑、插件提供的编辑命令或工具栏,以及从编辑器界面插入新的扩展节点。
  • 在编辑期间运行插件的不可变文档转换,以及插件派生的标题投影或大纲。需要这些功能的插件会被拒绝(FR4)。
  • 将 RichText 自身的 Markdown 导入迁移到核心的解析器上。核心的解析器仅识别已采用的插件语法(FR5);RichText 的转换器导入其余所有内容。
  • 弃用或移除 transformers prop 和选项。
  • 为扩展节点提供公开主题目标;每个插件的渲染器拥有其节点的视觉表现。
  • 在 Server Components 中渲染 RichText 界面,服务端渲染 RichTextView 的内容(该内容仍在浏览器中填充),以及可序列化的扩展 props。
  • 通过 RichText 的公开 API 暴露编辑器引擎自身的插件、节点或扩展类型;包发现机制;全局注册;流式输入。

需求

  • FR1 — 单一定义。 插件是核心 createMarkdownPlugin 返回的入口。RichText 通过 createRichTextExtension(plugin)(FR3)采用同一个入口,后者返回一个不透明的 RichTextMarkdownExtension。RichText 使用核心的解析器识别插件的语法,并使用核心自身的扩展渲染来绘制其节点(FR8);不存在 RichText 特有的插件格式,也不存在插件解析或渲染的第二份副本。插件入口保持不透明:RichText 只读取核心插件协议暴露的内容。
  • FR2 — 按界面采用,绝不全局采用。 RichText 界面只使用其调用方传入的扩展:RichTextEditor 和 RichTextView 上的 markdownExtensions,以及 markdownToEditorStateJSON 的 extensions 选项。任何内容都不会在导入、全局或通过发现机制注册。同一页面上使用不同扩展的界面互不影响。
  • FR3 — 服务端安全的入口。 createRichTextExtension、RichTextMarkdownExtension、RichTextExtensionError、markdownToEditorStateJSON、editorStateJSONToMarkdown 及其选项类型从 @astryxdesign/richtext/markdown 导出,该模块不导入 React、DOM 或仅限客户端的模块:从核心中它只导入解析器和服务端安全的插件协议,绝不导入插件渲染器(FR8)。包的主入口仍然是客户端模块,并重新导出这些内容供客户端代码使用;服务端和 Node 代码从 @astryxdesign/richtext/markdown 导入它们。扩展持有其插件的函数和渲染器,因此不可序列化:客户端模块创建它们传递给 RichTextEditor 和 RichTextView 的扩展,无头代码则从插件和服务端安全入口创建自己的扩展。
  • FR4 — 默认拒绝。 createRichTextExtension 使用 getMarkdownPluginCapabilities(plugin) 读取插件的能力,该函数从核心的服务端安全子路径 @astryxdesign/core/Markdown/plugins 导出,报告插件是否声明了语法以及是否声明了不可变转换,除此之外不报告其定义的任何其他内容。RichText 采用语法;声明了转换的插件会被拒绝:createRichTextExtension 会在任何界面使用它之前抛出 RichTextExtensionError,指明插件名称和该能力。语法匹配但其节点名称没有渲染器的内容永远不会成为节点——核心的解析器会拒绝它并报告语法失败——因此其源文本保持为文本。被拒绝或缺失插件的语法作为字面文本导入(spec:AST-062 FR5)。
  • FR5 — 核心首先识别插件语法。 在 RichText 自身的 Markdown 导入读取顶层块之前,核心的解析器在给定恰好这些已采用插件的情况下,会在其中找到它们的节点。每个节点的精确源文本对 RichText 的导入屏蔽,并成为一个扩展节点;RichText 的转换器像没有插件时一样导入其余所有内容。在核心识别插件语法的地方,该插件的节点在该范围内胜出。被识别的范围与核心 Markdown 使用相同插件识别出的范围相同——相同的起点、终点、显示、节点名称和数据,并且代码内部、转义反斜杠之后或核心对插件屏蔽的任何其他位置都不包含其中——内联语法出现在任何导入内联内容的地方,块级语法出现在顶层。
  • FR6 — 扩展和转换器绝不拥有同一节点。 transformers prop 和选项在已采用的扩展声明其范围(FR5)之后导入基础 Markdown。普通语法重叠不是冲突:在核心识别为插件的范围内,插件的节点胜出,因此插件源文本内的链接、列表、强调或任何其他转换器语法都不会阻止文档打开。当转换器导入或导出了扩展的节点类型,或两个扩展采用了同一插件时,该界面或序列化器会在配置时被拒绝——抛出 RichTextExtensionError,指明插件、转换器或第二个扩展,以及该能力。
  • FR7 — 扩展节点是原子的。 被识别的范围在编辑器中是一个节点,不能在其中输入。光标一步越过它;它作为整体被选择、删除、剪切、复制、粘贴、移动、撤销和重做。内联节点位于其文本行中;块级节点是顶层块。辅助技术按文档顺序遇到每个节点一次,并使用其渲染器赋予的语义;节点本身不添加任何 Tab 停靠点。
  • FR8 — 渲染与核心一致。 节点通过 MarkdownPluginNodeRenderer 渲染,该函数从核心的仅客户端子路径 @astryxdesign/core/Markdown/plugin-renderer 导出,使用给定插件渲染一个已解析的扩展节点,并具有与 Markdown 为同一节点呈现的完全相同的 DOM、可访问性、主题目标、回退和失败报告——即其插件在核心错误边界和 suspense 回退内部为其节点名称提供的渲染器——并且不添加自己的元素或主题目标。RichTextEditor 和 RichTextView 导入它;服务端安全入口绝不导入它。返回空内容的渲染器渲染为空。如果渲染器在调用时或渲染期间抛出异常,该节点会显示其可读文本作为替代——即其源文本,或对于没有源文本的节点显示渲染器的 toText——并且在渲染器挂起时显示相同的文本。没有该节点插件的界面显示其源文本。失败绝不会破坏界面的其余部分。
  • FR9 — 诊断与核心一致。 RichText 通过核心的插件失败报告来报告插件的失败,与 Markdown 相同:每个插件和阶段一次,格式为 plugin "<name>" failed in <phase>; rendered readable fallback. 它不添加自己的诊断通道。
  • FR10 — 编写的源文本是权威的。 扩展节点无论位于何处都精确导出其源字节,因此包含插件语法的文档保持 spec:AST-062 FR1–FR5:未更改的文档逐字节往返;节点周围的编辑永远不会重写它;移动它会移动其字节。未带插件导入的文档将语法保留为字面文本,并在导出时保持不变。
  • FR11 — 存储状态从源文本重新派生。 存储的编辑器状态保留每个扩展节点的精确源文本、其插件的名称和协议版本(apiVersion),以及为渲染派生的数据。界面加载存储状态时,它会使用已采用的插件再次从源文本派生每个节点,绝不自行渲染存储的数据。已采用的插件不再将其源文本识别为该节点的节点——插件的语法或协议版本在未迁移的情况下发生变化,或插件缺失——会作为其源文本加载,即以字面文本形式导出且保持不变。
  • FR12 — 无头使用是服务端安全的。 识别、导入、导出和 createRichTextExtension 从 @astryxdesign/richtext/markdown 导入,可在 Node 和服务端代码中运行,且无需 DOM。RichText 的界面是客户端组件:它们不渲染为 Server Components,扩展也不是可序列化的 props(FR3)。RichTextView 保持其客户端边界——其内容在浏览器中填充——并且包含它的服务端渲染页面在采用扩展时不会在 hydration 时出现不匹配。

平台支持

  • 支持的功能/引擎下限:凡是 RichText 可渲染之处;识别、导入和导出还可通过 @astryxdesign/richtext/markdown 在 Node 中无头运行。
  • 不支持的行为:除非目标外,无其他不支持项。
  • 浏览器证据:FR7 和 FR8(编辑器中的键盘、选区、剪贴板、历史、渲染及辅助技术顺序)以及 FR12 的水合(hydration)需要浏览器证据。

当前状态影响

RichText 不采用 Markdown 插件:插件语法以字面文本导入,并按编写时的原样导出(spec:AST-062 FR5);RichTextEditor、RichTextView 和 markdownToEditorStateJSON 不接收 Markdown 插件。它们的 nodes、plugins 和 transformers 属性和选项(接收编辑器引擎节点、React 插件和编辑器引擎 Markdown 转换器)在 markdownExtensions 之外继续正常工作。该包只有一个入口点,即客户端模块,Markdown 序列化器只能通过它访问;@astryxdesign/richtext/markdown 增加了服务器安全版本。Core 的服务器安全子路径 @astryxdesign/core/Markdown/plugins 导出插件构造、第一方辅助工具(文本转换、语义围栏、源码装饰、frontmatter、软换行、标题链接)以及协议类型(component:Markdown 会列出它们);这些都不会报告插件的功能或渲染某个节点,条目保持不透明。Core 仅在 Markdown 内部渲染扩展节点。getMarkdownPluginCapabilities 以及带 MarkdownPluginNodeRenderer 的仅客户端子路径 @astryxdesign/core/Markdown/plugin-renderer 是新增的。

验证

契约 验证 代表性状态 变更或失败预期
FR1 将同一插件条目传递给 Markdown 和 createRichTextExtension 一个包含行内与块级贡献及数据的插件 仅 RichText 的定义,或第二个分词器或渲染器,将失败
FR2 页面上两个界面,一个带扩展,一个不带;分别有和没有扩展的导入 编辑器与视图;带和不带 extensions 的 markdownToEditorStateJSON 一个界面的扩展改变了另一个界面,或没有显式扩展就被识别,将失败
FR3 这些包构建后的导出、类型和导入图,分别在 Node、服务器模块和客户端模块中加载 @astryxdesign/richtext/markdown 和 @astryxdesign/core/Markdown/plugins,无 DOM;@astryxdesign/core/Markdown/plugin-renderer 作为客户端模块;RichText 主入口重新导出服务器安全入口;仅导入服务器安全入口的生产 bundle 服务器安全入口导入 React 组件、DOM、客户端模块或插件渲染器;渲染器子路径缺少客户端边界;缺少导出或类型;或服务器专用 bundle 中出现客户端代码,将失败
FR4 在能力矩阵上使用 getMarkdownPluginCapabilities 和 createRichTextExtension 带渲染器的语法;转换;带语法的转换;节点名称没有渲染器的匹配;文档中被拒绝插件的语法 接受转换;拒绝时未指明插件与能力;能力报告暴露了语法和转换以外的内容;无渲染器的匹配变成节点;或语法被丢弃,将失败
FR5 由 core 解析并由带相同插件的 RichText 导入的语料库,逐节点对比 行内与块级匹配;延迟匹配和失败匹配;行内代码和围栏代码内的语法;转义起始符;基础 Markdown 也会读取的插件语法(类似强调的分隔符);列表、引用和表格单元格中的行内语法;嵌套块级语法 与 core 不同的跨度、显示、节点名称或数据;插件跨度内读取了基础 Markdown;或识别了嵌套块级语法,将失败
FR6 Surface 和序列化器配置,以及在其下打开的文档 一个导入或导出扩展节点类型的 transformer;一个插件对应两个扩展;一个 note 插件,其源包含链接、列表标记和强调,并使用默认 transformers 打开;一个无关的自定义 transformer 以下情况均视为失败:冲突配置未抛出异常;错误信息遗漏了插件、transformer、扩展或能力;文档因基础语法位于插件源内部而无法打开
FR7 在真实浏览器中编辑内联节点和块节点 跨节点使用方向键、Shift 选择、Backspace 和 Delete、剪切、复制、粘贴到另一个编辑器(带扩展和不带扩展两种情况)、撤销、重做、在节点旁输入 若光标出现在节点内部、发生部分删除、或编辑导致节点被拆分,则失败
FR8 由 Markdown、MarkdownPluginNodeRenderer 以及两种 RichText 界面渲染的完全相同节点,在 Markdown 的块级包装器下进行比较 返回内容的渲染器;返回空内容的渲染器;调用时抛出异常的渲染器;组件抛出异常的渲染器;会挂起的渲染器;没有源的节点;没有扩展的界面 节点 DOM、无障碍树、主题目标、回退或失败报告中的任何差异,或渲染器新增的任何元素或主题目标,均视为失败
FR9 来自两种界面的失败报告 语法失败;重复出现的渲染失败 若报告与核心的消息或出现频率不同,或包含仅 RichText 才有的诊断信息,则失败
FR10 添加了插件语法的 spec:AST-062 一致性语料库 未更改的文档;节点旁的编辑;节点被移动;在没有插件的情况下导入 若节点源的任何字节发生变化,或在没有插件时源丢失,则失败
FR11 在插件变更后加载已存储状态 同一插件;协议版本变更;不再匹配的语法变更;存储数据被编辑为与源不一致;没有插件 若渲染过期的存储数据,或源字节丢失或被更改,则失败
FR12 无头运行与 hydration 使用来自子路径的扩展进行节点导入和导出;在没有 DOM 的情况下调用 createRichTextExtension;服务器渲染的页面,对包含内联节点和块节点的 RichTextView 进行 hydration 在创建、导入或导出过程中执行了仅浏览器可用的操作,或出现 hydration 不匹配,均失败

决策日志

DEC-1 — 插件只用核心的协议编写一次

DEC-1 — RichText 复用 core 的契约

Reference: spec:AST-064/DEC-1 Decider: cixzhang, 2026-10-06

core 的插件协议已经约束语法、保护内置构造、验证节点,并提供带回退的渲染。RichText 按原样采用这些条目,通过 core 的解析器识别语法,并使用插件的渲染器绘制节点,因此一个插件在读取时的含义与编辑时的含义不可能不一致。否决:RichText 插件格式,因为它会复制每个插件的解析与渲染,并让它们彼此漂移。

DEC-2 — 每个界面显式采用插件

Reference: spec:AST-064/DEC-2 Decider: cixzhang, 2026-10-06

某个界面的扩展就是其调用方传入的那些扩展,正如 Markdown 的 plugins 那样。否决:全局注册表,因为它会让一个产品的插件改变另一个界面的文档,并使行为依赖导入顺序。

DEC-3 — 默认拒绝:只采用 RichText 完全支持的插件

Reference: spec:AST-064/DEC-3 Decider: cixzhang, 2026-10-06

如果某个编辑器悄悄跳过插件的某一部分——例如它的 transform——那么对于同一份源文本,它显示的文档就会与 Markdown 不同。RichText 只在它能支持插件全部能力时才采用该插件,否则会明确拒绝,并把插件的语法当作文本保留。否决:带警告的部分采用。

DEC-4 — core 识别插件语法;RichText 导入其余部分

Reference: spec:AST-064/DEC-4 Decider: cixzhang, 2026-10-06

插件语法的含义以 core 解析器给出的含义为准,因此 core 先识别它,且其范围不向 RichText 的导入开放;基础 Markdown 仍由 RichText 的 transformer 处理。插件源码中出现的基础语法属于该插件;只有拥有该扩展节点类型的 transformer 才会与它冲突,而这种冲突在配置界面时就被拒绝,绝不会在文档打开时才被拒绝。否决:在本记录中将 RichText 的全部导入都移到 core 的解析器上;在扩展与 transformer 之间采用“后者胜出”;以及因为插件源码内部出现基础语法就让文档失败。

DEC-5 — 扩展节点是原子的,其源码即事实来源

Reference: spec:AST-064/DEC-5 Decider: cixzhang, 2026-10-06

core 的协议把语法读入节点并渲染它们;它没有办法把变更后的节点写回 Markdown。原子节点保留其创作时的源码,导出时精确导出该源码,并在每次加载时都从该源码重新派生,因此存储的数据永远不会与文档产生偏离。存储状态只通过插件条目暴露出的信息来命名插件,即插件名称和协议版本:决定节点是什么的是重新派生,而不是存储的身份标识。否决:可编辑的扩展内容(那需要每个插件各配一个序列化器),以及跨插件版本信任存储数据。

DEC-6 — core 只暴露 RichText 需要的事实

Reference: spec:AST-064/DEC-6 Decider: cixzhang, 2026-10-06

插件条目保持不透明,这样所有消费者都会经过 core 的验证、防护和回退。RichText 需要 core 提供两件事:知道插件是否声明了 transform,以及像 Markdown 那样渲染单个节点。core 恰好只暴露这些:在服务端安全的插件子路径中提供只读能力报告,以及在客户端专用子路径中提供单节点渲染器;该渲染器呈现节点的方式与 Markdown 完全一致,且不添加任何自己的元素。在 core 内部共享同一条渲染路径可防止两者产生偏离。

否决:把渲染器放在服务端安全的插件子路径中,这会把客户端代码拉进服务端导入;暴露插件定义,这会招致解析和渲染逻辑被复制;以及把每个节点渲染为一整份 Markdown 文档,这会在编辑器内引入文档元素和 Markdown 的主题目标。

开放问题

  • 无。

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