Tiptap-markdown

1. 明确真相源：文档 JSON，不是 Markdown#

• 存储和协作只用 Tiptap JSON（或 HTML）。
• Markdown 只做两件事：输入快捷方式（InputRule）和 导入/导出（有损，用户可接受）。
• 不要试图让文档在 Markdown 和富文本之间“无损往返”，这是不可能的，一旦放弃这个目标，一半的补丁就没必要了。

2. 把键盘行为写成一张“决策表”，而不是散落的 keymap#

建一个单独的 KeyboardBehavior 扩展，设高 priority，所有 Enter / Backspace / Tab / Shift-Tab 都先进这里，根据上下文判断：

text

1
上下文 = { 父节点类型, 深度, 是否为空, 光标在块首/块尾, 上一个兄弟节点类型 }

例如 Enter 的表：

每一行都对应一条测试用例。命中就返回 true，不命中就 return false 交给默认行为。这样修 bug 就是改表格 + 加用例，而不是猜哪个扩展抢了按键。

3. 直接利用官方已经踩过坑的东西#

• @tiptap/extension-list-keymap（Tiptap 3 里在 @tiptap/extension-list 包内）：专门修列表 Backspace/Delete 的诡异行为，很多人自己重写反而更糟。
• Tiptap 默认 keymap 里的 undoInputRule：实现了 Typora 那种“自动转换后按 Backspace 撤回转换”。
• Tiptap 3 官方出了 @tiptap/markdown（比社区的 tiptap-markdown 对 JSON 模型更友好），可以看看是否满足你的导入导出需求。

4. 给每个键盘场景写自动化测试#

用 vitest + prosemirror-test-builder（或直接构造 JSON 文档，设置 selection，触发 command，断言 JSON）。列表相关的回归 bug 没有测试基本不可能收敛。装个 prosemirror-dev-toolkit 看每次 transaction 也很有帮助。

5. “内容”和“主题”分层，这是公众号场景的核心#

微信公众号粘贴的限制：只认内联 style，没有外部 CSS，没有 JS，没有 iframe，图片必须传微信素材库。截图里那个 Spotify 卡片进了公众号一定会没掉。

推荐的做法（doocs/md、mdnice 都是这么做的，只是它们从 Markdown 出发，你从 JSON 出发）：

text

1
文档 JSON（内容 + 少量块级覆盖样式 attrs）
2
        ↓
3
主题（默认字体、字号、标题样式、引用样式、配色）
4
        ↓
5
渲染器：generateHTML(json, extensions) → 按主题注入 CSS → juice 内联化
6
        ↓
7
公众号 HTML / 知乎 HTML / 网页 HTML / Markdown（有损）

• 编辑器里工具栏调的字体、字号、对齐，尽量做成主题级别或块级 attrs，而不是随手往文本上塞 <span style>。否则导出到不同渠道时样式不可控，用户切换主题也没法生效。
• 像 Spotify 这类富媒体块，在渲染阶段按渠道降级：公众号 → 封面图 + 文字链接；网页 → 保留 embed。