MDX Editor项目中有序列表起始编号问题的技术解析

在MDX Editor项目使用过程中，开发者可能会遇到一个关于有序列表（Ordered List）的显示问题：当用户尝试以非1的数字（如3）开始有序列表时，富文本编辑器界面会正确显示该起始编号，但切换到源码模式后实际保存的依然是标准Markdown格式（从1开始）。本文将从技术角度深入分析该问题的成因及解决方案。

问题现象的技术本质

该问题涉及Markdown解析器的两个核心层面：

1. 富文本渲染层：编辑器界面基于用户输入动态生成视觉编号（如3.xxx）
2. AST抽象语法树层：底层实际遵循CommonMark规范，默认强制有序列表从1开始编号

这种差异源于Markdown不同实现规范的分歧：

• 原始Markdown规范（John Gruber版）仅支持从1开始的列表
• GFM（GitHub Flavored Markdown）等扩展规范支持自定义起始编号

技术实现原理分析

MDX Editor的列表处理流程包含三个关键阶段：

1. 用户输入解析阶段

   • 通过正则匹配识别"数字+点+空格"的列表模式
   • 富文本层临时保留用户输入的起始编号

2. AST转换阶段

   • 使用mdast（Markdown AST）进行语法树转换
   • 默认配置会规范化列表起始值为1

3. 序列化输出阶段

   • 通过toMarkdown将AST转换回Markdown文本
   • 默认不保留原始编号信息

解决方案建议

对于需要自定义起始编号的场景，可通过以下技术方案解决：

1. 配置mdast解析选项

{
  mdastExtensions: [{
    transforms: [(tree) => {
      // 自定义AST转换逻辑处理列表起始值
    }]
  }]
}

2. 修改序列化行为

toMarkdownOptions: {
  listItemIndent: 'one',
  incrementListMarker: false  // 禁用编号自增
}

3. 自定义插件开发 可扩展列表处理插件，在以下生命周期介入处理：

• 输入时捕获起始编号
• 渲染时动态生成序号
• 导出时保留编号元数据

最佳实践建议

1. 对于严格兼容CommonMark的场景，建议在UI层添加提示，说明仅支持从1开始的列表
2. 需要GFM兼容性时，建议通过preset配置加载gfm插件
3. 复杂列表需求可考虑通过自定义CSS计数器实现视觉编号

该问题的本质是不同Markdown规范实现之间的差异，开发者应根据项目实际需求选择合适的兼容性方案。理解编辑器底层AST处理流程，有助于更好地控制Markdown元素的渲染行为。