概述

几乎所有 Markdown 应用程序都支持原始 Markdown 设计文档中概述的基本语法。Markdown 处理器之间存在细微的差异和差异——尽可能内联。

标题

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

替代语法

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

标题的最佳实践

Markdown 应用程序如何处理井号(#)和标题名称之间的缺失空格上没有统一标准。为了兼容性，请始终在数字符号和标题名称之间放置一个空格。

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

段落

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

段落的最佳实践

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

换行

要换行或创建换行符 (<br>), 请以两个或多个空格结束一行，然后按回车键。

换行的最佳实践

你几乎可以在每个 Markdown 应用程序中使用两个或多个空格（通常称为“尾随空格”）作为换行符，但这是有争议的。在编辑器中很难看到尾随空格，而且许多人在每个句子后不小心或有意地放置了两个空格。出于这个原因，你可能希望使用尾随空格以外的其他内容作为换行符。如果你的 Markdown 应用程序支持 HTML，你可以使用<br> HTML 标签。

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

这里有两个我不建议使用的选项。CommonMark 和其他一些轻量级标记语言允许你在行尾键入反斜杠(\)，但并非所有 Markdown 应用程序都支持这一点，因此从兼容性角度来看，这不是一个很好的选择。也有一些轻量级标记语言不需要在行尾添加任何内容——只需按回车键，它们就会创建一个换行符。

强调

你可以通过将文本设置为粗体或斜体来增加重点。

粗体

要加粗文本，请在单词或短语前后添加两个星号或下划线。为了强调单词的中间部分，请在字母周围添加两个不带空格的星号。

粗体的最佳实践

Markdown 应用程序在如何处理单词中间的下划线上没有统一标准。为了兼容性，使用星号在单词中间加粗以表示强调。

斜体

要使文本变为斜体，请在单词或短语前后添加一个星号或下划线。为了强调单词中间的斜体，请在字母周围添加一个不带空格的星号。

斜体的最佳实践

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.

带有多个段落的块引用

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

> 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.

嵌套块引用

块引用可以嵌套。在要嵌套的段落前面添加一个 >> 符号。

> 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**.

渲染输出如下所示：

The quarterly results look great!

• Revenue was off the chart.
• Profits were higher than ever.

Everything is going according to plan.

块引用的最佳实践

为了兼容性，请在引用块的前后留出空行。

列表

You can organize items into ordered and unordered lists.

有序列表

To create an ordered list, add line items with numbers followed by periods. The numbers don’t have to be in numerical order, but the list should start with the number one.

Ordered List Best Practices

CommonMark and a few other lightweight markup languages let you use a parenthesis ()) as a delimiter (e.g., 1) First item), but not all Markdown applications support this, so it isn’t a great option from a compatibility perspective. For compatibility, use periods only.

无序列表

To create an unordered list, add dashes (-), asterisks (*), or plus signs (+) in front of line items. Indent one or more items to create a nested list.

Starting Unordered List Items With Numbers

If you need to start an unordered list item with a number followed by a period, you can use a backslash (\) to escape the period.

Unordered List Best Practices

Markdown applications don’t agree on how to handle different delimiters in the same list. For compatibility, don’t mix and match delimiters in the same list — pick one and stick with it.

Adding Elements in Lists

To add another element in a list while preserving the continuity of the list, indent the element four spaces or one tab, as shown in the following examples.

Paragraphs

* 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.

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

• And here’s the third list item.

Blockquotes

* 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.

渲染输出看起来是这样的：

• 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.

Code Blocks

Code blocks are normally indented four spaces or one tab. When they’re in a list, indent them eight spaces or two tabs.

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. 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.

Images

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. Open the file containing the Linux mascot.

2. Marvel at its beauty.

   

3. Close the file.

Lists

You can nest an unordered list in an ordered list, or vice versa.

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

渲染输出看起来是这样的：

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

代码

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

转义反引号

如果你想表示为代码的单词或短语包含一个或多个反引号，可以通过使用双反引号（``）将其括起来来进行转义。

代码块

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

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

渲染输出看起来是这样的：

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

水平分隔线

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

***

---

_________________

所有三种方式的渲染输出效果相同：

水平线最佳实践

为了兼容性，请在水平线的前后留出空行。

链接

要创建一个链接，请将链接文本放在方括号中（例如，[Duck Duck Go]) ，然后紧接着用圆括号包含 URL（例如，(https://duckduckgo.com)）。

我最喜欢的搜索引擎是 [Duck Duck Go](https://duckduckgo.com).

渲染输出看起来是这样的：

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

添加标题

你可以选择为链接添加标题。这样，当用户将鼠标悬停在链接上时，会显示为工具提示。要添加标题，请在 URL 后用双引号括起来。

我最喜欢的搜索引擎是 [Duck Duck Go](https://duckduckgo.com "保护隐私的搜索引擎").

渲染输出看起来是这样的：

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

URL 和电子邮件地址

要快速将 URL 或电子邮件地址转换为链接，请用尖括号括起来。

<https://www.markdownguide.org>
<fake@example.com>

渲染输出看起来是这样的：

https://www.markdownguide.org
fake@example.com

格式化链接

要对链接进行 强调，在方括号和圆括号前后添加星号。要将链接标记为 代码，在方括号中添加反引号。

我喜欢支持 **[EFF](https://eff.org)**.
这是 *[Markdown 101](https://markdown101.github.io)*.<br/>
查看有关 [`代码`](#code).

渲染输出看起来是这样的：

我喜欢支持 EFF.
这是 Markdown 101.
查看有关 代码.

引用风格链接

引用风格链接是一种特殊类型的链接，使 URL 在 Markdown 中更易于显示和阅读。引用风格链接分为两部分：一部分嵌入到文本中，另一部分存储在文件的其他地方，以保持文本的可读性。

格式化链接的第一部分

引用风格链接的第一部分由两组方括号组成。第一组方括号包含要显示为链接的文本。第二组方括号显示一个标签，用于指向你在文档其他地方存储的链接。

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

这意味着以下示例格式在链接的第一部分是大致等效的：

• [霍比特人洞穴][1]
• [霍比特人洞穴] [1]

格式化链接的第二部分

引用风格链接的第二部分格式化具有以下属性：

1. 标签，使用方括号括起来，紧接着是冒号和至少一个空格（例如 [label]: ）。
2. 链接的 URL，你可以选择用尖括号括起来。
3. 链接的可选标题，你可以用双引号、单引号或圆括号括起来。

这意味着以下示例格式在链接的第二部分大致等效：

• [1]: https://en.wikipedia.org/wiki/Hobbit#Lifestyle
• [1]: https://en.wikipedia.org/wiki/Hobbit#Lifestyle "霍比特人的生活方式"
• [1]: https://en.wikipedia.org/wiki/Hobbit#Lifestyle '霍比特人的生活方式'
• [1]: https://en.wikipedia.org/wiki/Hobbit#Lifestyle (霍比特人的生活方式)
• [1]: <https://en.wikipedia.org/wiki/Hobbit#Lifestyle> "霍比特人的生活方式"
• [1]: <https://en.wikipedia.org/wiki/Hobbit#Lifestyle> '霍比特人的生活方式'
• [1]: <https://en.wikipedia.org/wiki/Hobbit#Lifestyle> (霍比特人的生活方式)

你可以将链接的第二部分放在 Markdown 文档中的任何位置。有些人将它们放在出现的段落之后，而其他人则将其放在文档的末尾（类似于尾注或脚注）。

将两部分组合在一起

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

在地面下的一个洞里住着一个霍比特人。
不是一个肮脏、潮湿的洞，充满了虫子的末端和恶心的气味，也不是一个干燥、光秃秃的沙土洞，里面没有可以坐下或吃东西的东西：这是一个 [霍比特人洞穴](https://en.wikipedia.org/wiki/Hobbit#Lifestyle "霍比特人的生活方式")，这意味着舒适。

虽然它可能指向有趣的附加信息，但显示的 URL 实际上并没有为现有的原始文本增加太多内容，反而使其更难阅读。为了解决这个问题，你可以将 URL 格式化成这样：

在地面下的一个洞里住着一个霍比特人。不是一个肮脏、潮湿的洞，充满了虫子的末端和恶心的气味，也不是一个干燥、光秃秃的沙土洞，里面没有可以坐下或吃东西的东西：这是一个 [霍比特人洞穴][1]，这意味着舒适。
[1]: <https://en.wikipedia.org/wiki/Hobbit#Lifestyle> "霍比特人的生活方式"

在上述两种情况中，渲染输出将是相同的：

在地面下的一个洞里住着一个霍比特人。不是一个肮脏、潮湿的洞，充满了虫子的末端和恶心的气味，也不是一个干燥、光秃秃的沙土洞，里面没有可以坐下或吃东西的东西：这是一个 霍比特人洞穴，这意味着舒适。

链接的 HTML 将是：

<a href="https://en.wikipedia.org/wiki/Hobbit#Lifestyle" title="霍比特人的生活方式">霍比特人洞穴</a>

链接最佳实践

Markdown 应用程序在处理 URL 中间的空格时并不一致。为了兼容性，尽量使用 %20 对空格进行 URL 编码。或者，如果你的 Markdown 应用程序 支持 HTML，你可以使用 a HTML 标签。

Images

要添加图片，请在 Markdown 文本中使用感叹号 (!)，后跟方括号中的替代文本，再加上圆括号中的图片路径或 URL。你可以选择性地在路径或 URL 后加上双引号中的标题。

![圣胡安山脉非常美丽！](/assets/images/san-juan-mountains.jpg "圣胡安山脉")

渲染输出看起来是这样的：

链接图片

要给图片添加链接，请将图片的 Markdown 语法放在方括号中，然后在圆括号中添加链接。

[![沙漠中的一块古老岩石](/assets/images/shiprock.jpg "新墨西哥州的船岩，摄影：Beau Rogers")](https://www.flickr.com/photos/beaurogers/31833779864/in/photolist-Qv3rFw-34mt9F-a9Cmfy-5Ha3Zi-9msKdv-o3hgjr-hWpUte-4WMsJ1-KUQ8N-deshUb-vssBD-6CQci6-8AFCiD-zsJWT-nNfsgB-dPDwZJ-bn9JGn-5HtSXY-6CUhAL-a4UTXB-ugPum-KUPSo-fBLNm-6CUmpy-4WMsc9-8a7D3T-83KJev-6CQ2bK-nNusHJ-a78rQH-nw3NvT-7aq2qf-8wwBso-3nNceh-ugSKP-4mh4kh-bbeeqH-a7biME-q3PtTf-brFpgb-cg38zw-bXMZc-nJPELD-f58Lmo-bXMYG-bz8AAi-bxNtNT-bXMYi-bXMY6-bXMYv)

渲染输出看起来是这样的：

Escaping Characters

要在 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 and **bold**</p> 是无效的。