简明 Markdown 教程

markdown 的哲学

设计 markdown 的目的，是实现一种尽可能易读、易写的文档编写方式。

甚至，不需要借助工具，使用纯文本打开，就可以看得挺清楚的。

Markdown 的出现，让写文档轻松了不少。写作者可以更加聚焦内容，而不是样式。

markdown 是写作格式。就是在纯文本的基础上，增加一些标记。

它不是为了替代 HTML 而生的。

是为了简化编写文档而生的。

它定义了一套简单的语法，提供一个转换工具，把它转换成 HTML 。

所以，很长时间以来，都是左边写源码，右边显示预览。

它对文档做了提炼。比 HTML 简单，比 TXT 丰富。

除了 Markdown ，也有一些其他的轻量级标记语言。比如 AsciiDoc、reStructuredText 、 atx 。

历史上，还有 Docbook 这样的标记语言。专门为了写书、写文章而设计的。最终还是简洁占了上风。就想 YAML 一部分替代了 JSON， JSON 一部分替代了 XML 。

它也符合迭代思维、二八原则。只是关注最常用的编写文档的要素。

所见即所得。是软件追求的目标。

语法

Markdown ，就像是 HTML ，也是用来制作、描述文档的。

所以，同样有一些文档元素。

标题、段落、无序列表、有序列表、表格、链接等。

标题

# 一级标题
## 二级标题

通常使用 # ，也有其他的格式，但不建议使用。

无序列表

- 项1
- 项2

通常使用 - ，也有其他格式，但不建议使用。

有序列表

1. 项1
2. 项2

序号不是一定要1 2 3 这样排下来，但建议就是这样写。

链接

[文本](url)

外部链接，增加 _blank ？不支持。直接写 HTML 代码。或者使用 rehype-external-links 这种插件。

表格

可以用 markdown 编写表格，但不容易。二维的东西，用一维表示，是会比较困难的。它有点像 ASCII 图形。

| 字段1   | 字段2   |
| ----- | ----- |
| 单元格A1 | 单元格B1 |
| 单元格A2 | 单元格B2 |

显示效果：

字段1	字段2
单元格A1	单元格B1
单元格A2	单元格B2

代码块

用三个反引号前后把代码包起来。

第一行是三个反引号 ，中间放代码，最后一行也是三个反引号 。
在开头的三个反引号还可以跟着语言，这样可以做语法高亮。

<pre> ```js console.log("Hello"); ``` </pre>

显示效果：

console.log("Hello");

代码

换行的是代码块。不换行的是代码。

用反引号把内容包起来。

`code`

强调

*文本*
**文本2**
_文本3_
__文本4__

显示效果（斜体）：

文本
文本2
文本3
文本4

图片

![Alt text](/path/to/img.jpg)
![Alt text](/path/to/img.jpg "Optional title")

分割线

---

标准

Markdown 没有统一的标准。

起源

最早是 2004 年，由 John Gruber 和 Aaron Swartz ，构思实现的。

Markdown 这个词，由 Mark 和 Down 组成。 Mark 就是 markup ，标记。 down 表示，更轻量，含量更少的意思。

就是为了简化 HTML 标签的编写。

衍生

因为原生的 markdown 的要素太少、功能太少。有些人根据自己的需求，扩充了一些。就出现的 Pandoc Markdown 、GitHub Flavored Markdown 等。

混合HTML

可以的。 markdown 设计之初，只是为了简化 HTML 的文档编写。所以只定义了最常见的元素的 markdown 语法。有些东西，还是可以继续用 HTML 编写。

如何混合？

MD 本来就是一块一块的。所以，可以在其中用 HTML 表示。但是，最好不要在 HTML 中嵌套 MD 。

写文章。以 标题 h 和 段落 p 为主要元素。

This is a regular paragraph.

<table>
    <tr>
        <td>Foo</td>
    </tr>
</table>

This is another regular paragraph.

这就是一个示例。很自然。

工具

编辑工具， Typora 。
转化工具， Pandoc 。它可以在多种文档格式之间互相转换。

后记

为了写好这篇教程，翻了古早的 markdown 文档。才了解到它背后的设计哲学。

它说，HTML 是发布语言，Markdown 是编写格式。

这确实是一种深刻的洞察。

直接用 HTML 写文档，还是有点麻烦的。我深有体会。在写个人网站时，就用 HTML 。后来写教程，就慢慢改成用 Markdown 写了。

参考

• Daring Fireball: Markdown
• Typora
• Pandoc