Milkdown 编辑器 Markdown 解析器在处理列表项后换行符时的异常分析

问题现象

在使用 Milkdown 编辑器时，开发人员发现当 Markdown 内容中包含特定结构的列表项后跟随 HTML 换行标签 <br /> 时，编辑器会出现解析异常。具体表现为当列表项文本使用粗体标记（**text**）并以两个空格结尾（Markdown 的换行语法）时，如果紧接着出现 <br /> 标签，解析器会抛出错误导致渲染失败。

技术背景

Milkdown 是一个基于 ProseMirror 的现代化 Markdown 编辑器框架，它使用 remark 作为 Markdown 解析器，将 Markdown 转换为抽象语法树（AST），然后再转换为 ProseMirror 的文档结构。在这个过程中，HTML 标签的处理是一个常见的痛点，因为 Markdown 和 HTML 的混合使用可能导致解析器状态管理复杂化。

问题根源分析

经过深入分析，这个问题源于 Milkdown 的解析器在处理列表项和 HTML 标签的边界条件时存在不足。具体来说：

1. 列表项的结构特性：Markdown 列表项在解析后会转换为特定的 AST 节点，包含段落和其他块级内容。
2. HTML 标签的解析：<br /> 作为行内 HTML 元素，在 Markdown 中通常被转换为换行符。
3. 解析器状态冲突：当 <br /> 出现在列表项之后时，解析器在关闭列表项节点和打开新块级节点之间出现了状态管理问题。

解决方案实现

为了解决这个问题，我们实现了一个自定义的 remark 插件 remarkFixBrInLists，其核心逻辑如下：

1. AST 遍历：使用 unist-util-visit 工具遍历 Markdown 的抽象语法树。
2. HTML 节点检测：识别所有值为 <br /> 的 HTML 节点。
3. 上下文判断：检查这些节点是否位于列表项内部或紧邻列表项。
4. 安全转换：将可能引发问题的 <br /> 节点替换为一个包含单个空格的段落节点。

这种转换既保留了视觉上的间距效果，又避免了解析器的状态冲突。

技术实现细节

import { $remark } from "@milkdown/utils";
import { visit } from "unist-util-visit";

export const remarkFixBrInLists = $remark("remarkFixBrInLists", () => () => (tree) => {
  visit(tree, "html", (node, index, parent) => {
    if (node.value && node.value.trim() === "<br />" && parent && typeof index === "number") {
      if (
        parent.type === "listItem" ||
        (index > 0 && parent.children[index - 1]?.type === "listItem") ||
        (index < parent.children.length - 1 && parent.children[index + 1]?.type === "listItem")
      ) {
        parent.children.splice(index, 1, {
          type: "paragraph",
          children: [{ type: "text", value: " " }],
        });
      }
    }
  });
});

最佳实践建议

1. 避免混合使用 Markdown 和 HTML：尽量使用纯 Markdown 语法实现换行等简单格式。
2. 注意列表项的格式一致性：保持列表项内部结构的统一性，避免在列表项间插入非常规元素。
3. 考虑使用插件扩展：对于必须使用的特殊格式，可以通过自定义插件实现安全转换。
4. 测试边界条件：在使用复杂格式组合时，应进行充分的边界条件测试。

总结

这个问题展示了 Markdown 解析器在处理混合内容时的复杂性，特别是当 HTML 元素出现在特定上下文环境中时。通过实现自定义 remark 插件，我们不仅解决了当前问题，还为处理类似情况提供了可扩展的解决方案。这种基于 AST 转换的方法具有很好的通用性，可以应用于其他 Markdown 解析异常的处理场景。

对于 Milkdown 用户来说，理解解析器的工作原理和限制有助于编写更健壮的 Markdown 内容，同时也展示了 Milkdown 框架通过插件机制提供的强大扩展能力。