Markdown語法教程

Markdown 是一種輕量級標記語言，創始人爲 John Gruber。它允許人「使用易讀易寫的純文本格式編寫文檔，然後轉換成有效的 XHTML（或者 HTML）文檔」。——維基百科

背景

優點

專注於文字內容；
純文本，易讀易寫，可以方便地納入版本控制；
語法簡單，沒有什麼學習成本，能輕鬆在碼字的同時做出美觀大方的排版。

使用場景

各類代碼託管平臺
主流的代碼託管平臺，如 GitHub、GitLab、BitBucket、Coding、Gitee 等等，都支持 Markdown 語法，很多開源項目的 README、開發文檔、幫助文檔、Wiki 等都用 Markdown 寫作。
技術社區和寫作平臺
StackOverflow、CSDN、掘金、簡書、GitBook、有道雲筆記
論壇
V2EX、光谷社區

各平臺可能採用不同語言實現的 Markdown 解析引擎，或採用同一解析引擎的不同版本，而且可能有不同程度的定製與擴展，這導致在不同平臺上使用 Markdown 寫作時體驗並不完全一致。不過幸好對於大家公認的一些標準語法，各家都是支持的。

編輯工具

理論上任何一款文本編輯器都能用於編輯 Markdown 文檔，它們分別提供了不同程度的語法高亮、預覽等功能，以下只是列舉其中一部分，選擇自己稱手的即可。

推薦編輯器
Typora / VS Code
傳統編輯器
Vim / Emacs / Sublime Text / Notepad++
IDE 自帶編輯器
IntelliJ IDEA / Android Studio / WebStorm
專用編輯器
Ulysses / Mou / Markpad
在線編輯器
CSDN / 簡書

語法

標題

Markdown：

# atx-style 一級標題

## 二級標題

###### 六級標題

Setext-style 一級標題
===

二級標題
---

預覽效果：

atx-style 一級標題

二級標題

六級標題

Setext-style 一級標題

二級標題

對應 HTML：

<h1>atx-style 一級標題</h1>

<h2>二級標題</h2>

<h6>六級標題</h6>

<h1>Setext-style 一級標題</h1>

<h2>二級標題</h2>

段落

中間沒有空行的連續不斷的幾行文字被視爲一個段落。

Markdown：

白日依山盡，

黃河入海流。
（句號後面沒空格）

欲窮千里目，

更上一層樓。  
（句號後面有倆空格）

預覽效果：

白日依山盡，

黃河入海流。
（句號後面沒空格）

欲窮千里目，

更上一層樓。
（句號後面有倆空格）

對應 HTML：

<p>白日依山盡，</p>

<p>黃河入海流。
（句號後面沒有空格）</p>

<p>欲窮千里目，</p>

<p>
  更上一層樓。
  <br>
  （句號後面有倆空格）
</p>

行內格式

對段落或者部分文本的強調效果。

Markdown：

後面倆字**加黑**

後面倆字*斜體*

預覽效果：

後面倆字加黑

後面倆字斜體

對應 HTML：

<p>
  後面倆字
  <strong>加黑</strong>
</p>
<p>
  後面倆字
  <em>斜體</em>
</p>

引用塊

Markdown：

> 引用塊段落一。
>
> 引用塊段落二。
>> 內嵌引用塊段落一。
>
> ### 引用塊內的標題

預覽效果：

引用塊段落一。

引用塊段落二。

內嵌引用塊段落一。

引用塊內的標題

對應 HTML：

<blockquote>
  <p>引用塊段落一。</p>
  <p>引用塊段落二。</p>
  <blockquote>
    <p>內嵌引用塊段落一。</p>
  </blockquote>
  <h3 id="引用塊內的標題">引用塊內的標題</h3>
</blockquote>

超鏈接

Markdown 支持行內式鏈接和引用式鏈接。

Markdown：

行內式 [博學de叫獸](http://zhangchong.xin/ "博學de叫獸") 鏈接，帶 title。

行內式 [博學de叫獸](http://zhangchong.xin/) 鏈接。

引用式 [博學de叫獸][1] 鏈接。

引用式 [博學de叫獸][2] 鏈接，帶 title。

[1]: http://zhangchong.xin/
[2]: http://zhangchong.xin/ "博學de叫獸"

預覽效果：

行內式博學de叫獸鏈接，帶 title。

行內式博學de叫獸鏈接。

引用式博學de叫獸鏈接。

引用式博學de叫獸鏈接，帶 title。

對應 HTML：

<p>行內式 <a href="http://zhangchong.xin/" title="博學de叫獸">博客</a> 鏈接，帶 title。</p>

<p>行內式 <a href="http://zhangchong.xin/">博學de叫獸</a> 鏈接。</p>

<p>引用式 <a href="http://zhangchong.xin/">博學de叫獸</a> 鏈接。</p>

<p>引用式 <a href="http://zhangchong.xin/" title="博學de叫獸">博學de叫獸</a> 鏈接，帶 title。</p>

圖片

在超鏈接的寫法前加一個 !，就是引用圖片的方法。

Markdown：

![avatar](https://avatar.csdn.net/8/C/2/3_u012102104.jpg)

預覽效果：

對應 HTML：

<img src="https://avatar.csdn.net/8/C/2/3_u012102104.jpg" alt="avatar">

列表

包括有序列表和無序列表。

Markdown：

- 蘋果
- 葡萄
- 榴蓮

1. 蘋果
2. 葡萄
3. 榴蓮

預覽效果：

蘋果
葡萄
榴蓮

蘋果
葡萄
榴蓮

對應 HTML：

<ul>
  <li>蘋果</li>
  <li>葡萄</li>
  <li>榴蓮</li>
</ul>
<ol>
  <li>蘋果</li>
  <li>葡萄</li>
  <li>榴蓮</li>
</ol>

其中無序列表的標記可以使用 +、- 或 *，有序列表前的數字可以是亂序的。

代碼塊

支持行內代碼和代碼塊。

Markdown：
Android 裏使用 TextUtils 類的 isEmpty 方法來判斷字符串是否爲空。

```java
if (TextUtils.isEmpty(text)) {
    return null;
}
```

預覽效果：
Android 裏使用 TextUtils 類的 isEmpty 方法來判斷字符串是否爲空。

if (TextUtils.isEmpty(text)) {
    return null;
}

對應 HTML：

<p>Android 裏使用 <code>TextUtils</code> 類的 <code>isEmpty</code> 方法來判斷字符串是否爲空。</p>

<div class="highlight highlight-source-java"><pre><span class="pl-k">if</span> (<span class="pl-smi">TextUtils</span><span class="pl-k">.</span>isEmpty(text)) {
    <span class="pl-k">return</span> <span class="pl-c1">null</span>;
}</pre></div>

上例中的語言標記 java 可選填，可用於在編輯器和渲染後的效果裏添加語法高亮。塊式代碼也可以對整個代碼段縮進四個空格，或一個 Tab 來實現。

水平分割線

使用一個單獨行裏的三個或以上 *、- 來生產一條水平分割線，它們之間可以有空格。

Markdown：

***

-----

- - -

預覽效果：

對應 HTML：

<hr />

<hr />

<hr />

嵌入 HTML

Markdown 標記語言的目的不是替代 HTML，也不是發明一種更便捷的插入 HTML 標籤的方式。它對應的只是 HTML 標籤的一個很小的子集。
對於那些沒有辦法用 Markdown 語法來對應的 HTML 標籤，直接使用 HTML 來寫就好了。

擴展語法

本節的內容是介紹一些受到廣泛支持的 Markdown 擴展語法。

表格

Markdown：

| 編號  | 姓名（左） | 年齡（右） | 性別（中） |
| ----- | :--------  | ---------: | :------:   |
| 0     | 張三       | 28         | 男         |
| 1     | 李四       | 29         | 男         |

預覽效果：

編號	姓名（左）	年齡（右）	性別（中）
0	張三	28	男
1	李四	29	男

對應 HTML：

<table>
  <thead>
    <tr>
      <th>編號</th>
      <th align="left">姓名（左）</th>
      <th align="right">年齡（右）</th>
      <th align="center">性別（中）</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>0</td>
      <td align="left">張三</td>
      <td align="right">28</td>
      <td align="center">男</td>
    </tr>
    <tr>
      <td>1</td>
      <td align="left">李四</td>
      <td align="right">29</td>
      <td align="center">男</td>
    </tr>
  </tbody>
</table>

任務列表

在 GitHub / GitLab 裏有較好的支持。

Markdown：

- [x] 洗碗
- [ ] 清洗油煙機
- [ ] 拖地

預覽效果：

洗碗
清洗油煙機
拖地

對應 HTML：

<ul class="contains-task-list">
  <li class="task-list-item"><input type="checkbox" id="" disabled="" class="task-list-item-checkbox" checked=""> 洗碗</li>
  <li class="task-list-item"><input type="checkbox" id="" disabled="" class="task-list-item-checkbox"> 清洗油煙機</li>
  <li class="task-list-item"><input type="checkbox" id="" disabled="" class="task-list-item-checkbox"> 拖地</li>
</ul>

刪除線

Markdown：

後面三個字打上~~刪除線~~。

預覽效果：

後面三個字打上~~刪除線~~。

對應 HTML：

<p>後面三個字打上<del>刪除線</del>。</p>

自動鏈接

自動鏈接擴展，即：當識別到 URL，或用 <、> 包括的 URL 時，會自動爲其生成 a 標籤。

Markdown：

http://zhangchong.xin/

<[email protected]>

預覽效果：

http://zhangchong.xin/

[email protected]

對應 HTML：

<p><a href="http://zhangchong.xin/">http://zhangchong.xin/</a></p>

<p><a href="mailto:<[email protected]>"><[email protected]></a></p>

emoji

以 GitHub Pages 爲例。

Markdown：

:camel: :blush: :smile:

預覽效果：

🐫 😊 😄

對應 HTML：

<p>
  <img class="emoji" title=":camel:" alt=":camel:" src="https://assets-cdn.github.com/images/icons/emoji/unicode/1f42b.png" height="20" width="20">
  <img class="emoji" title=":blush:" alt=":blush:" src="https://assets-cdn.github.com/images/icons/emoji/unicode/1f60a.png" height="20" width="20">
  <img class="emoji" title=":smile:" alt=":smile:" src="https://assets-cdn.github.com/images/icons/emoji/unicode/1f604.png" height="20" width="20">
</p>

拓展進階

想象力豐富的工程師們還擴展了很多基於 Markdown 的玩法，包括但不限於：

畫流程圖和時序圖
插入數學公式
用 Markdown 做 PPT
用 Markdown 寫微信公衆號