Markdown 预览教程

同一段 Markdown 在两个预览器里渲染结果不同,多半是方言问题。删线、表格空行、代码块语言标注、列表缩进的实际差异,以及什么时候别用 Markdown。

同一段文字,两个预览器两种样子

把一段带删除线和表格的笔记贴进两个在线预览器,一个正常渲染,另一个把符号当普通文字全显示出来。不是预览器坏了,是它们支持的方言不一样:一个按 CommonMark 严格解析,另一个走 GFM 扩展。

方言差异,先认三条

  • 删除线 ~~text~~:CommonMark 标准不支持,GFM 支持,遇到不渲染就是这个原因
  • 表格:多数解析器要求表格前留一个空行,紧贴段落写会失效
  • 任务列表 - [ ]:GFM 扩展语法,标准解析器只当普通文字

表格和代码块最容易翻车

表格的坑集中在分隔行:| --- | --- | 写错列数,整张表会退化成纯文本。代码块要标语言,三个反引号后面加 js 或 python,某些预览器不标语言就不做高亮,甚至把缩进吃掉。这两类建议写完立刻预览一遍,别等发布后才发现。

列表缩进的隐形规则

嵌套列表通常要求子项缩进两个或四个空格,不同解析器默认值不同。用 Tab 混着空格最容易出错:编辑器里看着对齐,渲染出来层级全乱。建议统一用两个空格,跨平台最稳。

什么时候别用 Markdown

需要精确控制位置(海报、证书)、需要复杂表格合并单元格、需要页眉页脚分页,这些场景 Markdown 都吃力,直接上 Word 或 LaTeX 更省事。它擅长的是结构清晰的长文档,不是排版艺术品。

常见问题

预览正常,发布后错乱
发布端解析器和预览器可能不是同一个实现,换用同一套渲染库。
中文加粗失效
多半是星号和汉字之间没留空格,部分解析器对此敏感。
能插入 HTML 吗
多数支持内联 HTML,但安全性取决于渲染方是否过滤。
GitHub 上能看的这里看不了
两边方言不同,以目标平台支持的语法为准。

相关阅读

代码格式化看 代码格式化;JSON 展示看 JSON 格式化;文本清理看 文本去空格。工具在 Markdown 预览。

去使用 Markdown 预览工具