Markdown 看起来”通用”——但跨平台分享时 80% 的人都遇到过排版异常。根因是 Markdown 没有统一规范：John Gruber 2004 年的”参考实现 + 示例”留下大量歧义，各平台为了修复歧义和加扩展形成了不同方言。理解这些差异能避免”GitHub 上正常发布到微信全乱”的痛苦。
主流 Markdown 方言一览
| 方言 | 出处 | 特点 | 适用 |
|---|---|---|---|
| 原始 Markdown | John Gruber 2004 | 模糊规范 | 历史参考 |
| CommonMark | 2014 标准化 | 严格规范 | 跨平台基线 |
| GFM | GitHub | CommonMark + 表格 / 任务列表 / 自动链接 | GitHub / 通用 |
| Markdown Extra | PHP Markdown | 加表格 / 脚注 / 属性 | 部分博客系统 |
| MultiMarkdown | Fletcher Penney | 学术写作扩展 | 学术 / 出版 |
| Pandoc Markdown | Pandoc | 最强大、最复杂 | 文档转换 |
| 微信富文本 | 微信公众号 | 不支持 Markdown 直接渲染 | 需转换工具 |
| 飞书 / 语雀 | 平台专属 | 部分兼容 GFM + 自有扩展 | 团队协作 |
共同语法（所有方言都支持）
# 一级标题
## 二级标题
### 三级标题
**粗体** *斜体* `行内代码`
> 引用文本
- 无序列表
- 项目 2
1. 有序列表
2. 项目 2
[链接文字](https://example.com)
```
代码块
```这些是 Markdown 的”基础公约”——任何平台都能渲染。
GFM 独有（GitHub / 通用扩展）
表格
| 列 1 | 列 2 | 列 3 |
|------|------|------|
| A | B | C |
| 居中 | 右对齐 | 左对齐 |对齐：
| 左 | 中 | 右 |
|:---|:---:|---:|
| A | B | C |注意：CommonMark 不支持表格——所以纯 CommonMark 渲染器看不到表格。
任务列表
- [x] 已完成
- [ ] 待办
- [ ] 子任务
- [x] 子项 1
- [ ] 子项 2删除线
~~删除文字~~自动链接
https://example.com ← 自动转为可点链接
@username ← GitHub 内自动转用户链接
#123 ← GitHub 内自动转 issue 链接代码语言高亮
```javascript
function hello() {
console.log("Hi");
}
```支持的语言（PrismJS / highlight.js / Shiki 大致一样）：
- 主流：js, ts, py, go, rust, java, c, cpp, csharp
- 数据：json, yaml, toml, xml, csv
- 命令行：bash, sh, shell, powershell
- 数据库：sql
- 标记：html, css, markdown
- 特殊：diff, mermaid
平台特殊语法
GitHub 独有
[!NOTE] ← Alert (2023+)
[!TIP]
[!IMPORTANT]
[!WARNING]
[!CAUTION]例：
> [!WARNING]
> 这是一个警告框GitLab 独有
{++ 添加文字 ++} ← CriticMarkup
{-- 删除文字 --}
{== 高亮文字 ==}
{>> 评论 <<}Notion 独有
- 用
/命令插入元素（不是纯 Markdown） - 数据库块、嵌入、callout 等
语雀独有
:::tip
提示信息
:::
:::warning
警告
:::
:::danger
危险
:::Hexo / Hugo / Jekyll（静态博客）
各自的 frontmatter（YAML / TOML）：
---
title: 文章标题
date: 2026-04-26
tags: [markdown, web]
---
正文...数学公式：哪些支持 LaTeX
行内公式：$E = mc^2$
块级公式：
$$
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$支持平台：
- ✅ Typora, Obsidian, Logseq, HackMD
- ✅ GitHub（issue/PR/discussion 直接支持，2024 年起 .md 文件需启用）
- ✅ GitLab
- ✅ Notion（
/equation） - ✅ 语雀
- ✅ Jupyter / Quarto / R Markdown
- ✅ MkDocs（配插件）
不支持：
- ❌ 微信公众号（必须截图）
- ❌ 知乎（用自己的
[公式]标签） - ❌ CSDN
- ❌ 多数普通博客（看主题是否装 MathJax / KaTeX）
兜底方案：
- 公式渲染成 PNG / SVG，作为图片嵌入
- 用 LaTeX → 图片转换工具（CodeCogs / texit）
- 用 Unicode 字符替代（α β π Σ ∫）
微信公众号工作流
核心：微信公众号不支持 Markdown 直接渲染，需要转 HTML。
1. 用 Markdown 编辑器写文章（Typora / VS Code / 在线工具）
↓
2. 用转换工具转 HTML（含内联样式）
- md2wechat
- Mdnice (mdnice.com)
- wechat-md
- Markdown Here
↓
3. 选择 / 复制 HTML 渲染结果
↓
4. 粘贴到微信公众号编辑器
↓
5. 公众号编辑器保留 HTML 内联样式
↓
6. 预览 + 调整 + 发布为什么必须内联样式：
- 公众号编辑器去除外部 CSS /
<style>标签 - 只保留每个元素的
style="..."属性 - 转换工具会把 CSS 规则全部”展平”到 style 属性
陷阱：
- 复制纯 Markdown 文本到公众号 → 显示
**#等原始符号 - 复制带 CSS 类的 HTML → 样式丢失
- 必须复制渲染后的 HTML 带内联样式
飞书 / 语雀的 Markdown 支持
| 功能 | 飞书 | 语雀 | 钉钉文档 |
|---|---|---|---|
| 标题 / 列表 / 强调 | ✅ | ✅ | ✅ |
| 表格 | ✅（语法） | ✅（语法） | ⚠（需用按钮） |
| 代码块 + 高亮 | ✅ | ✅ | ⚠（语言少） |
| 任务列表 | ✅ | ✅ | ✅ |
| LaTeX 公式 | ❌ | ✅ | ❌ |
| 自定义 callout | ❌ | ✅ | ❌ |
| 直接粘贴 .md | ✅（多数语法保留） | ✅ | ⚠（部分丢失） |
| 导出为 .md | ❌（部分支持） | ✅ | ❌ |
实务：
- 语雀：Markdown 支持最完整，可作为协作 + Markdown 真理源
- 飞书：富文本为主，Markdown 是”输入便利”
- 钉钉文档：Markdown 支持最弱，建议用富文本编辑
CommonMark 与 GFM 的歧义点
历史上各 Markdown 实现处理不一致的点（CommonMark 给出明确规范）：
| 歧义 | CommonMark 规范 | GitHub Old | GitHub New (CMARK) |
|---|---|---|---|
| 列表项内嵌段落 | 需要 4 空格缩进 | 2 空格 | 2 或 4 空格 |
段落起始的 > | 引用 | 引用 | 引用 |
| 强调嵌套 | 复杂规则 | 简化 | 标准化 |
| HTML 内嵌 | 严格分块 | 宽松 | 严格 |
| 链接定义 | 文档级 | 段级 | 文档级 |
陷阱：从老 GitHub 迁移到 CommonMark 实现时，少数老文档渲染会变化。
中文排版的常见坑
中英混排
错误：Hello世界 React组件
正确：Hello 世界 React 组件 ← 中英文之间空格自动化方案：
pangu.js：浏览器 / Node.js 自动加空格- VS Code 插件 “Pangu-Markdown”
- CSS
text-spacing: ideograph-alpha（部分浏览器支持）
全角 vs 半角标点
全角：你好，世界！这是 (test)。
半角：你好,世界! 这是(test).- 出版 / 文学：全角（视觉舒适）
- 程序员 / 文档：半角（与代码协调）
- 不要混用：选一种风格贯穿全文
引号
"双引号" ← Markdown 里仍显示直引号 "..."
"中文引号" ← 必须手动输入全角
可以用 SmartyPants 自动转换：
"hello" → "hello" （部分平台支持）行末标点掉行
中文标点（。！？）跑到下行行首很难看。
CSS 方案：
p { word-break: keep-all; line-break: strict; }Markdown 层面：用零宽空格 或非断空格 控制（不优雅）。
跨平台兼容性最佳实践
"最大公约数"原则：
↓
基础语法（所有平台）：标题 / 段落 / 列表 / 强调 / 链接 / 图片 / 代码
↓
GFM（多数平台）：表格 / 任务列表 / 删除线 / 代码高亮
↓
方言扩展（部分平台）：LaTeX / Mermaid / Callout / 脚注
写文章时按"最低支持平台"选择语法实务：
- 跨平台 .md 文件 → CommonMark + GFM 表格 + 代码高亮
- GitHub 内部 → 全 GFM + GitHub Alert
- 微信公众号 → 写 Markdown + 工具转 HTML
- 学术 / 数学 → Quarto / R Markdown（最强 LaTeX 支持）
转换工具速查
| 用途 | 工具 |
|---|---|
| Markdown ↔ HTML | Pandoc, marked, markdown-it |
| Markdown ↔ Word | Pandoc |
| Markdown ↔ PDF | Pandoc + LaTeX, marp（slides） |
| Markdown → 公众号 | md2wechat, Mdnice, Markdown Here |
| Markdown → 知乎 | 直接粘贴（知乎支持基础语法） |
| Markdown → 飞书 / 语雀 | 直接粘贴 |
| Markdown → 幻灯片 | Marp, reveal-md, Slidev |
| 静态站点生成 | MkDocs, Hugo, Hexo, Astro, Docusaurus |
实战清单
✅ 必做：
- 写文章前先确认目标平台方言
- 跨平台分享用 GFM 基础（不依赖方言扩展）
- 表格 / 公式 / 高亮等扩展确认平台支持
- 微信公众号必经转换工具
- 中英混排自动加空格（pangu.js）
- 代码块始终指定语言（
text兜底）
❌ 避免：
- GitHub 用 GFM 写完直接粘贴到微信
- 依赖单平台专属语法（飞书 callout）跨平台
- 数学公式用 LaTeX 不确认平台支持
- 不指定代码语言（无高亮）
- 中英混排不加空格（拥挤难读）
- 平台间互导期望 100% 保真
Markdown 的”通用性”是个温柔的谎言——理解方言差异、按目标平台选语法、必要时用转换工具，才能让一份文档真的”跨平台”。