Milkdown Markdown解析器在列表项后处理`<br />`标签的异常分析与解决方案

问题背景

Milkdown作为一款现代化的Markdown编辑器，其核心功能之一是将Markdown语法转换为可编辑的富文本内容。在实际使用过程中，开发者发现当Markdown内容中包含特定结构的列表项后跟随HTML换行标签<br />时，解析器会出现崩溃现象。

异常场景还原

以下Markdown结构会触发解析异常：

* **加粗文本** : 描述内容。  
* **加粗文本** : 描述内容。  
* **加粗文本** : 描述内容.

  <br />

关键特征：

1. 使用无序列表（*开头）
2. 每个列表项包含加粗文本（** **语法）
3. 列表项末尾使用两个空格实现换行
4. 最后跟随一个独立的<br />标签

技术原理分析

Milkdown解析流程

Milkdown的Markdown解析采用分层架构：

1. Remark层：将原始Markdown转换为语法树（AST）
2. Prosemirror层：将AST转换为编辑器可操作的文档模型

异常根源

当解析器遇到以下组合时会产生冲突：

1. 列表项（listItem）的闭合处理
2. 块级HTML标签（<br />）的上下文判定
3. 加粗文本（strong）的mark范围界定

在AST转换过程中，解析器无法正确处理<br />作为块级元素出现在列表项之后的场景，导致节点创建失败。

解决方案实现

临时解决方案：remarkFixBrInLists插件

我们开发了一个自定义Remark插件来解决此问题，核心逻辑如下：

visit(tree, "html", (node, index, parent) => {
  if (node.value.trim() === "<br />" && parent) {
    // 检查相邻节点是否为列表项
    const isNearListItem = /* 判断逻辑 */;
    
    if (isNearListItem) {
      // 替换为安全节点
      parent.children.splice(index, 1, {
        type: "paragraph",
        children: [{ type: "text", value: " " }],
      });
    }
  }
});

实现要点

1. AST遍历：使用unist-util-visit遍历语法树
2. 精准匹配：只处理纯<br />标签的情况
3. 上下文判断：检查相邻节点是否包含listItem类型
4. 安全替换：用空白段落替代原始HTML节点

技术启示

1. Markdown解析边界：混合Markdown与HTML时需注意解析器兼容性
2. AST操作安全：修改语法树时要保证文档结构完整性
3. 错误防御：编辑器应具备对异常内容的优雅降级能力

最佳实践建议

对于需要在列表后添加空行的场景，推荐：

1. 优先使用纯Markdown语法（双空格换行）
2. 避免在列表结构附近使用原始HTML标签
3. 必要时使用自定义插件进行内容预处理

该解决方案已在实际项目中验证有效，既保持了文档的视觉表现，又确保了编辑器的稳定运行。