Markdown 语法速查与 GFM 差异
日常写 Markdown 用到的语法一屏就放得下，用 # 写标题，用 * 和 ** 写强调，再加上列表、链接、图片、代码块、引用和表格。容易让人踩坑的是 Markdown 并不是单一标准，CommonMark 定义了核心部分，GitHub Flavored Markdown（GFM）在上面加了表格、任务列表、删除线和自动链接，脚注、公式、图表这些就要看各个应用自己怎么实现。这份速查按核心语法和扩展语法分开写，每条带示例，并标出妙言实际能渲染什么。
核心语法（CommonMark）
标题
# 一级标题
## 二级标题
### 三级标题
# 后面要留一个空格，一共六级，从 # 到 ######。一篇笔记里最好只放一个 # 标题，其余层级用来分章节，大纲和目录都是靠它们生成的。妙言里有至少两个标题的笔记会自动生成目录，用 ⌘5 打开。
强调和行内代码
*斜体* 或 _斜体_
**粗体** 或 __粗体__
***粗斜体***
`行内代码`
命令、文件名、设置项这类读者要照着敲或照着找的东西，都放进反引号里。
列表
- 无序项
- 另一项
- 嵌套项，缩进两个空格
1. 第一
2. 第二
3. 第三
嵌套项要和上一级文字的起始位置对齐，在妙言列表里按 return 会接着写下一项，连按两次 return 就退出列表。
链接和图片
[链接文字](https://example.com)
图片语法就是链接语法前面多一个 !。妙言把本地附件放在笔记旁边的 i/ 文件夹里，写成 /i/<文件名>，所以整个目录搬走以后笔记照样能用。
代码块
```python
print("hello")
```
起始围栏后面的单词是语言名，决定语法高亮，图表工具也是靠同样的围栏拿到输入，语言名写成 mermaid、plantuml 或 markmap 即可。
引用和分隔线
> 一行引用。
> 同一段引用里的另一行。
---
单独一行三个短横线就是分隔线，妙言的演示模式里同样的 --- 会开始新的一页，所以做幻灯片时一页里面不要再放分隔线，详见 Markdown 转幻灯片。
段落和换行
CommonMark 里段落中间的单个换行是软换行，渲染出来是一个空格，空一行才是新段落，想强制换行要在行尾加两个空格或一个反斜杠。各个应用在这里并不一致，妙言的设置里有一项换行方式，可以选「妙言」（默认，预览中每次换行都会另起一行）或「Github」（预览中需要空一行才会换行）。同一段文字在一个应用里连成一团、在另一个应用里却散开，多半就是这个原因。
转义
在会被 Markdown 当作语法的字符前面加反斜杠，比如 \*不是斜体\* 或 \# 不是标题，行内代码和代码块里面不需要转义。
GFM 扩展
表格
| 品名 | 价格 | 有货 |
|:-----|-----:|:----:|
| 茶 | 2.50 | 是 |
| 果酱 | 0.50 | 否 |
分隔行里的冒号决定对齐方式，分别是靠左、靠右、居中。源码里各列宽度不用对齐，不过对齐了文件更好读。妙言里输入 /table 再按 Tab 会插入模板，粘贴纯文本之后用「编辑 > 文档排版」（⌘⇧L）可以整理格式。
任务列表
- [x] 写完初稿
- [ ] 补截图
妙言的预览模式里可以直接点复选框切换状态。
删除线
~~删掉的文字~~
自动链接
GFM 会把纯文本网址变成链接，不过妙言的解析器只打开了 table、footnotes、strikethrough 和 tasklist 这几个扩展，autolink 不在其中，重要的网址写成 <https://example.com> 或普通链接更稳妥。
GFM 之外
脚注
这个说法需要出处。[^1]
[^1]: 出处在这里。
GFM 规范里没有脚注，所以把它当作应用自己的功能，妙言开启了脚注解析。
公式和图表
行内公式写 $E = mc^2$，块级公式写 $$ ... $$，图表用 mermaid 围栏代码块。这两样都属于渲染器的功能，见 Markdown 里写 LaTeX 公式 和 Markdown 里画 Mermaid 图。
提示块
> [!NOTE]
> 补充说明。
妙言认得 NOTE、TIP、IMPORTANT、WARNING 和 CAUTION，别的应用里这些多半只显示成普通引用。
原生 HTML 和折叠区域
<details>
<summary>展开</summary>
空一行之后里面可以继续写 Markdown。
</details>
妙言的预览会渲染原生 HTML，输入 /fold 再按 Tab 就能插入这段结构。
双链和 frontmatter
[[项目计划]] 按标题原文链接到另一篇笔记，不带 .md 后缀，妙言会据此生成反链。笔记最开头夹在两行 --- 之间的块会当作 frontmatter，在渲染预览里隐藏。
上下标
妙言自带的语法指南里写了 H~2~O 和 26^th^，但妙言并不渲染这种写法，平时不要依赖这种写法，需要的话用 <sub> 和 <sup> 这两个 HTML 标签。
这些东西怎么拼在一起
Markdown 源码先经过解析器变成 HTML，CommonMark 规定核心语法怎么对应到 HTML，GFM 在上面再加一些规则。妙言的预览用的是 cmark-gfm 的 Swift 移植版，挂了 table、footnotes、strikethrough 和 tasklist 四个扩展，生成的 HTML 再装进网页视图，由 KaTeX 完成公式排版，由图表库把围栏代码块变成 SVG。大多数意外都能这样拆开看，在解析器这一步出问题说明语法写错或者不被支持，在后面出问题就是渲染器的事，比如公式有错误或者图表拼写有误。
常见错误
#或-后面没有空格，这一行会保持纯文本。- 表格缺了分隔行，也会保持纯文本。
- 嵌套列表一处用制表符、一处用空格缩进。
- 代码围栏没有成对，会把后面整篇笔记都吞进去，数一数反引号行有几行。
- 紧贴在文字下面的单独一个
---，有些解析器会把它当成标题下划线。
检查一篇笔记时切到预览，看页面上有没有残留的语法字符，它们就是解析器没读懂的那几行。
常见问题
CommonMark 和 GFM 有什么区别
CommonMark 是对核心语法的精确规范，GFM 是它的超集，加了表格、任务列表、删除线、自动链接，以及对原生 HTML 的一条限制规则。
行尾一定要加两个空格吗
只有应用严格遵循 CommonMark、而你又想换行不分段的时候才需要。妙言默认的换行方式是每次换行都另起一行。
能把这份速查贴进妙言试一下吗
可以，应用自带的 Examples 文件夹里有一份妙言 Markdown 语法指南，覆盖了上面每一种写法，完整应用可以在 App Store 和 GitHub 找到。