Markdown基本語法

Markdown基本語法 #

概述 #

幾乎所有 Markdown 應用程序都支持原始 Markdown 設計文檔中概述的基本語法。Markdown 處理器之間存在細微的差異和矛盾 — 我們會盡可能地在行內註明。

標題 #

要創建標題,請在單詞或短語前面添加數字符號(#)。您使用的數字符號數量應與標題級別相對應。例如,要創建三級標題(<h3>),請使用三個數字符號(例如 ### 標題3 )。

Markdown HTML 渲染結果
# 標題級別 1 <h1>標題級別 1</h1>

標題級別 1

## 標題級別 2 <h2>標題級別 2</h2>

標題級別 2

### 標題級別 3 <h3>標題級別 3</h3>

標題級別 3

#### 標題級別 4 <h4>標題級別 4</h4>

標題級別 4

##### 標題級別 5 <h5>標題級別 5</h5>
標題級別 5
###### 標題級別 6 <h6>標題級別 6</h6>
標題級別 6

替代語法 #

或者,在文本下方的行中,為標題 1 添加任意數量的 == 字符,或為標題 2 添加任意數量的 -- 字符。

Markdown HTML 渲染結果
標題級別 1
===============
<h1>標題級別 1</h1>

標題級別 1

標題級別 2
---------------
<h2>標題級別 2</h2>

標題級別 2

標題最佳實踐 #

Markdown 應用程序對於如何處理數字符號 (#) 和標題名稱之間的 空格意見不一。出於兼容性考慮,請始終在數字符號標題名稱之間留一個空格。

✅  推薦 ❌  不推薦
# 標題文字

#標題文字

為了兼容性,您還應該在標題前後放置空行。

✅  推薦 ❌  不推薦
## Head ## Head 

粗體 #

要加粗文本,請在文本前後添加兩個星號(**)或兩個下劃線(__)。

Markdown HTML 渲染結果
I just love **bold text**. I just love <strong>bold text</strong>. I just love bold text.
I just love __bold text__ . I just love <strong>bold text</strong>. I just love bold text.
Love**is**bold Love<strong>is</strong>bold Loveisbold

加粗最佳實踐 #

Markdown 應用程序對如何處理單詞中間的下劃線意見不一。為了兼容性,請盡量使用星號(**)加粗文本。

✅  推薦 ❌  不推薦
Love**is**bold Love__is__bold

斜體 #

要使文本斜體化,請在文本前後添加一個星號(*)或下劃線(_)。

Markdown HTML 渲染結果
Italicized text is the *cat's meow*. Italicized text is the <em>cat's meow</em>. Italicized text is the cat’s meow.
Italicized text is the _cat's meow_. Italicized text is the <em>cat's meow</em>. Italicized text is the cat’s meow.
A*cat*meow A<em>cat</em>meow Acatmeow

斜體最佳實踐 #

Markdown 應用程序對如何處理單詞中間的下劃線意見不一。為了兼容性,請盡量使用星號(*)加粗文本。

✅  推擠 ❌  不推薦
A*cat*meow A_cat_meow

段落 #

要創建段落,請使用空行分隔一行或多行文本。

Markdown HTML 渲染結果
I really like using Markdown.
I think I'll use it to format all of my documents from now on.
<p>I really like using Markdown.<⁄p>
<p>I think I'll use it to format all of my documents from now on.<⁄p>

I really like using Markdown.

I think I'll use it to format all of my documents from now on.

段落最佳實踐 #

除非 段落在列表中,否則不要使用空格或制表符縮進段落。

註意:如果您需要在輸出中縮進段落,請參閱有關如何縮進( 制表符)。
✅  推薦 ❌  不推薦
Don't put tabs or spaces in front of your paragraphs.

Keep lines left-aligned like this.

     This can result in unexpected formatting problems.

  Don't add tabs or spaces in front of paragraphs.

換行符 #

要創建換行符或新行<br>,請在行末添加兩個或更多空格,然後鍵入回車鍵。

Markdown HTML 渲染結果
This is the first line.  
And this is the second line.
<p>This is the first line.<br>
And this is the second line.</p>

This is the first line.
And this is the second line.

換行最佳實踐 #

幾乎每個 Markdown 應用程序中都可以使用兩個或更多空格(通常稱為“尾隨空格”)作為換行符,但這是存在爭議的。在編輯器中很難看到尾隨空格,許多人會無意或故意在每個句子後放兩個空格。因此,您可能希望使用除尾隨空格以外的其他東西作為換行符。如果您的 Markdown 應用程序 支持 HTML,則可以使用 <br> HTML 標簽。

為了兼容性,請在行尾使用尾隨空格或 <br> HTML 標簽。

還有兩個我不推薦使用的選項。CommonMark 和其他一些輕量級標記語言允許你在行尾輸入反斜杠 (\),但並非所有 Markdown 應用程序都支持此功能,因此從兼容性角度來看,這不是一個好選擇。而且至少有幾種輕量級標記語言不需要在行尾輸入任何內容 - 只需輸入回車鍵即可創建換行符。

✅  推薦 ❌  不推薦
First line with two spaces after.  
And the next line.

First line with the HTML tag after.<br>
And the next line.

First line with a backslash after.\
And the next line.

First line with nothing after.
And the next line.

強調 #

您可以通過將文本設為粗體斜體來增加強調效果。

粗體和斜體 #

要同時使用粗體斜體強調文本,請在文本前後添加三個星號*或下劃線_

Markdown HTML 渲染結果
This text is ***really important***. This text is <em><strong>really important</strong></em>. This text is really important.
This text is ___really important___. This text is <em><strong>really important</strong></em>. This text is really important.
This text is __*really important*__. This text is <em><strong>really important</strong></em>. This text is really important.
This text is **_really important_**. This text is <em><strong>really important</strong></em>. This text is really important.
This is really***very***important text. This is really<em><strong>very</strong></em>important text. This is reallyveryimportant text.
註意:根據您使用的 Markdown 處理器,emstrong 標簽的順序可能會顛倒。

粗體和斜體最佳實踐 #

Markdown 應用程序對如何處理單詞中間的下劃線意見不一。為了兼容性,盡量使用星號*將單詞中間加粗和斜體以強調。

✅  推薦 ❌  不推薦
高***桌子***低板凳都是木頭。 高___桌子___低板凳都是木頭。

區塊引用 #

要創建區塊引用,請在段落前面添加 >

> 高桌子低板凳都是木頭。

渲染結果如下所示:

高桌子低板凳都是木頭。

包含多個段落的區塊引用 #

區塊引用可以包含多個段落。在段落之間的空白行上添加 >

> 他大舅他二舅都是他舅。
>
> 高桌子低板凳都是木頭。

渲染結果如下所示:

他大舅他二舅都是他舅。

高桌子低板凳都是木頭。

嵌套的區塊引用 #

區塊引用可以嵌套。在要嵌套的段落前面添加 >>

> 他大舅他二舅都是他舅。
>
>> 高桌子低板凳都是木頭。

渲染結果如下所示:

他大舅他二舅都是他舅。

高桌子低板凳都是木頭。

帶有其他元素的區塊引用 #

區塊引用可以包含其他 Markdown 格式的元素。但並非所有元素都可以使用,您需要進行實驗才能知道哪些元素有效。

> #### 一些方言俗語
>
> - 他大舅他二舅都是他舅。
> - 高桌子低板凳都是木頭。
>
>  *走一步*退一步全當**沒走**。

渲染結果如下所示:

一些方言俗語 #

  • 他大舅他二舅都是他舅。
  • 高桌子低板凳都是木頭。

走一步退一步全當沒走

塊引用最佳實踐 #

為了兼容性,請在塊引用前後放置空行。

✅  推薦 ❌  不推薦
他大舅他二舅都是他舅。

> 高桌子低板凳都是木頭。

走一步退一步全當沒走。
他大舅他二舅都是他舅。
> 高桌子低板凳都是木頭。
走一步退一步全當沒走。

列表 #

您可以將項目組織成有序無序列表。

在列表中添加元素 #

要在列表中添加另一個元素同時保持列表的連續性,請將元素縮進四個空格一個制表符,如以下示例所示。

提示:如果結果與預期不符,請仔細檢查列表中的元素是否縮進四個空格一個制表符

內嵌段落 #

* 這是第一個列表項。
* 這是第二個列表項。

	在第二列表項下方添加另一個段落。

* 這是第三個列表項。

渲染結果如下所示:

  • 這是第一個列表項。

  • 這是第二個列表項。

    在第二列表項下方添加另一個段落。

  • 這是第三個列表項。

內嵌引用塊 #

* 這是第一個列表項。
* 這是第二個列表項。

	> 引用塊放在第二個列表項下面會很好看。

* 這是第三個列表項。

渲染結果如下所示:

  • 這是第一個列表項。

  • 這是第二個列表項。

    引用塊放在第二個列表項下面會很好看。

  • 這是第三個列表項。

內嵌代碼塊 #

代碼塊通常縮進四個空格或一個制表符。當它們在列表中時,縮進八個空格或兩個制表符。

1. 打開文件
2. 在第21行找到如下代碼塊:

        <html>
          <head>
            <title>測試</title>
          </head>

3. 更新標題以與您的網站名稱匹配。

渲染結果如下所示:

  1. 打開文件

  2. 在第21行找到如下代碼塊:

     <html>
       <head>
         <title>測試</title>
       </head>
    
  3. 更新標題以與您的網站名稱匹配。

內嵌圖片 #

1. 打開包含 Linux 吉祥物的文件。
2. 他看起來真不錯。

	![Tux,Linux 吉祥物](/images/tux.png)

3. 關閉文件。

渲染結果如下所示:

  1. 打開包含 Linux 吉祥物的文件。
  2. 他看起來真不錯。

Tux,Linux 吉祥物

  1. 關閉文件。

內嵌列表 #

您可以將無序列表嵌套在有序列表中,反之亦然。

1. 第一項
2. 第二項
3. 第三項
	- 縮進項
	- 縮進項
4. 第四項

渲染結果如下所示:

  1. 第一項
  2. 第二項
  3. 第三項
    • 縮進項
    • 縮進項
  4. 第四項

有序列表 #

要創建有序列表,請添加帶有數字和句點的行項目。數字不必按數字順序排列,但列表應從數字 1 開始。

Markdown HTML 渲染結果
1. 第一項
2. 第二項
3. 第三項
4. 第四項
<ol>
  <li>第一項</li>
  <li>第二項</li>
  <li>第三項</li>
  <li>第四項</li>
</ol>
  1. 第一項
  2. 第二項
  3. 第三項
  4. 第四項
1. 第一項
1. 第二項
1. 第三項
1. 第四項
<ol>
  <li>第一項</li>
  <li>第二項</li>
  <li>第三項</li>
  <li>第四項</li>
</ol>
  1. 第一項
  2. 第二項
  3. 第三項
  4. 第四項
1. 第一項
8. 第二項
3. 第三項
5. 第四項
<ol>
  <li>第一項</li>
  <li>第二項</li>
  <li>第三項</li>
  <li>第四項</li>
</ol>
  1. 第一項
  2. 第二項
  3. 第三項
  4. 第四項
1. 第一項
2. 第二項
3. 第三項
    1. 縮進項
    2. 縮進項
4. 第四項
<ol>
  <li>第一項</li>
  <li>第二項</li>
  <li>第三項
    <ol>
      <li>縮進項</li>
      <li>縮進項</li>
    </ol>
  </li>
  <li>第四項</li>
</ol>
  1. 第一項
  2. 第二項
  3. 第三項
    1. 縮進項
    2. 縮進項
  4. 第四項

有序列表最佳實踐 #

CommonMark 和其他一些輕量級標記語言允許您使用括號 ()) 作為分隔符(例如,1) 第一項),但並非所有 Markdown 應用程序都支持此功能,因此從兼容性角度來看,這不是一個好選擇。為了兼容性,請僅使用句點(.)。

✅  推薦 ❌  不推薦
1. 第一項
2. 第二項
1) 第一項
2) 第二項

無序列表 #

要創建無序列表,請在行項前面添加破折號 (-)、星號 (*) 或加號 (+)。縮進一個或多個項以創建嵌套列表。

Markdown HTML 渲染結果
- 第一項
- 第二項
- 第三項
- 第四項
<ul>
  <li>第一項</li>
  <li>第二項</li>
  <li>第三項</li>
  <li>第四項</li>
</ul>
  • 第一項
  • 第二項
  • 第三項
  • 第四項
* 第一項
* 第二項
* 第三項
* 第四項
<ul>
  <li>第一項</li>
  <li>第二項</li>
  <li>第三項</li>
  <li>第四項</li>
</ul>
  • 第一項
  • 第二項
  • 第三項
  • 第四項
+ 第一項
+ 第二項
+ 第三項
+ 第四項
<ul>
  <li>第一項</li>
  <li>第二項</li>
  <li>第三項</li>
  <li>第四項</li>
</ul>
  • 第一項
  • 第二項
  • 第三項
  • 第四項
- 第一項
- 第二項
- 第三項
    - 內嵌項
    - 內嵌項
- 第四項
<ul>
  <li>第一項</li>
  <li>第二項</li>
  <li>第三項
    <ul>
      <li>內嵌項</li>
      <li>內嵌項</li>
    </ul>
  </li>
  <li>第四項</li>
</ul>
  • 第一項
  • 第二項
  • 第三項
    • 內嵌項
    • 內嵌項
  • 第四項

以數字開始無序列表項 #

如果您需要以數字後跟句點開始無序列表項,則可以使用反斜杠 (\) 轉義句點。

Markdown HTML 渲染結果
- 1987年\. 最好的一年!
- 我認為1988年是第二好的一年。
<ul>
  <li>1987年.最好的一年!</li>
  <li>我認為1988年是第二好的一年。</li>
</ul>
  • 1968年。最好的一年!
  • 我認為1969年是第二好的一年。

無序列表最佳實踐 #

Markdown 應用程序對於如何處理同一列表中的不同分隔符意見不一。為了兼容性,請勿在同一列表中混合使用分隔符。

✅  推薦 ❌  不推薦
- 第一項
- 第二項
- 第三項
- 第四項
+ 第一項
* 第二項
- 第三項
+ 第四項

代碼 #

要將文本表示為代碼,請將其括在反引號 (`) 中。

Markdown HTML 渲染結果
在命令提示符下,輸入`nano`。 在命令提示符下,輸入 <code>nano</code>. 在命令提示符下,輸入 nano.

轉義反引號 #

如果您想要表示為代碼的單詞或短語包含一個或多個反引號,則可以通過將單詞或短語括在雙反引號(``)中來轉義它。

Markdown HTML 渲染結果
``在你的 Markdown 文件中使用`code`。 `` <code>在你的 Markdown 文件中使用`code`。</code> 在你的 Markdown 文件中使用`code`。

代碼塊 #

要創建代碼塊,請將塊的每一行縮進至少四個空格或一個制表符。

    <html>
      <head>
      </head>
    </html>

渲染結果如下所示:

<html>
  <head>
  </head>
</html>
註意:要創建不帶縮進行的代碼塊,請使用 圍欄代碼塊

水平線 #

要創建水平線,請在一行中使用三個更多星號 (***)、破折號 (---) 或下劃線 (___)。

***

---

_________________

三者的渲染輸出看起來相同:


水平線最佳實踐 #

為了兼容性,請在水平線前後放置空行。

✅  推薦 ❌  不推薦
他大舅他二舅都是他舅。

---

高桌子低板凳都是木頭。
他大舅他二舅都是他舅。
---
高桌子低板凳都是木頭。

鏈接 #

要創建鏈接,請將鏈接文本括在括號中(例如,[UNIXETC]),然後在其後緊接著用括號括上 URL(例如,(https://unixetc.com/))。

[UNIXETC](https://unixetc.com/)是一個有趣的網站。

渲染結果如下所示:

UNIXETC是一個有趣的網站。

註意:要鏈接到同一頁面上的元素,請參閱 鏈接到標題ID。要創建在新選項卡或窗口中打開的鏈接,請參閱 鏈接目標部分。

添加標題 #

您可以選擇為鏈接添加標題。當用戶將鼠標懸停在鏈接上時,這將作為工具提示出現。要添加標題,請在 URL 後用引號將其括起來。

[UNIXETC](https://unixetc.com/ "UNIX Publication")是一個有趣的網站。

渲染結果如下所示:

UNIXETC是一個有趣的網站。

URL和電子郵件地址 #

要快速將 URL 或電子郵件地址轉換為鏈接,請將其括在尖括號中。

<https://unixetc.com/>
<[email protected]>

渲染結果如下所示:

https://unixetc.com/ [email protected]

格式化鏈接 #

強調鏈接,請在括號和圓括號前後添加星號。要將鏈接表示為 代碼,請在括號中添加反引號。

**[UNIXETC](https://unixetc.com/)**是一個有趣的網站。
本站的連接在這裏 *[Markdown](https://markdown.hk)*.
參見[`代碼`](../basic-syntax#代碼)部分。

渲染結果如下所示:

UNIXETC 是一個有趣的網站。

本站的連接在這裏 Markdown.

參見 代碼部分。

引用樣式鏈接 #

引用樣式鏈接是一種特殊的鏈接,它使 URL 在 Markdown 中更易於顯示和閱讀。引用樣式鏈接由兩部分組成:與文本保持內聯的部分和存儲在文件其他位置以保持文本易於閱讀的部分。

引用樣式鏈接的第一部分 #

引用樣式鏈接的第一部分使用兩組括號進行格式化。第一組括號包圍應顯示為鏈接的文本。第二組括號顯示用於指向您存儲在文檔其他位置的鏈接的標簽。

雖然不是必需的,但您可以在第一組和第二組括號之間添加一個空格。第二組括號中的標簽不區分大小寫,可以包含字母、數字、空格或標點符號。

以下示例格式的第一部分表示的是一個意思:

  • [UNIXETC][1]
  • [UNIXETC] [1]

引用樣式鏈接第二部分 #

引用樣式鏈接的第二部分使用以下屬性進行格式化:

  1. 標簽,用括號括起來,後面緊跟著冒號和至少一個空格,例如,[label]:
  2. 鏈接的 URL,您可以選擇將其括在尖括號中。
  3. 鏈接的可選標題,您可以將其括在雙引號、單引號或圓括號中。

以下示例格式的第二部分表示的是一個意思:

  • [1]: https://unixetc.com
  • [1]: https://unixetc.com "UNIX Publication"
  • [1]: https://unixetc.com 'UNIX Publication'
  • [1]: https://unixetc.com (UNIX Publication)
  • [1]: <https://unixetc.com> "UNIX Publication"
  • [1]: <https://unixetc.com> 'UNIX Publication'
  • [1]: <https://unixetc.com> (UNIX Publication)

您可以將鏈接的第二部分放在 Markdown 文檔的任何位置。有些人會將其放在出現該鏈接的段落之後,而其他人則將其放在文檔末尾(如尾註或腳註)。

將各部分組合在一起的示例 #

假設您將 URL 作為 標準URL鏈接添加到段落中,它在 Markdown 中如下所示:

呦呦鹿鳴,食野之蘋。我有嘉賓,鼓瑟吹笙。

呦呦鹿鳴,食野之蒿。我有嘉賓,德音孔昭。

呦呦鹿鳴,食野之芩。我有嘉賓,鼓瑟鼓琴。

以上節選自[詩經·小雅·鹿鳴之什](https://shisanjing.cn/docs/shi-jing/xiao-ya/lu-ming-zhi-shi/lu-ming/)

雖然它可能指向有趣的附加信息,但顯示的 URL 除了使文本更難閱讀之外,實際上並沒有給現有的原始文本增加太多內容。要解決這個問題,你可以像這樣格式化 URL:

呦呦鹿鳴,食野之蘋。我有嘉賓,鼓瑟吹笙。

呦呦鹿鳴,食野之蒿。我有嘉賓,德音孔昭。

呦呦鹿鳴,食野之芩。我有嘉賓,鼓瑟鼓琴。

以上節選自[詩經·小雅·鹿鳴之什][1]

[1]: <https://shisanjing.cn/docs/shi-jing/xiao-ya/lu-ming-zhi-shi/lu-ming/> "詩經·小雅·鹿鳴之什"

在上述兩種情況下,渲染的結果將是相同的:

呦呦鹿鳴,食野之蘋。我有嘉賓,鼓瑟吹笙。

呦呦鹿鳴,食野之蒿。我有嘉賓,德音孔昭。

呦呦鹿鳴,食野之芩。我有嘉賓,鼓瑟鼓琴。

以上節選自詩經·小雅·鹿鳴之什

該鏈接的 HTML 內容為:

<a href="https://shisanjing.cn/docs/shi-jing/xiao-ya/lu-ming-zhi-shi/lu-ming/" title="詩經·小雅·鹿鳴之什">詩經·小雅·鹿鳴之什</a>

鏈接最佳實踐 #

Markdown 應用程序對如何處理 URL 中間的空格意見不一。為了兼容性,請嘗試使用 %20 對任何空格進行 URL 編碼。或者,如果您的 Markdown 應用程序支持 HTML,則可以使用 a HTML標簽。

✅  推薦 ❌  不推薦
[link](https://unixetc.com/one%20by%20one)

<a href="https://unixetc.com/one by one">link</a>

[link](https://unixetc.com/one by one)

URL 中間的括號也可能存在問題。為了保證兼容性,請嘗試使用 %28 對左括號 (() 進行 URL 編碼,使用 %29 對右括號 ()) 進行 URL 編碼。或者,如果您的 Markdown 應用程序支持 HTML,則可以使用 a HTML 標簽。

✅  推薦 ❌  不推薦
[詩經·小雅·鹿鳴之什](https://shisanjing.cn/%28lu-ming-zhi-shi%29

<a href="https://shisanjing.cn/(lu-ming-zhi-shi)">詩經·小雅·鹿鳴之什</a>

[詩經·小雅·鹿鳴之什](https://shisanjing.cn/(lu-ming-zhi-shi))

圖片 #

要添加圖片,請添加感嘆號 (!),後跟括號中的替代文本,以及括號中的圖片資源的路徑或 URL。您可以選擇在路徑或 URL 後添加圖片標題

![Tux Logo](/images/tux.png "Tux Logo")

渲染結果如下所示:

Tux Logo

註意:要調整圖像大小,請參閱 圖像大小部分。要添加標題,請參閱 圖像標題部分。

鏈接圖片 #

要添加圖像鏈接,請將圖像的 Markdown 括在括號中,然後在括號中添加鏈接。

[![Tux Logo](/images/tux.png "Tux Logo")](https://unix.pub)

渲染結果如下所示:

Tux Logo

轉義字符 #

要顯示原本用於格式化 Markdown 文檔中的文本的文字字符,請在該字符前添加反斜杠 (\)。

\* 如果沒有反斜杠,這將是無序列表中的項目符號。

渲染結果如下所示:

* 如果沒有反斜杠,這將是無序列表中的項目符號。

可用的轉義字符 #

您可以使用反斜杠來轉義以下字符。

字符 名稱
\ 反斜杠
` 反引號,另見 轉義反引號
* 星號
_ 下劃線
{ } 花括號
[ ] 方括號
< > 尖括號
( ) 圓括號
# 英鎊符號
+ 加號
- 減號(連字符)
.
! 感嘆號
| 管道,另請參見表中的轉義管道

HTML #

許多 Markdown 應用程序允許您在 Markdown 格式的文本中使用 HTML 標簽。如果您更喜歡某些 HTML 標簽而不是 Markdown 語法,這將非常有用。例如,有些人發現對圖像使用 HTML 標簽更容易。當您需要更改元素的屬性(例如指定 文本的顏色或更改圖像的寬度)時,使用 HTML 也很有用。

要使用 HTML,請將標簽放在 Markdown 格式文件的文本中。

這是**粗體字**,這是<em>斜體字</em>。

渲染結果如下所示:

這是粗體字,這是斜體字

HTML 最佳實踐 #

出於安全原因,並非所有 Markdown 應用程序都支持 Markdown 文檔中的 HTML。如有疑問,請檢查 Markdown 應用程序的文檔。某些應用程序僅支持部分 HTML 標簽。

使用空行將塊級 HTML 元素(如 <div><table><pre><p>)與周圍內容分開。盡量不要使用制表符或空格縮進標簽 - 這可能會幹擾格式。

您不能在塊級 HTML 標簽內使用 Markdown 語法。例如,<p>italic**bold**</p> 不起作用。