Markdown 是什么

Markdown 写作约 4 分钟

Markdown 是在纯文本文件里写出带格式文字的一种办法，用几个普通字符当记号，# 表示标题，词两边的 * 表示强调，- 表示列表项，由程序读懂这些记号再转成 HTML，但文件本身不需要任何程序也读得懂，这是大家用它的主要原因。它适合笔记、文档和文章，不适合依赖精确版面的东西，覆盖大多数写作的十个记号，十分钟左右就能学会。

它是怎么来的

John Gruber 在 2004 年发布了 Markdown，他的项目页面把它说成两样东西，一种纯文本格式语法，加一个把这种语法转成 HTML 的 Perl 工具。这些记号取自大家在邮件和 Usenet 帖子里本来就在用的习惯，所以源文件看起来就像你随手敲的一封纯文本邮件。

原始说明在一些地方写得含糊，各家实现不一致。2014 年前后 CommonMark 项目写出了一份没有歧义的规范，GitHub 随后发布了在它之上加入表格和任务列表的 GitHub Flavored Markdown（GFM）。CommonMark 规范里提到 Reddit、StackOverflow 和 GitHub 上有几百万人在用 Markdown，大致就是你会碰到它的地方。有了这段历史，今天说的「Markdown」指的是一个定义清楚的核心，加上各个应用不一样的扩展，细节见 CommonMark 与 GFM 有什么区别。

覆盖大多数写作的十个记号

# Heading
## Subheading

A paragraph with *italic* and **bold** text and `inline code`.

- A bullet item
- Another item

1. A numbered item
2. The next one

[Link text](https://example.com)
![Alt text](photo.png)

> A quoted line.

```python
print("a code block")
```

从上往下读，# 开头是标题，个数决定级别，最多六级；空行分隔段落；单个星号或下划线是斜体，两个是粗体，反引号标出代码；行首的连字符是无序列表，数字加句点是有序列表；链接是方括号写文字、圆括号写地址，图片则是前面多一个 !；以 > 开头的行是引用；三个反引号开始和结束一个代码块，开头三个反引号后面的单词指定语言，用来给代码上色。

接下来很快会用到的还有两个，表格用 | 分列、表头下面一行连字符，任务列表写成 - [ ] 和 - [x]，两者都来自 GFM，不是原始 Markdown 的内容。Markdown 语法速查与 GFM 差异把它们连同容易踩的坑都列了出来。

渲染器怎么把它变成 HTML

Markdown 文件自己什么也不做。一个叫解析器的程序读它，找出记号，建立由标题、段落和列表组成的结构，再由渲染器把这个结构写出来，通常写成 HTML，# Heading 变成 <h1>Heading</h1>，**bold** 变成 <strong>bold</strong>。然后浏览器或网页视图拿样式表把 HTML 画出来，字体、间距和颜色都由样式表决定。

Markdown 文件先由解析器读出结构，渲染器写成 HTML，浏览器再配上样式表画出最终页面。
文件本身不变，解析器决定记号的含义，样式表决定最终的外观。

这个分工解释了新手常见的两件事。一是同一个文件在不同应用里看起来不一样，因为解析器、支持哪些扩展、用什么样式表都是应用自己的选择。二是排版问题基本只有两类，一类是解析器没读懂你的记号，在页面上表现为原样露出的星号或井号，另一类是样式表让它长成了现在这样，这一类改样式就行，不用动文件。

为什么文件一直读得懂

拿 **重要：** 先备份 和同一句话在文字处理软件的文件格式里对比，Markdown 的版本是任何编辑器都能打开的纯文本，可以用任何工具搜索，可以放进 git 仓库，应用没了十年后照样读得出来；文字处理文档是需要对应程序的打包格式。Markdown 文件只是文本，所以体积小，好做 diff，不关心渲染效果的时候，直接复制进邮件或聊天窗口也行。

把笔记存成自己文件夹里的普通文件，也是同一个理由，见 本地优先的 Markdown 笔记怎么管。

哪里会用到

GitHub 会把 README、issue 和评论里的 Markdown 渲染出来，很多人是在那里第一次碰到它。文档站、笔记应用和其他工具也会读它，每个工具支持哪些扩展以各自的文档为准，因为核心是通用的，额外的部分不是。

它不擅长什么

Markdown 描述的是结构，不是外观。它没法说某张图要离页边 2 厘米，没法做分栏，没法指定精确字号，也没法把文字放到某一页的某个位置，表格只能是简单的行和列，要合并单元格得写 HTML。需要精确版面时，用排版工具再导出，或者先写 Markdown 再用能处理样式的程序转换，想从笔记得到可以打印的文件，见 在 Mac 上把 Markdown 转成 PDF。

很多应用里 Markdown 还可以夹带原始 HTML，碰到特殊情况多了一条路，代价是文件的可移植性变差。

在妙言里开始

妙言是一款 Mac 上的 Markdown 编辑器，每篇笔记都是一个普通的 .md 文件，三步就能得到第一篇渲染好的笔记。

  1. 选择「文件」菜单里的「新建」，或者按 ⌘N 新建笔记，用上面的记号写一个标题和几行字。
  2. 选择「视图」菜单里的「切换预览」，或者按 ⌘3，编辑区会变成渲染后的页面，再按一次回到源码；「切换分栏」（⌘\）可以把源码和预览并排放。
  3. 看预览页上有没有残留的记号，比如多出来的 ** 或 #，它们标出解析器没读懂的位置。

妙言 4.5.0 通过 cmark-gfm 解析器渲染 CommonMark 加表格、任务列表、删除线和脚注，预览里另外有公式、提示框和图表。资料库为空的首次启动时还会生成几篇示例笔记，其中有一篇「妙言 Markdown 语法指南」，可以当范例读。选编辑器可以对照 Mac 上怎么选 Markdown 编辑器。

常见问题

Markdown 是编程语言吗？

不是，它是文本的标记语法，没有变量和逻辑，只有解析器转成 HTML 的记号。

要先学 HTML 吗？

不用。只有想要 Markdown 表达不了的东西时才会碰到 HTML，大多数笔记一辈子用不上。

用什么扩展名？

最常见的是 .md，妙言新建的笔记就是这个。