Skip to content

Markdown Round Trip

Jump to bottom
CatsInJune edited this page Oct 30, 2026 · 1 revision

Markdown 往返规则

本库的核心承诺是 Markdown 进，Markdown 出（getMarkdown()）。但 markdown 语法不足以表达全部富文本能力，所以实际规则分四类。每条规则都对应编辑器、预览、服务端渲染三端一致的行为（它们共享同一解析 tokenizer）。

1. 原生 GFM 往返

以下内容始终使用原生 markdown，未被触碰的内容永远不会被 HTML 化：

  • 标题、加粗/斜体/删除线、行内代码、链接
  • 图片 ![alt](url)（未缩放、未对齐、无图注时）
  • 有序/无序列表、任务列表
  • 表格、引用、围栏代码块（带语言）、水平线
  • GFM 脚注 [^1] / [^1]: 定义（阅读页可用 extractFootnoteSources 抽取定义行）

2. 刻意偏离标准语法

公式（KaTeX）

  • 内联：$$E = mc^2$$ —— 不是标准语法 $x$
  • 块：单独成行、用 $$ 包裹：
$$
\frac{a}{b}
$$
  • 输入 $ / $$ 不会转换成公式；没有打字快捷方式，只能从工具栏「更多」菜单插入
  • 导入已含 $$ 的标准数学 markdown 照常渲染

$ 的转义

单个 $ 永远是货币符（$24.4B、US$，甚至 $24.4B$ 也不是公式）。导出时货币 $ 会被转义为 \$，防止其他渲染器把它当公式开始符。

表情

:smile: 短代码往返；不认识的 :xxx: 原样保留为普通文本。

3. 无 markdown 语法、走 HTML 的特性

统一原则：只有当该样式被实际设置时才写 HTML。其他渲染器（GitHub 等）会净化 style 属性——丢的是装饰，不是内容。

特性 导出形态
图片缩放 <img src="…" alt="…" width="440" height="330">（resetImageSize(editor) 还原为 ![alt](url)）
图片对齐 <img … data-align="center">（官方 image-align-button 的属性名）
图片图注 <figure><img …><figcaption>…</figcaption></figure>
段落样式 <p style="text-align: center; margin-left: 2em; line-height: 1.5">、<h2 style="…">
折叠块 <details>…</details>（MIT Details 扩展）
图表 <!-- {"chartType": "line", …} --> 注释 + GFM 表格

其他字符级格式：

  • 字体颜色 / 背景高亮 / 字号导出为内联 <span style>（如 color:#ffeb00、background-color:#ff0000）；不用 ==高亮== 语法
  • 上下标导出 <sup>2</sup> / <sub>2</sub>
  • 列表编号格式非默认时导出 <ol data-numbering-format="upper-alpha">（默认阿拉伯数字不写属性）

这些标签在解析端由同一个共享 tokenizer 认领（先于 window.DOMParser 路径），编辑器、预览、renderReportHtml 服务端都能还原——包括 SSR 场景，否则内联 HTML 会被转义成字面文本。

4. 已知损耗

  • 合并单元格：GFM 没有 colspan，mergeCells 后导出为 | 1<br>2 |，重新加载无法还原合并结构——因此本库刻意不暴露合并/拆分单元格命令。详见设计决策。
  • 查找替换的替换结果沿用匹配起点处的字符格式（官方扩展语义）。
  • 图表配置存在注释里，GitHub 等渲染器把它显示为普通 HTML 注释 + 表格——数据不丢，图不渲染。

tiptap-markdown-react

相关链接

Clone this wiki locally