Markdown 徹底指南
概述
Markdown 是一種用於網絡文本書寫的輕量級標記語言，普遍用於我的 blog、github、wiki 中。其實瀏覽器並不能識別 Markdown 的語法，但許多 blog、wiki 平臺以及 github 都內置了 Markdown 編輯器，編輯器會先把 Markdown 文本轉換成 HTML 格式的網頁，而後再把 HTML 網頁交給瀏覽器來顯示。除了上述的內置編輯器外，還有許多能解析 Markdown 語法的編寫工具，這些工具通常都提供瀏覽器預覽和導出成 HTML 或 PDF 文件的功能。javascript
Markdown 的語法由一些符號定義，這些符號夾雜在文本中，用於控制文本的顯示方式。好比兩個星號能夠給文字加粗**加粗**，這兩個星號在 Markdown 編輯器處理後就變成了 HTML 中的<strong>加粗</strong>標籤。相較於 Word 類型編輯器的「所見即所得」而言，Markdown 文件自己是純文本，並無格式，但經過 Markdown 語法符號能提供更加準確的 HTML 類型格式控制同時又沒有 HTML 那麼難以書寫。php
Markdown 的語法須要編輯器才能實現，所以編輯器能夠按照本身的需求添加或者修改某個語法的含義。所以，基本上全部編輯器解析 Markdown 語法的方式都有些許差別，但大致上能夠分紅三類：html
- Classic Markdown：最基礎的 Markdown 語法，全部的編輯器都支持
- Extra Markdown：擴展的 Markdown 語法，增長了表格等元素，不必定都能支持
- Github Markdown：github 文檔使用的 Markdown 語法，包含 Extra Markdown 的全部內容，還增長了代碼高亮、emoji表情等語法，目前許多 blog 平臺（cnblogs，csdn）都支持這種語法
本文主要介紹 Classic 和 Github 的語法，對於只有 Github 支持的語法會用上標\(^g\)註明，同時就在使用 Markdown 中常常遇到的問題給出解決方案。做者但願能在一篇文章中將 Markdown 使用中常常遇到的問題作全面總結，如有錯漏，歡迎指正。java
注：做者在編寫此文的過程當中發現 cnblogs 的 Markdown 編輯器有個別地方處理不符合標準，代碼塊和引用塊的默認樣式有點醜，而且不支持預覽，請各位斟酌後使用。git
語法
標題和段落
標題支持兩種語法：底線格式和井號格式。標題會轉換成 HTML 中的<h1><h2>等標籤，這對於自動生成目錄很是重要（Markdown 沒有自動生成目錄的語法，不過能夠利用其餘的方式）。github
底線格式須要單獨一行，使用至少兩個=或-，只能處理兩階的標題。shell
標題1 === 標題2 ---
井號格式使用 1～6 個的#，最多六階標題。行尾能夠添加任意個#號，並不會被看成標題的一部分。編程
# 標題1 # ## 標題2 ###### 標題6 ##
段落開頭不能使用空格或製表符縮進，連續的文本行會首位相連成爲一個段落（cnblogs編輯器不會合成段落）。不一樣段落之間須要用一個或多個空行（空行能夠包含空字符）分隔。若是想將連續的文本行解釋爲兩個段落，在第一個文本上的末尾鍵入兩個空格後再換行。在生成 HTML 時，段落開頭的空格會被忽略或被解釋爲代碼塊等格式，段落之間的全部空行都會被忽略。ubuntu
行首空格、段間空行都被忽略。 連續文本行會被合成一段。（cnblogs編輯器仍然是兩段） 能夠在第一行最後加兩個空格後換行 就能夠分段了。
行首空格、段間空行都被忽略。
連續文本行會被合成一段。（cnblogs編輯器仍然是兩段）api
能夠在第一行加兩個空格後換行
就能夠分段了。
連接和圖片
連接用於跳轉到其餘頁面，包含行內式和參考式兩種樣式，還可使用簡單的自動連接。跳轉地址能夠用/開頭的相對路徑引用本機資源。
行內式：連接文字和跳轉地址寫在一塊兒。如：
[an example](http://www.cnblogs.com/zhuyuanhao/ "連接title")
an example
參考式：連接文字和跳轉地址分開寫，經過[id]標識聯繫起來。[id]標識能夠包含字母、數字、空白和標點符號，可是並不區分大小寫。跳轉地址部分能夠出如今文件的任意地方。
This is [an example][ID 2] reference-style link.
[id 2]: http://www.cnblogs.com/zhuyuanhao/ "可選title, 能夠用單引號'、雙引號"或括號()包着，也能夠另起一行並縮進"
[iD 3]: <http://www.cnblogs.com/zhuyuanhao/>
'跳轉地址也能夠用尖括號包起來'
隱式參考連接：使用空標識[]，在跳轉地址處使用連接文字做爲標識。
[Google][] [Google]: http://google.com/ "Google Inc."
自動連接：對於網址和電子郵件信箱，只要是用尖括號包起來，Markdown 就會自動把它轉成連接，連接文字和跳轉地址相同。
<http://www.cnblogs.com/zhuyuanhao/> <address@example.com>
http://www.cnblogs.com/zhuyuanhao/
address@example.com
圖片用於在當前頁面顯示圖片，也包含行內式和參考式，只須要在連接的樣式前加一個驚歎號!，就會被識別爲圖片。可使用相對路徑引用本地的圖片，也能使用 url 引用其餘網站的圖片。不過到目前爲止，Markdown 尚未辦法指定圖片的寬高。
行內式：
參考式：
![Alt text][id] [id]: url/to/image "Optional title attribute"
引用塊
引用塊使用右尖括號>標識，能夠在每行都加上>，也能夠只在段落的第一行加>。
> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, > consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.
可使用多個>表示引用塊的不一樣層級。
> This is the first level of quoting. > > > This is nested blockquote. > > Back to the first level.
引用的區塊內也可使用其餘的 Markdown 語法，包括標題、列表、代碼塊等。
> ## This is a header.
>
> 1. This is the first list item.
> 2. This is the second list item.
>
> Here's some example code:
>
> return shell_exec("echo $input | $markdown_script");
代碼
代碼能夠用行內代碼或者代碼塊來表示。
行內代碼使用一個或多個重音符號來表示代碼區域，起始和結束的重音符號個數必須相同。
Use the `printf()` function.
Use the printf() function.
若是想在代碼區域內插入k個重音符號，能夠用k+1個重音符號來開啓和結束代碼區段。
There is a literal ```backtick (``)``` here.
There is a literal backtick (``) here.
若是在起始和結束端都插入空格，就能夠在區域的一開始就插入重音符號。
A single backtick in a code span: `` ` `` A backtick-delimited string in a code span: `` `foo` ``
A single backtick in a code span: `
A backtick-delimited string in a code span: `foo`
Classic 代碼塊使用每行縮進的 4 個空格或是 1 個製表符來表示。在轉換成 HTML 時，每行行首的 4 個空格或 1 個製表符縮進會被移除，其他的空格或製表符會被保留。另外，通常在代碼塊中的 Markdown 語法符號不會被轉換。
Here is an example of AppleScript:
tell application "Foo"
**beep**
end tell
Here is an example of AppleScript:
tell application "Foo"
**beep**
end tell
Github 代碼塊使用三個或以上重音符號(```)放在代碼塊的前一行和後一行。在前一行重音符的後面加上語言名稱，能夠按照該語言的語法對代碼塊內容高亮。若是要在代碼塊中顯示三個重音符，用四個重音符來表示代碼塊起止便可。支持的編程語言參見the languages YAML file，若是要使用沒有語法高亮的代碼塊，用plain標記。
```ruby
require 'redcarpet'
markdown = Redcarpet.new("Hello World!")
puts markdown.to_html
```
require 'redcarpet'
markdown = Redcarpet.new("Hello World!")
puts markdown.to_html
列表
列表包括無序列表和有序列表兩類。列表的每一項都使用標記 + 分隔（至少一個空格或製表符） + 段落的格式，段落的內容能夠跨行，用空格縮進，還能夠包含代碼塊、引用塊等。若是在一個列表項裏添加用空行隔開的多個段落，須要在每一個段落開頭添加至少兩個空格。若是要表示多級列表，須要在下一級列表標記前加上至少兩個空格或一個製表符，多級列表能夠混用不一樣的標記（cnblogs的 Markdown 不支持多級列表）。
無序列表使用星號*、加號+或是減號-做爲列表標記，標記不能混用，不然會視爲不一樣的列表。
有序列表則使用數字和一個英文句點表示，數字的內容是任意的，並不會影響 HTML 顯示的數字。有時不須要列表，但在段落開頭的文字是數字加句點的格式，爲了避免被 Markdown 解析成列表，須要在句點前加上反斜線，如：2016\. Something Begin.
+ 無序列表項1 + 無序列表項2 + 下一級列表 2. 再下一級列表1 2. 再下一級列表2 - 不一樣標記視爲不一樣列表 - 列表還能夠 ```c # 包含代碼塊 int a = 10; ``` - 或者引用 > I have a dream! - 以及多行或多段。 第二行 第二段 2016\. Something Begin.
表格\(^g\)
表格只能用在Extra Markdown或Github Markdown中。用豎線|和連字符-表示，豎線用於分隔表格中的不一樣列，連字符用於分開表頭和表格主體，連字符添加冒號:還能夠控制單元格對齊方式。書寫時，豎線沒有對齊要求，行首行尾的豎線能夠省略，表頭下須要至少三個連字符分隔。
表格內容能夠包含 Mardown 行內格式，不能添加引用、列表、多行文本，能夠包含代碼行，不能用代碼塊。若要書寫豎線，須要用反斜線轉義\|（cnblogs編輯器支持有問題）。
| 默認左對齊 | 左對齊 | 中對齊 | 右對齊 | | ------ | :--- | :---: | ---: | 頭尾的豎線能夠省略 | 對齊 | 對齊 | 對齊 | **加粗** | `int a;` | 豎線 \| | 連接[Google](www.google.com) |
| 默認左對齊 | 左對齊 | 中對齊 | 右對齊 |
|---|---|---|---|
| 頭尾的豎線能夠省略 | 對齊 | 對齊 | 對齊 |
| 加粗 | int a; |
豎線 | 連接Google |
文字樣式和轉義符號
文字樣式包括加粗、斜體、刪除線。其中 Classic Markdown 不支持刪除線。加粗用**或__表示，斜體用*或_表示，刪除線用~~表示。若是樣式符號兩邊都沒有文字的話，會被看成普通符號，如：** 符號 **效果爲 ** 符號 **
| 樣式 | 語法 | 舉例 | 效果 |
|---|---|---|---|
| 加粗 | **或__ |
**文本**或 __文本__ |
文本或 文本 |
| 斜體 | *或_ |
*文本*或 _文本_ |
文本或_文本_ |
| 刪除線 | ~~ |
~~文本~~ |
|
| 混合 | 將上述符號混合 | **~~文本~~*混合* **效果 |
對於 Markdown 中的語法符號，前面加反斜線\便可顯示符號自己。包括
\\ 反斜線
\` 重音號
\* 星號
\_ 下劃線
\{\} \[\] \(\) 括號
\# 井號
\+ 加號
\- 減號
\. 句點
\! 驚歎號
\ 反斜線
` 重音號
* 星號
_ 下劃線
{} [] () 括號
# 井號
+ 加號
- 減號
. 句點
! 驚歎號
分割線用三個以上的星號*、減號-或下劃線_表示，符號之間能夠用空格分開但行內不能有其餘非空白符號。
*** - - - _______
任務列表\(^g\)和emoji表情\(^g\)
Github Markdown 支持任務列表樣式和 emoji 表情符號。（cnblogs編輯器裏，這兩項的支持都不是很好）
任務列表須要在 Markdown 列表項的段落部分用[ ]開頭，也能夠用[x]開頭表示一個已選擇的任務項。
- [x] 學習 Markdown - [ ] 使用 Markdown 1. [ ] 寫博客
emoji表情使用:EMOJICODE:的格式，詳細的表情列表參見EMOJI CHEAT SHEET。
:man: :thumbsup: :sunny: :bug:
在 Github 平臺還有兩個特殊的功能：使用@user/team來通知用戶或者用戶組或使用#number引用某個 Issue 或者 Pull Request。這兩個功能只在 Github 平臺有效，這裏就不詳述了，能夠參考mentioning-users-and-teams。
HTML 標籤
Markdown 中能夠直接書寫大部分 HTML 標籤。其中在 HTML 的區塊類型標籤<div>、<table>、<pre>、<p> 等內的，Markdown 語法會失效，在 HTML 行內型標籤<span>、<cite>、<del> 等內，Markdown 語法仍然有效。須要注意的是，在 HTML 標籤內，書寫特殊字符 < 和 & 仍然須要用它們的替代形式 < 和 &表示。在 Markdown 中，也能用 < 和 & 的這種特殊形式。
This is <a href="http://cn.bing.com/images/search?q=markdown&go=Submit+Query">Markdown</a> regular paragraph.
1 < 3 & 5
2 < 4 & 6
<table border="1" bgcolor="yellowgreen">
<tr>
<td>**count** 1 </td>
<td>**count** 2 < 4 & 6</td>
</tr>
</table>
This is **<em>another regular** paragraph</em>.
This is Markdown regular paragraph.
1 < 3 & 5
2 < 4 & 6
| count 1 | count 2 < 4 & 6 |
This is another regular paragraph.
支持 Tex 公式
在 Markdown 中添加 Tex 公式有兩種方式：請求外部服務器生成或者本地生成
外部服務器生成方式是發送 Tex 公式到外部服務器，而後服務器會將 Tex 公式的圖片發送回來，這種方式不能處理複雜的 Tex 語法。使用 HTML <img>標籤，將 Tex 公式寫在 <img>標籤的 url 連接的參數裏。如：
Google Chart服務器
<img src="http://chart.googleapis.com/chart?cht=tx&chl=\Large x=\frac{-b\pm\sqrt{b^2-4ac}}{2a}">
forkosh服務器
<img src="http://www.forkosh.com/mathtex.cgi? \Large x=\frac{-b\pm\sqrt{b^2-4ac}}{2a}">
本地生成方式將 Tex 解析腳本插入到 HTML 文件的<head>標籤中，在 HTML 文件渲染的過程當中生成 Tex 公式，當網頁中 Tex 公式比較多時速度會變慢。推薦使用 MathJax 引擎來實現，經過將下列 JS 腳本嵌入到生成的 HTML 文件<head>標籤中，就能解析 Tex 公式了。Markdown 文件不該包含 <script> 標籤，通常是經過修改 Markdown 編輯器的設置來自動添加。
<script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
行間公式（$$Tex$$）：$$x=\frac{-b\pm\sqrt{b^2-4ac}}{2a}$$
\[x=\frac{-b\pm\sqrt{b^2-4ac}}{2a}\]
行內公式（$Tex$或\\(Tex\\)）：\\(x=\frac{-b\pm\sqrt{b^2-4ac}}{2a}\\)
\(x=\frac{-b\pm\sqrt{b^2-4ac}}{2a}\)
csdn 的 Markdown 編輯器默認支持 Tex 公式，cnblogs 須要在博客「選項」中選中「啓用數學公式支持」，MarkdownPad2 須要在Tools > Options > Advanced > HTML Head Editor中添加 MathJax 引擎，在F6預覽中顯示 Tex 公式。
免費編輯器
書寫 Markdown 離不開編輯器。這裏羅列各個平臺下的免費編輯器供參考
| 平臺 | 編輯器 |
|---|---|
| Windows | MarkdownPad2 |
| Mac | Mou |
| Linux | ReText |
| 線上編輯器 | Dillinger.io、StackEdit |
| 博客平臺 | cnblogs、csdn、簡書 |
| Chrome插件 | Markdown Preview Plus |
另外，Sublime、Vim都帶有 Markdown 預覽插件。
免費圖牀
Markdown 文件自己不能包含圖片。所以，要發佈帶圖片的 Markdown 文章，就須要先將圖片存放在網絡上，經過 url 地址引用圖片：。博客平臺通常會提供圖片上傳服務，這樣就能夠在博客中引用圖片的 url ，可是轉發到博客外部就不必定能訪問。網絡圖牀服務器中的圖片能在全部地方訪問，但也有網絡失效或者服務器關閉的風險。
這裏羅列幾個比較好用的圖牀服務器
| 地址 | 說明 |
|---|---|
| https://sm.ms/ | 國際圖牀，無註冊、不限流量 |
| Github | 能夠把圖片上傳到github上 |
| https://portal.qiniu.com | 國內雲存儲服務七牛雲，需註冊、有流量限制，但能夠本身控制 |
| http://yotuku.cn/ | 國內圖牀，無註冊、不限流量 |
參考連接
Classsic Markdown：http://daringfireball.net/projects/markdown/syntax/
Classsic Markdown的翻譯版：http://wowubuntu.com/markdown/
Extra Markdown：https://michelf.ca/projects/php-markdown/extra/
Github Markdown：https://help.github.com/categories/writing-on-github/
MathJax：https://www.mathjax.org/
- 1. Flexbox 徹底指南
- 2. 【VSC】Snippets不徹底指南
- 3. 精讀《useEffect 徹底指南》
- 4. Anaconda徹底入門指南
- 5. iOS ARC 徹底指南
- 6. React Hook 不徹底指南
- 7. PHP-FPM 不徹底指南
- 8. systemctl命令徹底指南
- 9. Angular $q 徹底指南
- 10. FlexBox佈局徹底指南
- 更多相關文章...
- • SQL 指南 - 網站建設指南
- • HTML 指南 - 網站建設指南
- • 算法總結-雙指針
- • Github 簡明教程
-
每一个你不满意的现在，都有一个你没有努力的曾经。
- 1. Flexbox 徹底指南
- 2. 【VSC】Snippets不徹底指南
- 3. 精讀《useEffect 徹底指南》
- 4. Anaconda徹底入門指南
- 5. iOS ARC 徹底指南
- 6. React Hook 不徹底指南
- 7. PHP-FPM 不徹底指南
- 8. systemctl命令徹底指南
- 9. Angular $q 徹底指南
- 10. FlexBox佈局徹底指南