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.
`Loveisbold`	`Love<strong>is</strong>bold`	Loveisbold

加粗最佳实践 #

Markdown 应用程序对如何处理单词中间的下划线意见不一。为了兼容性，请尽量使用星号(**)加粗文本。

✅ 推荐	❌ 不推荐
`Loveisbold`	`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.
`Acatmeow`	`A<em>cat</em>meow`	Acatmeow

斜体最佳实践 #

Markdown 应用程序对如何处理单词中间的下划线意见不一。为了兼容性，请尽量使用星号(*)加粗文本。

✅ 推挤	❌ 不推荐
`Acatmeow`	`A_cat_meow`

段落 #

要创建段落，请使用空行分隔一行或多行文本。

Markdown HTML 渲染结果

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.


          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 处理器，em 和 strong 标签的顺序可能会颠倒。

粗体和斜体最佳实践 #

Markdown 应用程序对如何处理单词中间的下划线意见不一。为了兼容性，尽量使用星号*将单词中间加粗和斜体以强调。

✅ 推荐	❌ 不推荐
`高*桌子*低板凳都是木头。`	`高___桌子___低板凳都是木头。`

区块引用 #

要创建区块引用，请在段落前面添加 >。

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

渲染结果如下所示：

高桌子低板凳都是木头。

包含多个段落的区块引用 #

区块引用可以包含多个段落。在段落之间的空白行上添加 >。

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

渲染结果如下所示：

他大舅他二舅都是他舅。

高桌子低板凳都是木头。

嵌套的区块引用 #

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

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

渲染结果如下所示：

他大舅他二舅都是他舅。

高桌子低板凳都是木头。

带有其他元素的区块引用 #

区块引用可以包含其他 Markdown 格式的元素。但并非所有元素都可以使用，您需要进行实验才能知道哪些元素有效。

> #### 一些方言俗语
>
> - 他大舅他二舅都是他舅。
> - 高桌子低板凳都是木头。
>
>  *走一步*退一步全当**没走**。

渲染结果如下所示：

一些方言俗语 #

他大舅他二舅都是他舅。

高桌子低板凳都是木头。

走一步退一步全当没走。

块引用最佳实践 #

为了兼容性，请在块引用前后放置空行。

✅ 推荐	❌ 不推荐
`他大舅他二舅都是他舅。 > 高桌子低板凳都是木头。走一步退一步全当没走。`	`他大舅他二舅都是他舅。 > 高桌子低板凳都是木头。走一步退一步全当没走。`

列表 #

您可以将项目组织成有序和无序列表。

在列表中添加元素 #

要在列表中添加另一个元素同时保持列表的连续性，请将元素缩进四个空格或一个制表符，如以下示例所示。

提示：如果结果与预期不符，请仔细检查列表中的元素是否缩进四个空格或一个制表符。

内嵌段落 #

* 这是第一个列表项。
* 这是第二个列表项。

	在第二列表项下方添加另一个段落。

* 这是第三个列表项。

渲染结果如下所示：

这是第一个列表项。
这是第二个列表项。

在第二列表项下方添加另一个段落。
这是第三个列表项。

内嵌引用块 #

* 这是第一个列表项。
* 这是第二个列表项。

	> 引用块放在第二个列表项下面会很好看。

* 这是第三个列表项。

渲染结果如下所示：

这是第一个列表项。
这是第二个列表项。

引用块放在第二个列表项下面会很好看。
这是第三个列表项。

内嵌代码块 #

代码块通常缩进四个空格或一个制表符。当它们在列表中时，缩进八个空格或两个制表符。

1. 打开文件
2. 在第21行找到如下代码块:

        <html>
          <head>
            <title>测试</title>
          </head>

3. 更新标题以与您的网站名称匹配。

渲染结果如下所示：

打开文件

在第21行找到如下代码块:

 <html>
   <head>
     <title>测试</title>
   </head>

更新标题以与您的网站名称匹配。

内嵌图片 #

1. 打开包含 Linux 吉祥物的文件。
2. 他看起来真不错。

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

3. 关闭文件。

渲染结果如下所示：

打开包含 Linux 吉祥物的文件。
他看起来真不错。

Tux，Linux 吉祥物

关闭文件。

内嵌列表 #

您可以将无序列表嵌套在有序列表中，反之亦然。

1. 第一项
2. 第二项
3. 第三项
	- 缩进项
	- 缩进项
4. 第四项

渲染结果如下所示：

第一项
第二项
第三项
- 缩进项
- 缩进项
第四项

有序列表 #

要创建有序列表，请添加带有数字和句点的行项目。数字不必按数字顺序排列，但列表应从数字 1 开始。

Markdown	HTML	渲染结果
`1. 第一项 2. 第二项 3. 第三项 4. 第四项`	`<ol> <li>第一项</li> <li>第二项</li> <li>第三项</li> <li>第四项</li> </ol>`	第一项第二项第三项第四项
`1. 第一项 1. 第二项 1. 第三项 1. 第四项`	`<ol> <li>第一项</li> <li>第二项</li> <li>第三项</li> <li>第四项</li> </ol>`	第一项第二项第三项第四项
`1. 第一项 8. 第二项 3. 第三项 5. 第四项`	`<ol> <li>第一项</li> <li>第二项</li> <li>第三项</li> <li>第四项</li> </ol>`	第一项第二项第三项第四项
`1. 第一项 2. 第二项 3. 第三项 1. 缩进项 2. 缩进项 4. 第四项`	`<ol> <li>第一项</li> <li>第二项</li> <li>第三项 <ol> <li>缩进项</li> <li>缩进项</li> </ol> </li> <li>第四项</li> </ol>`	第一项第二项第三项缩进项缩进项第四项

有序列表最佳实践 #

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]

引用样式链接第二部分 #

引用样式链接的第二部分使用以下属性进行格式化：

标签，用括号括起来，后面紧跟着冒号和至少一个空格，例如，[label]:。
链接的 URL，您可以选择将其括在尖括号中。
链接的可选标题，您可以将其括在双引号、单引号或圆括号中。

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

[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)

渲染结果如下所示：

转义字符 #

要显示原本用于格式化 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> 不起作用。

Markdown基本语法 #

概述 #

标题 #

标题级别 1

标题级别 2

标题级别 3

标题级别 4

标题级别 5

标题级别 6

替代语法 #

标题级别 1

标题级别 2

标题最佳实践 #

粗体 #

加粗最佳实践 #

斜体 #

斜体最佳实践 #

段落 #

段落最佳实践 #

换行符 #

换行最佳实践 #

强调 #

粗体和斜体 #

粗体和斜体最佳实践 #

区块引用 #

包含多个段落的区块引用 #

嵌套的区块引用 #

带有其他元素的区块引用 #

一些方言俗语 #

块引用最佳实践 #

列表 #

在列表中添加元素 #

内嵌段落 #

内嵌引用块 #

内嵌代码块 #

内嵌图片 #

内嵌列表 #

有序列表 #

有序列表最佳实践 #

无序列表 #

以数字开始无序列表项 #

无序列表最佳实践 #

代码 #

转义反引号 #

代码块 #

水平线 #

水平线最佳实践 #

链接 #

添加标题 #

URL和电子邮件地址 #

格式化链接 #

引用样式链接 #

引用样式链接的第一部分 #

引用样式链接第二部分 #

将各部分组合在一起的示例 #

链接最佳实践 #

图片 #

链接图片 #

转义字符 #

可用的转义字符 #

HTML #

HTML 最佳实践 #