总览

几乎所有 Markdown 应用程序都支持 John Gruber 原始设计文档中列出的 Markdown 基本语法。但是，Markdown 处理程序之间存在着细微的变化和差异，我们都会尽可能标记出来。

标题（Headings）

要创建标题，请在单词或短语前面添加井号 (#) 。井号的数量代表了标题的级别。例如，添加三个井号即创建一个三级标题 (<h3>) (例如：### My Header)。

Markdown HTML 渲染效果
# Heading level 1 <h1>Heading level 1</h1> # Heading level 1
## Heading level 2 <h2>Heading level 2</h2> ## Heading level 2
### Heading level 3 <h3>Heading level 3</h3> ### Heading level 3
#### Heading level 4 <h4>Heading level 4</h4> #### Heading level 4
##### Heading level 5 <h5>Heading level 5</h5> ##### Heading level 5
###### Heading level 6 <h6>Heading level 6</h6> ###### Heading level 6

标题（Heading）用法的最佳实践

当井号（#）和标题文本之间没有空格时，各 Markdown 应用程序的处理方式是不一样的。为了兼容考虑，请在井号和标题文本之间添加一个空格。

✔&nbsp;这样做 ❌&nbsp;不要这样做
# Here’s a Heading #Here’s a Heading

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

✅  Do this ❌  Don’t do this
Try to put a blank line before...<br><br># Heading<br><br>...and after a heading. Without blank lines, this might not look right.<br># Heading<br>Don't do this!

段落（Paragraphs）

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

Markdown HTML 渲染效果
I really like using Markdown.<br><br>I think I'll use it to format all of my documents from now on. <p>I really like using Markdown.</p><br><br><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.

段落（Paragraph）用法的最佳实践

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

✅  这样做 ❌  不要这样做
Don't put tabs or spaces in front of your paragraphs.<br><br>Keep lines left-aligned like this.<br><br> This can result in unexpected formatting problems.<br><br>  Don't add tabs or spaces in front of paragraphs.

换行（Line Breaks）

在一行的末尾添加两个或多个空格，然后按回车键（return），即可创建一个换行（line break）或新行 (<br>)。

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

换行（Line Break）用法的最佳实践

几乎每个 Markdown 应用程序都支持两个或多个空格进行换行 (称为 “结尾空格（trailing whitespace）”) 的方式，但这是有争议的，因为很难在编辑器中直接看到空格，并且很多人在每个句子后面都会有意或无意地添加两个空格。由于这个原因，你可能需要使用除结尾空格以外的其它方式来进行换行。如果你所使用的 Markdown 应用程序 支持 HTML 的话，你可以使用 HTML 的 <br> 标签来实现换行。

为了兼容性，请在行尾添加“结尾空格”或 HTML 的 <br> 标签来实现换行。

✅  这样做 ❌  不要这样做
First line with two spaces after.  <br>And the next line.<br><br>First line with the HTML tag after.<br><br>And the next line.<br><br> First line with a backslash after.\<br>And the next line.<br><br>First line with nothing after.<br>And the next line.<br>

强调（Emphasis）

通过将文本设置为粗体或斜体来强调其重要性。

粗体（Bold）

要加粗文本，请在单词或短语的前后各添加两个星号（asterisks）或下划线（underscores）。如需加粗一个单词或短语的中间部分用以表示强调的话，请在要加粗部分的两侧各添加两个星号（asterisks）。

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

粗体（Bold）用法最佳实践

Markdown 应用程序在如何处理单词或短语中间的下划线上并不一致。为兼容考虑，在单词或短语中间部分加粗的话，请使用星号（asterisks）。

✅  这样做 ❌  不要这样做
Love**is**bold Love__is__bold

斜体（Italic）

要用斜体显示文本，请在单词或短语前后添加一个星号（asterisk）或下划线（underscore）。要斜体突出单词的中间部分，请在字母前后各添加一个星号，中间不要带空格。

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

斜体（Italic）用法的最佳实践

Markdown 的众多应用程序在如何处理单词中间的下划线上意见不一致。为了兼容起见，请用星号标注单词中间的斜体来表示着重。

✅  这样做 ❌  不要这样做
A*cat*meow A_cat_meow

粗体（Bold）和斜体（Italic）

要同时用粗体和斜体突出显示文本，请在单词或短语的前后各添加三个星号或下划线。要加粗并用斜体显示单词或短语的中间部分，请在要突出显示的部分前后各添加三个星号，中间不要带空格。

Markdown HTML 渲染效果
This text is ***really important***. This text is <strong><em>really important</em></strong>. This text is really important.
This text is ___really important___. This text is <strong><em>really important</em></strong>. This text is really important.
This text is __*really important*__. This text is <strong><em>really important</em></strong>. This text is really important.
This text is **_really important_**. This text is <strong><em>really important</em></strong>. This text is really important.
This is really***very***important text. This is really<strong><em>very</em></strong>important text. This is reallyveryimportant text.

粗体（Bold）和斜体（Italic）用法的最佳实践

Markdown 应用程序在处理单词或短语中间添加的下划线上并不一致。为了实现兼容性，请使用星号将单词或短语的中间部分加粗并以斜体显示，以示重要。

✅  这样做 ❌  不要这样做
This is really***very***important text. This is really___very___important text.

块引用（Blockquotes）

要创建块引用，请在段落前添加一个 > 符号。

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

渲染效果如下所示：

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

多个段落的块引用（Blockquotes）

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

1
2
3
> 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.

嵌套块引用（Nested Blockquotes）

1
2
3
> 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.

带有其它元素的块引用（Blockquotes with Other Elements）

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

1
2
3
4
5
6
> #### 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.

区块引号的最佳实践

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

✅  Do this ❌  Don’t do this
Try to put a blank line before...<br><br>> This is a blockquote<br><br>...and after a blockquote. Without blank lines, this might not look right.<br>> This is a blockquote<br>Don't do this!

列表（Lists）

你可以将多个条目组织成有序或无序列表。

有序列表（Ordered Lists）

要创建有序列表，请在每个列表项前添加数字并紧跟一个英文句点。数字不必按数学顺序排列，但是列表应当以数字 1 起始。

Markdown HTML Rendered Output
1. First item<br>2. Second item<br>3. Third item<br>4. Fourth item <ol><br>  <li>First item</li><br>  <li>Second item</li><br>  <li>Third item</li><br>  <li>Fourth item</li><br></ol> 1. First item
2. Second item
3. Third item
4. Fourth item
1. First item<br>1. Second item<br>1. Third item<br>1. Fourth item <ol><br>  <li>First item</li><br>  <li>Second item</li><br>  <li>Third item</li><br>  <li>Fourth item</li><br></ol> 1. First item
2. Second item
3. Third item
4. Fourth item
1. First item<br>8. Second item<br>3. Third item<br>5. Fourth item <ol><br>  <li>First item</li><br>  <li>Second item</li><br>  <li>Third item</li><br>  <li>Fourth item</li><br></ol> 1. First item
2. Second item
3. Third item
4. Fourth item
1. First item<br>2. Second item<br>3. Third item<br>    1. Indented item<br>    2. Indented item<br>4. Fourth item <ol><br>  <li>First item</li><br>  <li>Second item</li><br>  <li>Third item<br>    <ol><br>      <li>Indented item</li><br>      <li>Indented item</li><br>    </ol><br>  </li><br>  <li>Fourth item</li><br></ol> 1. First item
2. Second item
3. Third item
1. Indented item
2. Indented item
4. Fourth item

有序列表（Ordered List）用法的最佳实践

CommonMark 和其它几种轻量级标记语言可以让你使用括号（)）作为分隔符（例如 1) First item），但并非所有的 Markdown 应用程序都支持此种用法，因此，从兼容的角度来看，此用法不推荐。为了兼容起见，请只使用英文句点作为分隔符。

✅  这样做 ❌  不要这样做
1. First item<br>2. Second item 1) First item<br>2) Second item

无序列表（Unordered Lists）

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

Markdown HTML 渲染效果
- First item<br>- Second item<br>- Third item<br>- Fourth item <ul><br>  <li>First item</li><br>  <li>Second item</li><br>  <li>Third item</li><br>  <li>Fourth item</li><br></ul> - First item
- Second item
- Third item
- Fourth item
* First item<br>* Second item<br>* Third item<br>* Fourth item <ul><br>  <li>First item</li><br>  <li>Second item</li><br>  <li>Third item</li><br>  <li>Fourth item</li><br></ul> - First item
- Second item
- Third item
- Fourth item
+ First item<br>+ Second item<br>+ Third item<br>+ Fourth item <ul><br>  <li>First item</li><br>  <li>Second item</li><br>  <li>Third item</li><br>  <li>Fourth item</li><br></ul> - First item
- Second item
- Third item
- Fourth item
- First item<br>- Second item<br>- Third item<br>    - Indented item<br>    - Indented item<br>- Fourth item <ul><br>  <li>First item</li><br>  <li>Second item</li><br>  <li>Third item<br>    <ul><br>      <li>Indented item</li><br>      <li>Indented item</li><br>    </ul><br>  </li><br>  <li>Fourth item</li><br></ul> - First item
- Second item
- Third item
- Indented item
- Indented item
- Fourth item

以数字开头的无序列表

如果你需要以数字开头并且紧跟一个英文句号（也就是 .）的无序列表项，则可以使使用反斜线（\）来 转义 这个英文句号。

Markdown HTML Rendered Output
- 1968\. A great year!<br>- I think 1969 was second best. <ul><br>  <li>1968. A great year!</li><br>  <li>I think 1969 was second best.</li><br></ul> - 1968. A great year!
- I think 1969 was second best

链接（Links）

DuckDuckGo — 隐私保护，化繁为简。

网址和电子邮件地址

要将 URL 或电子邮件地址快速转换为链接，请将其括在尖括号中。

2279915703@qq.com

格式化链接

如需 强调（emphasize） 某个链接, 请在方括号前及圆括号后添加星号。要将链接表示为 代码（code） ，请在方括号内添加反引号。

百度

图片（Images）

要添加图片，首先请添加感叹号（!），然后紧跟着是方括号，方括号中可添加替代文本（alt text，即图片显示失败后显示此文本），最后跟着圆括号，圆括号中添加图片资源的路径或 URL。你可以选择在圆括号中的 URL 之后添加标题（即 title 属性）。

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

渲染效果如下：

The San Juan Mountains are beautiful!