基本语法

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

概述​

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

标题​

要创建标题，请在单词或短语前添加井号 (#)。井号的数量应与标题级别相对应。例如，要创建三级标题 (

)，请使用三个井号（例如，### 我的标题）。

MarkdownHTML呈现的输出# 一级标题

一级标题

二级标题

三级标题

四级标题

五级标题

六级标题

备用语法​

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

MarkdownHTML呈现的输出一级标题===============

一级标题

二级标题

标题最佳实践​

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

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

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

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

段落​

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

MarkdownHTML呈现的输出我真的很喜欢使用Markdown。我想从现在开始使用它来格式化我所有的文档。

我真的很喜欢使用Markdown。

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

段落最佳实践​

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

注意注意：如果您需要在输出中缩进段落，请参阅有关如何 缩进（制表符） 的部分。

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

换行​

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

MarkdownHTML呈现的输出这是第一行。这是第二行。

这是第一行。
这是第二行。

换行最佳实践​

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

为了兼容，请在行尾使用尾随空格或
HTML 标记。

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

✅ 执行此操作❌ 不要执行此操作后跟两个空格的第一行。 以及下一行。 后跟 HTML 标签的第一行。
以及下一行。后跟反斜杠的第一行。\以及下一行。 后跟空内容的第一行。 以及下一行。

强调​

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

加粗​

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

MarkdownHTML呈现的输出我非常喜欢 **加粗文本**。我非常喜欢 加粗文本。我非常喜欢 加粗文本。我非常喜欢 __加粗文本__。我非常喜欢 加粗文本。我非常喜欢 加粗文本。Love**is**boldLoveisboldLoveisbold

加粗最佳实践​

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

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

斜体​

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

MarkdownHTML呈现的输出斜体文本是 *cat's meow*。斜体文本是 cat's meow。斜体文本是 cat's meow。斜体文本是 _cat's meow_。斜体文本是 cat's meow。斜体文本是 cat's meow。A*cat*meowAcatmeowAcatmeow

斜体最佳实践​

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

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

加粗和斜体​

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

MarkdownHTML呈现的输出此文本 ***非常重要***。此文本是 非常重要。此文本 非常重要。此文本是 ___非常重要___。此文本是 非常重要。此文本是 非常重要。此文本是 __*非常重要*__。此文本是 非常重要。此文本是 非常重要。此文本是 **_非常重要_**。此文本是 非常重要。此文本是 非常重要。这是非常***非常***重要的文本。这是非常非常重要的文本。这是非常非常重要的文本。

注意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. 第四项

1. 第一项
2. 第二项
3. 第三项
4. 第四项

第一个项目

第二个项目

第三项

第四项

1. 第一个项目2. 第二个项目3. 第三项4. 第四项

1. 第一项
2. 第二项
3. 第三项
4. 第四项

第一个项目

第二个项目

第三项

第四项

1. 第一个项目2. 第二个项目3. 第三项4. 第四项

1. 第一项
2. 第二项
3. 第三项
4. 第四项

第一个项目

第二个项目

第三项

第四项

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

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

第一个项目

第二个项目

第三项

缩进项

缩进项

第四项

有序列表最佳实践​

CommonMark 和其他一些轻量级标记语言允许您使用括号 ) 作为分隔符例如，1) 第一项） ，但并非所有 Markdown 应用程序都支持此功能，因此从兼容性的角度来看，这不是一个好的选择。为了兼容性，仅使用句号。

✅ 执行此操作❌ 不要执行此操作1. 第一个项目2. 第二个项目3) 第一项4) 第二项

无序列表​

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

MarkdownHTML呈现的输出- 第一项- 第二项- 第三项- 第四项

• 第一项
• 第二项
• 第三项
• 第四项

第一项

第二项

第三项

第四项

* 第一项* 第二项* 第三项* 第四项

• 第一项
• 第二项
• 第三项
• 第四项

第一项

第二项

第三项

第四项

+ 第一项+ 第二项+ 第三项+ 第四项

• 第一项
• 第二项
• 第三项
• 第四项

第一项

第二项

第三项

第四项

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

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

第一项

第二项

第三项

缩进项

缩进项

第四项

用数字开始无序列表项​

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

MarkdownHTML呈现的输出- 1968\. 伟大的一年！- 我认为 1969 年是第二好的。

• 1968. 伟大的一年！
• 我认为 1969 年是第二好的。

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: 3. Update the title to match the name of your website.

呈现的输出如下所示

打开文件。

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

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

图像​

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

呈现的输出如下所示

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

惊叹于它的美丽。

关闭文件。

列表​

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

1. First item2. Second item3. Third item - Indented item - Indented item4. Fourth item

呈现的输出如下所示

第一项

第二项

第三项

缩进项

缩进项

第四项

代码​

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

MarkdownHTML呈现的输出在命令提示符下，键入 `nano`。在命令提示符下，键入 nano。在命令提示符下，键入 nano。

转义反引号​

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

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

代码块​

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

呈现的输出如下所示

注意要创建不缩进行的代码块，请使用 围栏代码块。

水平线​

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

***---_________________

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

水平线最佳实践​

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

✅ 执行此操作❌ 不要执行此操作尝试在...前放置空行 --- ...以及在水平线之后。尝试在...前放置空行 --- ...以及在水平线之后。

链接​

要创建链接，请用方括号括住链接文本，例如，[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](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 中更易于显示和阅读。引用式链接由两部分构成：一部分与文本保持一致，另一部分存储在文件中的其他位置，以保持文本易于阅读。

格式化链接的第一部分​

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

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

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

hobbit-hole

[霍比特人洞穴] 1

格式化链接的第二部分​

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

标签，用方括号括起来，紧跟一个冒号和至少一个空格（例如，[label]: ）。

链接的 URL，您可以选择用尖括号括起来。

链接的可选标题，您可以用双引号、单引号或括号括起来。

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

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

将各部分放在一起的示例​

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

In a hole in the ground there lived a hobbit. Not a nasty, dirty, wet hole, filled with the endsof worms and an oozy smell, nor yet a dry, bare, sandy hole with nothing in it to sit down on or toeat: 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 endsof worms and an oozy smell, nor yet a dry, bare, sandy hole with nothing in it to sit down on or toeat: it was a [hobbit-hole][1], and that means comfort.[1]: "Hobbit lifestyles"

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

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

链接的 HTML 代码为

hobbit-hole

链接最佳实践​

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

✅ 执行此操作❌ 不要执行此操作[link](https://www.example.com/my%20great%20page) link[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) 小说[小说](https://en.wikipedia.org/wiki/The_Milagro_Beanfield_War_(novel))

图像​

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


呈现的输出如下所示

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

链接图片​

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

[](https://mdg.imgix.net/assets/images/shiprock.jpg)

呈现的输出如下所示

转义字符​

要显示一个文本字符，该字符原本用于格式化 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 word is italic.

呈现的输出如下所示

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

HTML 最佳实践​

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

使用空行来分隔块级 HTML 元素，如

 和 
，使其与周围内容分开。尽量不要使用制表符或空格缩进标签，因为这会影响格式。
您不能在块级 HTML 标签中使用 Markdown 语法。例如，
italic and **bold**
 将不起作用。


							
						
						

							
诸葛亮与姜维北伐，多次进攻的上邽在哪里？