每个用 Markdown 写过东西的人,大概都经历过同一套困惑:为什么这家平台的表格语法和那家不一样?GitHub 上的删除线和任务列表,搬到别的编辑器就失效了?查语法时搜出来的教程质量参差,版本各异,越查越乱。这些问题的根源都是一个——Markdown 方言(flavors)林立,而多数教程只讲其中一种。
Markdown Guide 是这个领域的权威解法:一份同时面向新手与专家的完整参考,按基本语法、扩展语法、速查表、工具目录与进阶书籍组织,把"什么语法是所有人共有的,什么语法是各家方言加的"讲得清清楚楚。本文按网站的知识结构走一遍,附上每个部分的使用建议。
1、知识结构
Markdown Guide 的网站由 Jekyll 生成,内容分五块。各部分的定位如下:
| 板块 | 内容 | 适合谁 |
|---|---|---|
| Getting Started | 概念、历史与工作原理 | 刚接触的新手 |
| Basic Syntax | Gruber 原始定义的语法 | 所有人必修 |
| Extended Syntax | 各方言扩展的语法 | 需要进阶排版时查 |
| Cheat Sheet | 一页速查表 | 老手日常翻 |
| Tools | 数百个工具目录 | 选型时用 |
这个"基本语法与扩展语法"的二分法是整站最有价值的框架:基本语法出自 John Gruber 2004 年的原始设计文档,所有应用都支持;扩展语法是各实现后来加的——表格、围栏代码块、脚注、任务列表这些常用元素其实都在扩展之列。分清这两层,语法失效之谜就解开了大半。
Markdown 从纯文本到成品的流程是四步:
值得记住的背景:Markdown 由 John Gruber 在 2004 年创造,如今已是世界上最流行的标记语言之一。它的设计哲学写在 Gruber 的原话里——一份 Markdown 文档应当能以纯文本形式直接发布,而不显得被标记污染。这也解释了为什么 Markdown 文件用任何文本编辑器都能打开,软件死了内容也活着。
2、基本语法
基本语法是 Markdown 的"普通话",十一个元素覆盖日常写作的九成需求:
| 元素 | 语法 |
|---|---|
| 标题 | # 到 ###### |
| 粗体 | **文字** |
| 斜体 | *文字* |
| 引用 | > 文字 |
| 有序列表 | 1. 项目 |
| 无序列表 | - 项目 |
| 代码 | 行内 ` 与四个空格缩进 |
| 分隔线 | --- |
| 链接 | [标题](地址) |
| 图片 |  |
注意两个易错点。其一是代码块:原始语法是四个空格缩进,后来流行的三反引号围栏属于扩展语法——但在 GitHub、Reddit 这类主流平台写围栏完全没问题。其二是行内代码与转义:本站这类规范严格的编辑器要求行内代码标注命令、文件名、类名,和速查表的用法一致。
3、扩展语法
扩展语法是各方言的"地方口音"。常用的有这些:
| 元素 | 语法要点 |
|---|---|
| 表格 | 管道符加横线分隔行 |
| 围栏代码块 | 三反引号加语言标注 |
| 脚注 | [^1] 与文末定义 |
| 标题 ID | {#custom-id} |
| 定义列表 | 术语加冒号定义 |
| 删除线 | ~~文字~~ |
| 任务列表 | - [x] 完成 |
| 高亮 | ==文字== |
| 上下标 | H~2~O 与 X^2^ |
使用扩展语法的黄金法则:先用再信。这些元素的支持程度因应用而异——表格和围栏代码块几乎成为事实标准,删除线与任务列表在主流平台也通行,而标题 ID、定义列表、高亮、上下标就要看具体编辑器了。Cheat Sheet 页面附有速查表下载,建议存一份。
4、工具生态
Markdown Guide 维护着一份覆盖数百个应用的工具目录,按用途分类。写作类的常见选择如下:
| 用途 | 推荐工具 |
|---|---|
| 笔记 | Obsidian、Joplin、Simplenote |
| 文档站 | MkDocs、Docusaurus、VuePress |
| 博客静态站 | Jekyll、Ghost |
| 在线编辑 | StackEdit、Dillinger |
| 自出版电子书 | Leanpub |
选工具时有一个官方反复强调的原则:优先选 Markdown 支持完善的,因为这直接决定你文件的移植性。今天写的笔记,五年后要在另一个应用里打开,靠的是当初选了一个方言成分低的工具。判断方法是看它对扩展语法的支持范围,目录里每个工具都有对应的支持说明。
另一个人文向的事实:Markdown Guide 本身的许可证也体现了这一生态的开放性——网站内容采用 CC BY-SA 4.0(知识共享署名-相同方式共享 4.0),源码 MIT,教程可自由取用。
5、总结
Markdown Guide 的价值在于它把一片混沌的方言世界整理成了"基本语法 + 扩展语法"的清晰框架,并配齐了速查表与工具目录,是查语法时的第一落点。基本语法保证你的文字到处能渲染,扩展语法则要求你了解目标平台的方言边界——这套思路比背下某个编辑器的全部语法更可靠。
对于 Markdown 新手,建议从 Getting Started 读起,配合官方教程站边学边练;对于日常写作的老手,建议打印或收藏速查表,扩展语法先小范围验证再大面积使用;对于选型中的团队,建议用工具目录核对候选工具对扩展语法的支持范围,把文件可移植性当硬指标。


