首页 · 资源 · Markdown 兼容性测试

Markdown 兼容性测试:实用的 .md 测试包

Markdific Markdown 兼容性测试包是一个可重复使用的 .md 文件,用于检查 Markdown 编辑器、查看器、渲染器和转换工具如何处理同一份文档。配套的 assets/ 文件夹提供六个本地图片测试素材。
一份 Markdown 文档,分别指向语法、图片、图表和导出兼容性检查
所有资源

在 GitHub 上获取测试包

选择 Code → Download ZIP,将文档和图片文件一起保存。你也可以在仓库中查看源文件,并在下载前查看变更记录。

测试包采用 CC BY 4.0 开放许可。只要注明出处,你就可以重复使用或改编测试材料。这并不意味着 Markdific 应用是开源的。

简要回答:下载 ZIP,在每个工具中打开同一个 .md 文件,记录哪些内容渲染正确,然后保存并导出一份工作副本。渲染、Markdown 往返转换和导出格式要分别记录结果。

测试涵盖的内容

1.0 版文档包含 30 个编号章节。每个章节都注明了它测试的是 CommonMark、GitHub Flavored Markdown(GFM)、常见扩展、特定应用语法、HTML 行为,还是往返转换。

类别 示例 检查内容
CommonMark 标题、链接、列表、引用块、代码、换行 解析和文档结构
GFM 表格、任务列表、删除线、自动链接 扩展语法支持
图片 PNG、JPEG、WebP、含空格的文件名、远程图片 加载和路径保留
技术内容 LaTeX 数学公式和七种 Mermaid 图表类型 预览、回退显示源码、导出
特定应用语法 Obsidian Wiki 链接、嵌入、提示块(callout)、标签 可移植性和可恢复性
往返转换 打开、编辑、保存和导出 源码改写和内容丢失
将 Markdown 渲染、保存和导出检查分开记录的结果矩阵

数学公式、Mermaid 和 Obsidian 语法不属于核心 CommonMark。一个工具即使不支持它们,也可以是准确的 CommonMark 渲染器。本测试包是用于实际比较的文档,而不是正式的标准一致性测试套件。

如何进行公平比较

  1. 下载仓库 ZIP。解压时不要把 .md 文档和 assets/ 分开。
  2. 保留一份未改动的基准副本。记录应用版本、操作系统、渲染模式和测试日期。
  3. 在第一个工具中打开一份工作副本。检查渲染结果,如果可以,也检查源码。
  4. 做一处小修改,保存为 Markdown,然后将保存的文件与基准副本比较。
  5. 导出为该工具提供的每种格式,例如 HTML、PDF 或 DOCX。分别打开导出的文件进行检查。
  6. 在其他工具中使用同一份基准副本重复以上步骤,并填写文档中的结果表。
Markdown 兼容性测试流程:从未改动的基准副本开始,经过渲染、保存、导出,到收集证据

不要把所有观察结果合并成一个“支持 Markdown”的分数。查看器可能能渲染图表,却无法编辑;转换工具可能在 PDF 中保留了图表外观,却丢失了 Mermaid 源码。这些是不同的结果。

结果标签

  • 通过:执行所测试的操作后,结构和含义保持完整。
  • 部分通过:内容仍可使用,但格式、源码、元数据或可编辑性有变化。
  • 不支持:未实现某个可选的语法扩展,但源码仍可恢复。
  • 失败:内容丢失、产生误导、执行了不安全的内容,或无法恢复。
  • 未测试:操作无法完成,或不适用。

记录每个标签背后的依据。例如,“Mermaid 显示为可读的代码块”通常属于不支持,而不是失败,除非该工具声称支持 Mermaid 渲染。

图片测试:哪些应该加载,哪些不应加载

ZIP 中包含六个可正常加载的本地图片测试素材:PNG、JPEG、WebP、含空格的文件名、由 HTML 引用的图片,以及 Obsidian 风格的粘贴图片。请将 assets/ 放在文档旁边。六个文件特意使用同一张简单的图片,这样比较时只考察文件格式和路径处理,不受无关的视觉差异影响。

在独立的测试包中,另有两个路径特意设置为无法解析:上级相对路径依赖更大的文件夹结构,站点根相对路径依赖网站。远程图片依赖网络连接。这些用例测试的是工具如何提示缺失或外部的资源,并不是 ZIP 中缺少文件。

如果所有随附的本地图片都无法加载,请先检查解压、文件夹位置和本地文件权限,再评判渲染器。

保存和导出后要检查什么

可视化预览可能掩盖源码的变化。请检查保存后的 Markdown 中是否有链接地址丢失、图片路径被改写、表格损坏、代码围栏被修改、字符被转义或元数据被删除。无害的格式规范化与含义丢失是两回事。

对于 PDF,检查分页、代码换行、数学公式、图表分辨率和链接。对于 DOCX,检查标题、表格、列表和图片是否仍可编辑。对于 HTML,检查结构、本地资源,以及对原始 HTML 的安全处理。

文档中包含一个无害的脚本测试。安全的预览可能会转义、去除脚本,或只显示源码而不执行。不要把脚本被阻止执行视为失败。

分享可复现的结果

发布比较结果时,请注明测试包版本(1.0)、工具及其版本、操作系统、配置、导入方式、导出设置,附上填写完整的结果表,以及有明显差异之处的截图。如果修改过测试文件,也请说明。

测试包由 Markdific 制作,Markdific 也可能是被测试的应用之一。请对每个应用使用相同的文件和评分定义。不要仅仅因为某个产品实现了某项可选功能,就把它算作其他产品的缺陷。

下载和再利用

在 GitHub 上打开 Markdown 兼容性测试包

使用 Code → Download ZIP,一并获取 .md 文档、assets/、README 和许可证。

文档及其随附的图片素材采用 CC BY 4.0 许可。请注明“Markdific Markdown Compatibility Test Pack v1.0”,附上仓库和许可证的链接;如果改编了材料,请说明改动。

常见问题

这是官方的 CommonMark 测试套件吗?

不是。CommonMark 有自己的规范和一致性示例。本测试包测试的是实际文档和工作流程,包括扩展语法和导出。

可以测试静态网站生成器吗?

可以。请记录引擎、插件、配置、主题、构建版本和资源路径规则。要比较生成的 HTML 和文件,而不仅仅是开发预览。

可以发布或修改测试包吗?

可以,需遵守 CC BY 4.0。请注明出处,附上许可证链接,并说明改动。在比较结果中保留原始版本标识,让读者知道测试的是哪个版本。

参考资料