Skip to main content

基本语法

原始设计文档中概述的 Markdown 元素。

概述

几乎所有 Markdown 应用程序都支持原始 Markdown 设计文档中概述的基本语法。Markdown 处理器之间存在细微的差异和出入,这些差异和出入在可能的情况下都会以内联方式注明。

标题

要创建标题,请在单词或短语前添加井号 (#)。井号的数量应与标题级别相对应。例如,要创建三级标题 (<h3>),请使用三个井号(例如,### 我的标题)。

MarkdownHTML呈现的输出
# 一级标题<h1>一级标题</h1>

一级标题

## 二级标题<h2>二级标题</h2>

二级标题

### 三级标题<h3>三级标题</h3>

三级标题

#### 四级标题<h4>四级标题</h4>

四级标题

##### 五级标题<h5>五级标题</h5>
五级标题
###### 六级标题<h6>六级标题</h6>
六级标题

备用语法

或者,在文本下方的行中,添加任意数量的 == 字符以表示一级标题,或 -- 字符以表示二级标题。

MarkdownHTML呈现的输出
一级标题
===============
<h1>一级标题</h1>

一级标题

二级标题
---------------
<h2>二级标题</h2>

二级标题

标题最佳实践

Markdown 应用程序对于如何处理井号 (#) 和标题名称之间的空格没有达成一致。为了兼容性,请始终在井号和标题名称之间添加一个空格。

执行此操作 不要执行此操作
# 这是一个标题#这是一个标题

为了兼容,您还应在标题前后放置空行。

执行此操作 不要执行此操作
尝试在...前放置空行
# 标题
...并在标题后放置空行。
如果没有空行,可能看起来不正确。
# 标题
不要这样做!

段落

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

MarkdownHTML呈现的输出
我真的很喜欢使用
Markdown。

我想从现在开始使用它来格式
化我所有的文档。
<p>我真的很喜欢使用
Markdown。</p>

<p>我想从现在开始使用它来格式
化我所有的文档。</p>
我真的很喜欢使用
Markdown。

我想从现在开始使用它来格式
化我所有的文档。

段落最佳实践

除非 段落位于列表中,否则不要使用空格或制表符缩进段落。

注意

注意:如果您需要在输出中缩进段落,请参阅有关如何 缩进(制表符) 的部分。

执行此操作 不要执行此操作
不要在段落前放置制表符或空格。
保持行左对齐,如下所示。
   这可能会导致意外的格式问题。
不要在段落前添加制表符或空格。

换行

要创建换行或新行 (<br>),请使用两个或更多空格结束一行,然后键入回车。

MarkdownHTML呈现的输出
这是第一行。
这是第二行。
<p>这是第一行。<br>
这是第二行。</p>
这是第一行。
这是第二行。

换行最佳实践

您可以在几乎每个 Markdown 应用程序中使用两个或更多空格(通常称为“尾随空格”)进行换行,但这存在争议。在编辑器中很难看到尾随空格,许多人会在每个句子后意外或故意放置两个空格。因此,您可能希望使用尾随空格以外的东西进行换行。如果您的 Markdown 应用程序 支持 HTML,则可以使用 <br> HTML 标记。

为了兼容,请在行尾使用尾随空格或 <br> HTML 标记。

还有两个我不推荐使用的选项。CommonMark 和其他一些轻量级标记语言允许你在行尾输入一个反斜杠 (),但并非所有 Markdown 应用程序都支持此功能,因此从兼容性的角度来看,这不是一个好选项。至少有几种轻量级标记语言不需要在行尾输入任何内容——只需按回车,它们就会创建一个换行符。

执行此操作 不要执行此操作
后跟两个空格的第一行。
以及下一行。

后跟 HTML 标签的第一行。<br>
以及下一行。
后跟反斜杠的第一行。\
以及下一行。

后跟空内容的第一行。
以及下一行。

强调

你可以通过加粗或斜体文本来添加强调。

加粗

要加粗文本,请在单词或短语前和后添加两个星号或下划线。要加粗单词中间的内容以示强调,请在字母周围添加两个星号,中间不要有空格。

MarkdownHTML呈现的输出
我非常喜欢 **加粗文本**。我非常喜欢 <strong>加粗文本</strong>。我非常喜欢 加粗文本
我非常喜欢 __加粗文本__。我非常喜欢 <strong>加粗文本</strong>。我非常喜欢 加粗文本
Love**is**boldLove<strong>is</strong>boldLoveisbold

加粗最佳实践

Markdown 应用程序对于如何处理单词中间的下划线没有达成一致意见。为了兼容性,请使用星号加粗单词中间的内容以示强调。

执行此操作 不要执行此操作
Love**is**boldLove__is__bold

斜体

要将文本斜体化,请在单词或短语前和后添加一个星号或下划线。要斜体化单词中间的内容以示强调,请在字母周围添加一个星号,中间不要有空格。

MarkdownHTML呈现的输出
斜体文本是 *cat's meow*。斜体文本是 <em>cat's meow</em>。斜体文本是 cat's meow
斜体文本是 _cat's meow_。斜体文本是 <em>cat's meow</em>。斜体文本是 cat's meow
A*cat*meowA<em>cat</em>meowAcatmeow

斜体最佳实践

Markdown 应用程序对于如何处理单词中间的下划线没有达成一致意见。为了兼容性,请使用星号斜体化单词中间的内容以示强调。

执行此操作 不要执行此操作
A*cat*meowA_cat_meow

加粗和斜体

要同时使用加粗和斜体来强调文本,请在单词或短语前和后添加三个星号或下划线。要加粗和斜体化单词中间的内容以示强调,请在字母周围添加三个星号,中间不要有空格。

MarkdownHTML呈现的输出
此文本 ***非常重要***。此文本是 <em><strong>非常重要</strong></em>。此文本 非常重要
此文本是 ___非常重要___。此文本是 <em><strong>非常重要</strong></em>。此文本是 非常重要
此文本是 __*非常重要*__。此文本是 <em><strong>非常重要</strong></em>。此文本是 非常重要
此文本是 **_非常重要_**。此文本是 <em><strong>非常重要</strong></em>。此文本是 非常重要
这是非常***非常***重要的文本。这是非常<em><strong>非常</strong></em>重要的文本。这是非常非常重要的文本。
注意

em 和 strong 标签的顺序可能会根据你使用的 Markdown 处理器而颠倒。

粗体和斜体最佳实践

Markdown 应用程序对于如何处理单词中间的下划线没有达成一致。为了兼容性,请使用星号对单词中间加粗和斜体以示强调。

执行此操作 不要执行此操作
这是非常***非常***重要的文本。这是非常___非常___重要的文本。

引用块

要创建引用块,请在段落前添加 >

> Dorothy followed her through many of the beautiful rooms in her castle.

呈现的输出如下所示

多萝茜跟随她穿过城堡中许多美丽的房间。

包含多个段落的引用块

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

> Dorothy followed her through many of the beautiful rooms in her castle.
>
> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.

呈现的输出如下所示

多萝茜跟随她穿过城堡中许多美丽的房间。

女巫命令她清洗锅碗瓢盆,打扫地板,并用木头生火。

嵌套引用块

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

> Dorothy followed her through many of the beautiful rooms in her castle.
>
>> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.

呈现的输出如下所示

多萝茜跟随她穿过城堡中许多美丽的房间。

女巫命令她清洗锅碗瓢盆,打扫地板,并用木头生火。

包含其他元素的引用块

引用块可以包含其他 Markdown 格式的元素。并非所有元素都可以使用——你需要进行实验以查看哪些元素有效。

> #### The quarterly results look great!
>
> - Revenue was off the chart.
> - Profits were higher than ever.
>
> *Everything* is going according to **plan**.

呈现的输出如下所示

季度业绩看起来很棒!

  • 收入超出图表。
  • 利润比以往任何时候都高。

一切都按计划进行。

引用块最佳实践

为了兼容性,请在引用块前后添加空行。

执行此操作 不要执行此操作
尝试在...前放置空行

> 这是一个引用块

...并在引用块之后。
如果没有空行,可能看起来不正确。
> 这是一个引用块
不要这样做!

列表

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

有序列表

要创建有序列表,请添加带有数字和句号的行项目。数字不必按数字顺序排列,但列表应从数字一开头。

MarkdownHTML呈现的输出
1. 第一个项目
2. 第二个项目
3. 第三项
4. 第四项
<ol>
<li>第一项</li>
<li>第二项</li>
<li>第三项</li>
<li>第四项</li>
</ol>
  1. 第一个项目
  2. 第二个项目
  3. 第三项
  4. 第四项
1. 第一个项目
2. 第二个项目
3. 第三项
4. 第四项
<ol>
<li>第一项</li>
<li>第二项</li>
<li>第三项</li>
<li>第四项</li>
</ol>
  1. 第一个项目
  2. 第二个项目
  3. 第三项
  4. 第四项
1. 第一个项目
2. 第二个项目
3. 第三项
4. 第四项
<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. 第二个项目
3) 第一项
4) 第二项

无序列表

要创建无序列表,请在行项目前添加破折号 (-)、星号 (*) 或加号 (+)。缩进一个或多个项目以创建嵌套列表。

MarkdownHTML呈现的输出
- 第一项
- 第二项
- 第三项
- 第四项
<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>
  • 第一项
  • 第二项
  • 第三项
    • 缩进项
    • 缩进项
  • 第四项

用数字开始无序列表项

如果您需要用一个数字和一个句号开始一个无序列表项,您可以使用反斜杠 (\)转义 句号。

MarkdownHTML呈现的输出
- 1968\. 伟大的一年!
- 我认为 1969 年是第二好的。
<ul>
<li>1968. 伟大的一年!</li>
<li>我认为 1969 年是第二好的。</li>
</ul>
  • 1968. 伟大的一年!
  • 我认为 1969 年是第二好的。

无序列表最佳实践

Markdown 应用程序对于如何处理同一列表中的不同分隔符没有达成一致。为了兼容性,请不要在同一列表中混合和匹配分隔符——选择一个并坚持使用它。

执行此操作 不要执行此操作
- 第一项
- 第二项
- 第三项
- 第四项
+ 第一项
* 第二项
- 第三项
+ 第四项

在列表中添加元素

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

提示

如果事情没有按预期出现,请仔细检查你是否已将列表中的元素缩进了四个空格或一个制表符。

段落

* This is the first list item.
* Here's the second list item.

I need to add another paragraph below the second list item.

* And here's the third list item.

呈现的输出如下所示

  • 这是第一个列表项。

  • 这是第二个列表项。

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

  • 这是第三个列表项。

引用块

* This is the first list item.
* Here's the second list item.

> A blockquote would look great below the second list item.

* And here's the third list item.

呈现的输出如下所示

  • 这是第一个列表项。

  • 这是第二个列表项。

    在第二个列表项下方显示一个引用块会很棒。

  • 这是第三个列表项。

代码块

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

1. Open the file.
2. Find the following code block on line 21:

<html>
<head>
<title>Test</title>
</head>

3. Update the title to match the name of your website.

呈现的输出如下所示

  1. 打开文件。
  2. 在第 21 行找到以下代码块:
 <html>
<head>
<title>Test</title>
</head>
  1. 更新标题以匹配你网站的名称。

图像

1. Open the file containing the Linux mascot.
2. Marvel at its beauty.

![Tux, the Linux mascot](/assets/images/tux.png)

3. Close the file.

呈现的输出如下所示

  1. 打开包含 Linux 吉祥物的文件。

  2. 惊叹于它的美丽。

attachments\tutorial-basics

  1. 关闭文件。

列表

你可以在有序列表中嵌套无序列表,反之亦然。

1. First item
2. Second item
3. Third item
- Indented item
- Indented item
4. Fourth item

呈现的输出如下所示

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

代码

要表示一个单词或短语为代码,请用反引号 (`) 将其括起来。

MarkdownHTML呈现的输出
在命令提示符下,键入 `nano`。在命令提示符下,键入 <code>nano</code>。在命令提示符下,键入 nano

转义反引号

如果你要表示为代码的单词或短语包含一个或多个反引号,你可以通过用双反引号 (``) 将单词或短语括起来来转义它。

MarkdownHTML呈现的输出
``在你的 Markdown 文件中使用 `code`。``<code>在你的 Markdown 文件中使用 `code`。</code>在你的 Markdown 文件中使用 code

代码块

要创建代码块,请将块的每一行至少缩进四个空格或一个制表符。

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

呈现的输出如下所示

  <html>
<head>
</head>
</html>
注意

要创建不缩进行的代码块,请使用 围栏代码块

水平线

要创建水平线,请在单独的一行上使用三个或更多星号 (***)、破折号 (---) 或下划线 (___)。

***

---

_________________

所有三个的渲染输出看起来相同


水平线最佳实践

为了兼容性,在水平线前后添加空行。

执行此操作 不要执行此操作
尝试在...前放置空行

---

...以及在水平线之后。
尝试在...前放置空行
---
...以及在水平线之后。

要创建链接,请用方括号括住链接文本,例如,[Duck Duck Go],然后紧跟括号中的 URL,例如,(https://duckduckgo.com)

My favorite search engine is [Duck Duck Go](https://duckduckgo.com).

呈现的输出如下所示

我最喜欢的搜索引擎是 Duck Duck Go

注意

要链接到同一页面上的元素,请参阅 链接到标题 ID。要创建在新标签或窗口中打开的链接,请参阅 链接目标 部分。

添加标题

您可以选择为链接添加标题。当用户将鼠标悬停在链接上时,它将显示为工具提示。要添加标题,请在 URL 后用引号将其括起来。

My favorite search engine is [Duck Duck Go](https://duckduckgo.com "The best search engine for privacy").

呈现的输出如下所示

我最喜欢的搜索引擎是 Duck Duck Go

URL 和电子邮件地址

要快速将 URL 或电子邮件地址变成链接,请用尖括号将其括起来。

<http://markdownguide.cn>
<fake@example.com>

呈现的输出如下所示

http://markdownguide.cn

[fake@example.com](fake@example.com)

注意

Docusaurus 不支持使用尖括号快速将 URL 或电子邮件地址变成链接。

格式化链接

强调 链接,请在方括号和圆括号前后添加星号。要将链接表示为 代码,请在方括号中添加反引号。

I love supporting the **[EFF](https://eff.org)**.
This is the *[Markdown Guide](http://markdownguide.cn)*.
See the section on [`code`](#code).

呈现的输出如下所示

我非常支持 EFF

这是 Markdown 指南

请参阅 code 部分。

引用式链接

引用式链接是一种特殊的链接,它使 URL 在 Markdown 中更易于显示和阅读。引用式链接由两部分构成:一部分与文本保持一致,另一部分存储在文件中的其他位置,以保持文本易于阅读。

格式化链接的第一部分

引用式链接的第一部分使用两组方括号进行格式化。第一组方括号包围应显示为链接的文本。第二组方括号显示用于指向存储在文档其他位置的链接的标签。

虽然不是必需的,但您可以在第一组和第二组方括号之间添加空格。第二组方括号中的标签不区分大小写,并且可以包含字母、数字、空格或标点符号。

这意味着以下示例格式对于链接的第一部分大致相同

格式化链接的第二部分

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

  1. 标签,用方括号括起来,紧跟一个冒号和至少一个空格(例如,[label]: )。
  2. 链接的 URL,您可以选择用尖括号括起来。
  3. 链接的可选标题,您可以用双引号、单引号或括号括起来。

这意味着以下示例格式对于链接的第二部分来说大致相等

您可以将链接的第二部分放在 Markdown 文档中的任何位置。有些人将它们放在它们出现的段落之后,而另一些人将它们放在文档的末尾(如尾注或脚注)。

将各部分放在一起的示例

假设您将一个 URL 作为 标准 URL 链接 添加到一个段落,并且在 Markdown 中看起来像这样

In a hole in the ground there lived a hobbit. Not a nasty, dirty, wet hole, filled with the ends
of worms and an oozy smell, nor yet a dry, bare, sandy hole with nothing in it to sit down on or to
eat: it was a [hobbit-hole](https://en.wikipedia.org/wiki/Hobbit#Lifestyle "Hobbit lifestyles"), and that means comfort.

虽然它可能指向有趣的附加信息,但显示的 URL 除了使其更难阅读之外,实际上并没有给现有原始文本增加太多内容。要解决这个问题,您可以像这样格式化 URL

In a hole in the ground there lived a hobbit. Not a nasty, dirty, wet hole, filled with the ends
of worms and an oozy smell, nor yet a dry, bare, sandy hole with nothing in it to sit down on or to
eat: it was a [hobbit-hole][1], and that means comfort.

[1]: <https://en.wikipedia.org/wiki/Hobbit#Lifestyle> "Hobbit lifestyles"

在上面的两个实例中,呈现的输出将是相同的

有一个霍比特人住在洞穴里。不是一个肮脏、潮湿、令人厌恶的洞穴,里面布满了蠕虫的末端和恶臭,也不是一个干燥、光秃、沙质的洞穴,里面什么都没有,只能坐下来或吃东西:这是一个 霍比特人洞穴,这意味着舒适。

链接的 HTML 代码为

<a href="https://en.wikipedia.org/wiki/Hobbit#Lifestyle" title="Hobbit lifestyles">hobbit-hole</a>

链接最佳实践

Markdown 应用程序对于如何处理 URL 中间的空格没有达成一致。为了兼容性,请尝试使用 %20 对 URL 中的任何空格进行 URL 编码。或者,如果您的 Markdown 应用程序 支持 HTML,则可以使用 a HTML 标签。

执行此操作 不要执行此操作
[link](https://www.example.com/my%20great%20page)

<a href="https://www.example.com/my great page">link</a>
[link](https://www.example.com/my great page)

URL 中间的括号也可能带来问题。为了兼容性,尝试使用 %28 对左括号 (() 进行 URL 编码,使用 %29 对右括号 ()) 进行 URL 编码。或者,如果 Markdown 应用程序 支持 HTML,可以使用 a HTML 标签。

执行此操作 不要执行此操作
[小说](https://en.wikipedia.org/wiki/The_Milagro_Beanfield_War_%28novel%29)

<a href="https://en.wikipedia.org/wiki/The_Milagro_Beanfield_War_(novel)">小说</a>
[小说](https://en.wikipedia.org/wiki/The_Milagro_Beanfield_War_(novel))

图像

要添加图片,添加一个感叹号 (!),后跟方括号中的备用文本,以及括号中图片资源的路径或 URL。您可以在路径或 URL 后添加引号中的标题(可选)。

![The San Juan Mountains are beautiful!](/assets/images/san-juan-mountains.jpg "San Juan Mountains")

呈现的输出如下所示

The San Juan Mountains are beautiful!

注意

要调整图片大小,请参阅 图片大小 部分。要添加标题,请参阅 图片标题 部分。

链接图片

要向图片添加链接,请用方括号括住图片的 Markdown,然后在括号中添加链接。

[![An old rock in the desert](/attachments/tutorial-basics/shiprock.jpg)](https://mdg.imgix.net/assets/images/shiprock.jpg)

呈现的输出如下所示

An old rock in the desert

转义字符

要显示一个文本字符,该字符原本用于格式化 Markdown 文档中的文本,请在字符前面添加一个反斜杠 ()。

\* Without the backslash, this would be a bullet in an unordered list.

呈现的输出如下所示

* 如果没有反斜杠,这将是无序列表中的项目符号。

可以转义的字符

可以使用反斜杠转义以下字符。

字符名称
\反斜杠
```反引号(另请参阅 代码中的转义反引号
*星号
_下划线
{ }大括号
[ ]方括号
< >尖括号
( )圆括号
#井号
+加号
-减号(连字符)
.
!感叹号
|管道(另请参阅 表格中转义管道

HTML

许多 Markdown 应用程序允许你在 Markdown 格式文本中使用 HTML 标签。如果你更喜欢某些 HTML 标签而不是 Markdown 语法,这会很有帮助。例如,有些人觉得使用 HTML 标签来处理图片更简单。当你需要更改元素的属性(例如指定 文本颜色 或更改图片的宽度)时,使用 HTML 也会很有帮助。

要使用 HTML,请将标签放置在 Markdown 格式文件文本中。

This **word** is bold. This <em>word</em> is italic.

呈现的输出如下所示

这个 单词 是粗体。这个 单词 是斜体。

HTML 最佳实践

出于安全原因,并非所有 Markdown 应用程序都支持 Markdown 文档中的 HTML。如有疑问,请查看 Markdown 应用程序的文档。一些应用程序仅支持 HTML 标签的子集。

使用空行来分隔块级 HTML 元素,如 <div><table><pre><p>,使其与周围内容分开。尽量不要使用制表符或空格缩进标签,因为这会影响格式。

您不能在块级 HTML 标签中使用 Markdown 语法。例如,<p>italic and **bold**</p> 将不起作用。