Markdown語法使用指南

Markdown 語法

以下是 Markdown 的常用語法！在以后的筆記中將持續使用 Markdown 語法進行編譯，因此，將此分享給大家。

概述

  • Markdown 的目標是實現 【易讀易寫】
  • Markdown 語法全由一些符號所組成，這些符號經過精挑細選，其作用一目了然。

兼容HTML

  • Markdown 語法的目標是：成為一種適用于網絡書寫的語言

  • Markdown 語法的理念是：讓文檔更容易讀、寫和隨意改

  • HTML 是一種發布的格式，Markdown 是一種書寫的格式

  • Markdown 的格式語法只涵蓋純文本可以涵蓋的范圍

  • 不在 Markdown 涵蓋范圍內的標簽，都可以在文檔里面用 HTML 撰寫，直接加標簽就可以了

  • 要制約的只有一些 HTML 區塊元素，如： <div>、 <table>、 <pre>、<p>標簽等，必須在前后加上空行與其他內容區隔開，還要求它 們的開始標簽與結尾標簽不能用制表符或空格來縮進。

注意：在 HTML 區塊標簽間的 Markdown 格式語法將不會被處理*。

  • HTML 的區段(行內)標簽，如： <span>、 <site>、 <del>可以在 Markdown 的段落里邊或是標題里隨意使用，依照個人習慣，甚至可以不用 Markdown 格式，而直接采用 HTML 標簽來格式化。

注意：在 HTML 區段標簽間的 Markdown 格式語法是有效的.

特殊字符自動轉換

在 HTML文件中，有兩個字符需要特殊處理：< 和 &。
< 符號用于起始標簽， & 符號則用于標記 HTML 實體
如果你只是想要顯示這些字符的原型，則需要使用實體字符的形式，像是:

< 和 &。

&字符：

  • 如果要輸入 AT&T；，則必須寫成：
AT &T
  • 如果輸入網址中含有 &，也同樣需要換成實體字符：
key &value

才能放到鏈接標簽的 href 屬性里

  • Merkdown 可以讓你自然的書寫字符，它可以處理字符轉換。如果你使用的 & 字符是 HTML 字符實體的一部分，它會保留原狀，否則它會被轉換成
&

  • 類似的情況也會發生在 < 符號上，因為 Markdown 允許兼容 HTML ，如果你是把 < 符號作為 HTML 標簽的定界符使用，那 Markdown 也不會對它做任何轉換

  • 但是如果把 < 當成其他連接符號使用，如：

4 < 5

Markdown 將會把它轉換為：

4 < 5

不過需要注意的是：code 范圍內，不論是行內還是區塊，< 和 & 兩個符號都一定會被轉換成 HTML 實體，這項特性讓你可以很容易地用 Markdown 寫 HTML code(和 HTML 相對而言 HTML 語法中，你要把所有的 < 和 & 都轉換為HTML實體，才能在HTML文件里面寫出 HTML code)。

區塊元素

段落和換行

一個 Markdown 段落是由一個或多個連續的文本行組成，它的前后要有一個以上的空行（空行的定義是顯示上看起來像是空的，便會被視為空行。
比方說，若某一行只包含空格和制表符，則該行也會被視為空行。普通段落不該用空格或制表符來縮進。

  • 「由一個或多個連續的文本行組成」這句話其實暗示了 Markdown 允許段落內的強迫換行（插入換行符 </br>）
  • 如果你確實想要依賴 Markdown 來插入
    標簽的話:
空格 + 空格 + enter = 換行
  • Markdown 中email式的區塊引用和多段落的列表在使用換行來排版的時候，不但更好用，還更方便閱讀。

標題

  • Markdown 支持兩種標題的語法，類 Setext 和類 atx 形式。
  • 類 Setext 形式是用底線的形式，利用 =（最高階標題）和 -（第二階標題）
  • 類 Atx 形式則是在行首插入1到6個 #，對應到標題1到6階，例如：
 # 這是H1標題  

 ## 這是H2標題  

 ### 這是H3標題  

 #### 這是H4標題  

 ##### 這是H5標題

 ###### 這是H6標題
  • 我更推薦適用類 atx 樣式的標題，這與我們平常的 html 標題標簽基本上一致
  • 也可以選擇性地「閉合」類 atx 樣式的標題，這純粹只是美觀用的，若是覺得這樣看起來比較舒適，你就可以在行尾加上 #，而行尾的 # 數量也不用和開頭一樣。
    行首的井字符數量決定標題的階數

區塊引用 Blockquotes

  • Markdown 標記區塊引用是使用類似 email 中用 > 的引用方式。
  • Markdown 文件中建立一個區塊引用，那會看起來像是你自己先斷好行，然后在每行的最前面加上 > ：
 > This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
 > consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
  • Markdown 也允許你偷懶只在整個段落的第一行最前面加上 > ：
 > This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
  consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
  • 區塊引用可以嵌套（例如：引用內的引用），只要根據層次加上不同數量的 > ：
> This is the first level of quoting.
>
> > This is nested blockquote.
>
> Back to the first level.
  • 引用的區塊內也可以使用其他的 Markdown 語法，包括標題、列表、代碼區塊等：
> ## 這是一個標題。
> 1.   這是第一行列表項。
> 2.   這是第二行列表項。

任何像樣的文本編輯器都能輕松地建立email型的引用。例如在 BBEdit 中，你可以選取文字后然后從選單中選擇增加引用階層。

列表

Markdown 支持有序列表和無序列表。

  • 無序列表使用星號、加號或是減號作為列表標記:

     * 這是一個無序列表
 + 這是一個無序列表
 - 這是一個無序列表

  • 通過 table 鍵可以實現無序列表的嵌套:

    + 這是無序列表
   + 這是無序列表的嵌套
   + 這是無序列表的嵌套
       * 這是無序列表的嵌套的嵌套
       - 這是無序列表的嵌套的嵌套    
* 這是無序列表

  • 有序列表則使用數字接著一個英文句點:

     1. 這是一個有序列表1
 2. 這是一個有序列表2
 3. 這是一個有序列表3

很重要的一點是，你在列表標記上使用的數字并不會影響 HTML 輸出的順序，上面的列表數字即使是胡亂排序的， HTML 也會按列表自上而下進行排列

  • Markdown 文件的列表數字和輸出的結果不由編碼的大小來決定,你可以懶一點，Markdown 可以完全不用在意數字的正確性。

  • 如果你使用懶惰的寫法，建議第一個項目最好還是從 1. 開始，因為 Markdown 未來可能會支持有序列表的 start 屬性。

  • 列表項目標記通常是放在最左邊，也可以縮進最多3個空格，項目標記后面則一定要接著至少一個空格或制表符。

  • 要讓列表看起來更漂亮，你可以把內容用固定的縮進整理好：

Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,  
viverra nec, fringilla in, laoreet vitae, risus.
  • 但是如果你懶，那也行：
Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
     Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
         viverra nec, fringilla in, laoreet vitae, risus.

  • 列表項目可以包含多個段落，每個項目下的段落都必須縮進 4 個空格或是 1 個制表符：

  1. This is a list item with two paragraphs. Lorem ipsum dolor
    sit amet, consectetuer adipiscing elit. Aliquam hendrerit
    mi posuere lectus.
  2. Suspendisse id sem consectetuer libero luctus adipiscing.
+ 如果你每行都有縮進，看起來會整潔很多，當然，如果你很懶惰，Markdown 也允許：
  • This is a list item with two paragraphs.
    This is the second paragraph in the list item. You're
    only required to indent the first line. Lorem ipsum dolor
    * sit amet, consectetuer adipiscing elit.
+ 如果要在列表項目內放進引用，那 > 就需要縮進：

  • A list item with a blockquote:

    This is a blockquote
    inside a list item.

+ 如果要放代碼區塊的話，該區塊就需要縮進兩次，也就是 8 個空格或是 2 個制表符：
  • 一列表項包含一個列表區塊：
    <代碼寫在這>
 當然，項目列表很可能會不小心產生，像是下面這樣的寫法：
  1. What a great season.
在行首出現數字-句點-空白的情況，避免這樣的狀況，你可以在句點前面加上反斜杠。

#### 代碼區塊

和程序相關的寫作或是標簽語言原始碼通常會有已經排版好的代碼區塊，通常這些區塊我們并不希望它以一般段落文件的方式去排版，而是照原來的樣子顯示，Markdown 會用 &lt;pre> 和  &lt;code> 標簽來把代碼區塊包起來。
要在 Markdown 中建立代碼區塊很簡單，只要簡單地縮進4個空格或是1個制表符就可以，例如，下面的輸入：

這是一個普通段落：

這是一個代碼區塊。

Markdown 會轉換成:

<p> 這是一個普通段落：</p>

<pre><code>這是一個代碼區塊。</pre></code>

這個每行一階的縮進( 4 個空格或是 1 個制表符)，都會被移除，例如：

Here is an example of AppleScript:

tell application "Foo"
    beep
end tell

會被轉換為：

<p>Here is an example of AppleScript:</p>

<pre><code>tell application "Foo"
beep
end tell
</pre></code>

一個代碼區塊會一直持續到沒有縮進的那一行（或是文件結尾）。

在代碼區塊里面，&、<、> 會自動轉成 HTML 實體，這樣的方式讓你非常容易使用 Markdown 插入范例用的HTML原始碼，只需要復制貼上，再加上縮進就可以了，剩下的Markdown都會幫你處理，例如：

<div class="footer">
? 2004 Foo Corporation
</div>

會被轉換為：

<pre><code><div class="footer">
? 2004 Foo Corporation
</div>
</code></pre>

代碼區塊中，一般的 Markdown 語法不會被轉換，像是星號便只是星號，這表示你可以很容易地以 Markdown 語法撰寫 Markdown 語法相關的文件。

#### 分隔線
你可以在一行中用三個以上的星號、減號、底線來建立一個分隔線，行內不能有其他東西。你也可以在星號或是減號中間插入空格。下面每種寫法都可以建立分隔線：

————————————————————————————

> 區段元素

#### 鏈接
Markdown 支持兩種形式的鏈接語法：**行內式**和**參考式**兩種形式。
不管是哪一種，鏈接文字都是用 \[ 方括號 \] 來標記。 

** 行內式鏈接 **
+ 行內式的鏈接是用一個方括號緊跟著一個圓括號標識的：\[鏈接文字\]\(鏈接地址)
+ \[\]  是 &lt;a&gt; 標簽包含著的鏈接文字&lt;/a&gt;
+ \(\)  是  &lt;a&gt; 標簽 href 指向的鏈接地址
+ 鏈接后可跟 title 屬性，title 不是必須屬性，根據需來設置**

This is an example inline link.

例如：

[Markdown語法](https://github.com/WinSolstice/tools/blob/master/README.md title="WinSolstice的markdown語法總結")

 注釋：\[鏈接文字\](鏈接地址 title)

Markdown會自動轉換為：

<p>
<a title="WinSolstice的markdown語法總結">
Markdown語法</a>
</p>

HTML輸出為：  
<p><a  title="Title">
Markdown語法</a></p>  
如果你是要鏈接到同樣主機的資源，你可以使用相對路徑：
<p>

See my About page for details

</p>
<h4> 參考式鏈接 </h4>
<li>考式鏈接是用兩個方括號標識的：\[鏈接文字\]\[用以辨識鏈接的id\]</li>
<li>然后在文件的任意處，你可以把這個id對應的鏈接地址定義出來</li>
<li>鏈接后可跟 title 屬性，title 不是必須屬性，根據需來設置</li>

This is an example reference-style link.
id: http://example.com/ "Optional Title Here"

例如：

[Maekdown語法][WinSolstice title="WinSolstice的markdown語法總結"]

[鏈接文字][用以辨識鏈接的id title]

定義 id ：id對應的鏈接地址 


Markdown會自動轉換為：

<p>
<a title="WinSolstice的markdown語法總結">
Maekdown語法</a>
</p>

+ 定義id對應的鏈接地址：

HTML輸出：  

[Maekdown語法][WinSolstice] 
[WinSolstice]:https://github.com/WinSolstice/tools/blob/master/README.md


<p>*此處是[ ]的兼容問題，正常情況下點擊html會產生<a  title="WinSolstice的markdown語法總結">
Markdown語法</a>的效果*</p>

**鏈接內容定義的形式為:**

- 方括號（前面可以選擇性地加上至多三個空格來縮進），里面輸入鏈接文字，
- 接著一個冒號，
- 接著一個以上的空格或制表符，
- 接著鏈接的網址，
- 選擇性地接著 title 內容，可以用單引號、雙引號或是括弧包著,或者將title 屬性放到下一行，也可以加一些縮進，若網址太長的話，這樣會比較好看： 
+ 鏈接網址也可以用尖括號包起來：
+ 鏈接辨別標簽可以有字母、數字、空白和標點符號，但是并不區分大小寫，因此下面兩個鏈接是一樣的：  
下面這三種鏈接的定義都是相同：

[foo]: http://example.com/ Optional "Title Here"
[foo]: http://example.com/ Optional 'Title Here'
[foo]: http://example.com/ (Optional Title Here)
id: http://example.com/ "Optional Title Here"

*請注意：有一個已知的問題是 Markdown.pl 1.0.1 會忽略單引號包起來的鏈接 title。* 

+ 隱式鏈接標記功能讓你可以省略指定鏈接標記，這種情形下，鏈接標記會視為等同于鏈接文字，要用隱式鏈接標記只要在鏈接文字后面加上一個空的方括號，如果你要 讓 "Google" 鏈接到 google.com，你可以簡化成：
    [Google]: []

然后定義鏈接內容：

由于鏈接文字可能包含空白，所以這種簡化型的標記內也許包含多個單詞：

Visit Daring Fireball for more information.

然后接著定義鏈接：

鏈接的定義可以放在文件中的任何一個地方，我比較偏好直接放在鏈接出現段落的后面，你也可以把它放在文件最后面，就像是注解一樣。

下面是一個參考式鏈接的范例：

I get 10 times more traffic from Google than from
Yahoo or MSN.

如果改成用鏈接名稱的方式寫：

I get 10 times more traffic from Google than from
Yahoo or MSN.

上面兩種寫法都會產生下面的 HTML。

<p>I get 10 times more traffic from <a href="http://google.com/"
title="Google">Google</a> than from
<a title="Yahoo Search">Yahoo</a>
or <a title="MSN Search">MSN</a>.</p>

下面是用行內式寫的同樣一段內容的 Markdown 文件，提供作為比較之用：

I get 10 times more traffic from Google
than from Yahoo or
MSN.

參考式的鏈接其實重點不在于它比較好寫，而是它比較好讀，比較一下上面的范例，使用參考式的文章本身只有 81 個字符，但是用行內形式的卻會增加到 176 個字元，如果是用純 HTML 格式來寫，會有 234 個字元，在 HTML 格式中，標簽比文本還要多。

使用 Markdown 的參考式鏈接，可以讓文件更像是瀏覽器最后產生的結果，讓你可以把一些標記相關的元數據移到段落文字之外，你就可以增加鏈接而不讓文章的閱讀感覺被打斷。



#### 強調
Markdown 使用星號 \* 和底線 \_ 作為標記強調字詞的符號，被 \* 或 \_ 包圍的字詞會被轉成用&lt;em&gt;
標簽包圍，用兩個 \** 或 \__ 包起來的話，則會被轉成&lt;strong&gt;，例如：

single asterisks

single underscores

double asterisks

double underscores_


會轉成：

<em>single asterisks</em>

<em>single underscores</em>

<strong>double asterisks</strong>

<strong>double underscores</strong>

你可以隨便用你喜歡的樣式，唯一的限制是，你用什么符號開啟標簽，就要用什么符號結束。

強調也可以直接插在文字中間：

unfriggingbelievable

但是**如果你的 * 和 _ 兩邊都有空白的話，它們就只會被當成普通的符號。**

如果要在文字前后直接插入普通的星號或底線，你可以用反斜線：

*this text is surrounded by literal asterisks*

#### 代碼

如果要標記一小段行內代碼，你可以用反引號把它包起來（`），例如：

Use the printf() function.

會產生：

<p>Use the <code>printf()</code> function.</p>

如果要在代碼區段內插入反引號，你可以用多個反引號來開啟和結束代碼區段：

There is a literal backtick (`) here.

這段語法會產生：

<p><code>There is a literal backtick (`) here.</code></p>

代碼區段的起始和結束端都可以放入一個空白，起始端后面一個，結束端前面一個，這樣你就可以在區段的一開始就插入反引號：

A single backtick in a code span: `

A backtick-delimited string in a code span: `foo`

會產生：

<p>A single backtick in a code span: <code>`</code></p>

<p>A backtick-delimited string in a code span: <code>foo</code></p>

在代碼區段內，& 和 < 都會被自動地轉成 HTML 實體，這使得插入 HTML 原始碼變得很容易，Markdown 會把下面這段：

Please don't use any <blink> tags.

轉為：

<p>Please don't use any <code><blink></code> tags.</p>

你也可以這樣寫：

— is the decimal-encoded equivalent of —.

以產生：

<p><code>—</code> is the decimal-encoded
equivalent of <code>—</code>.</p>


#### 圖片

很明顯地，要在純文字應用中設計一個「自然」的語法來插入圖片是有一定難度的。

Markdown 使用一種和鏈接很相似的語法來標記圖片，同樣也允許兩種樣式： 行內式和參考式。
 + 行內式的圖片語法:
+ 行內式的圖片語法由：![圖片名稱]（圖片地址)組成
+ 圖片名稱沒有的情況選可以只寫空格
+ 圖片地址可以是圖片的 url 或者是本地圖片路徑
+ 圖片地址后可跟 title 屬性，title 不是必須屬性，根據需來設置
    ```
  ![](/path/to/img.jpg)

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

** 參考式的圖片語法則長得像這樣：**

![Alt text][id]

  • [id」是圖片參考的名稱，圖片參考的定義方式則和連結參考一樣：

到目前為止， Markdown 還沒有辦法指定圖片的寬高，如果你需要的話，你可以使用普通的 <img> 標簽

其它

自動鏈接

  • Markdown 支持以比較簡短的自動鏈接形式來處理網址和電子郵件信箱，只要是用尖括號包起來， Markdown 就會自動把它轉成鏈接。
    一般網址的鏈接文字就和鏈接地址一樣，例如：
<wawacai.xin.com>

Markdown 會轉為：

<a >http://wawacai.xin.com</a>

郵址的自動鏈接也很類似，只是 Markdown 會先做一個編碼轉換的過程，把文字字符轉成 16 進位碼的 HTML 實體，這樣的格式可以糊弄一些不好的郵址收集機器人，例如：

<address@example.com>

Markdown 會轉成：

<a href="mailto:addre
ss@example.co
m">address@exa
mple.com</a>

在瀏覽器里面，這段字串其實是

 <a href="mailto:address@example.com">address@example.com </a>

會變成一個可以點擊的「address@example.com」鏈接。

這種作法雖然可以糊弄不少的機器人，但并不能全部擋下來，不過總比什么都不做好些。不管怎樣，公開你的信箱終究會引來廣告信件的。

反斜杠

Markdown 可以利用反斜杠來插入一些在語法中有其它意義的符號，例如：如果你想要用星號加在文字旁邊的方式來做出強調效果（但不用 <em> 標簽），你可以在星號的前面加上反斜杠：

\*literal asterisks\*

Markdown 支持以下這些符號前面加上反斜杠來幫助插入普通的符號：

\   反斜線
`   反引號
*   星號
_   底線
{}  花括號
[]  方括號
()  括弧
#   井字號
+   加號
-   減號
.   英文句點
!   驚嘆號
最后編輯于 ：
?著作權歸作者所有,轉載或內容合作請聯系作者
平臺聲明：文章內容（如有圖片或視頻亦包括在內）由作者上傳并發布，文章內容僅代表作者本人觀點，簡書系信息發布平臺，僅提供信息存儲服務。

推薦閱讀更多精彩內容