Markdown 基本语法

Arthas2024-07-302025-03-03

个人学习笔记，参考资料来自：中文版；英文版。

1. 标题

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

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

1.1 可选语法

还可以在文本下方添加任意数量的==号来标识一级标题，或者--号来标识二级标题。

Markdown	HTML
`Heading level 1` `===============`	`<h1>Heading level 1</h1>`
`Heading level 2` `---------------`	`<h2>Heading level 2</h2>`

1.2 标题最佳实践

不同的Markdown应用程序处理#和标题之间的空格方式并不一致。为了兼容考虑，请用一个空格在#和标题之间进行分隔。

✅ Do this	❌ Don’t do this
`# Here's a Heading`	`#Here's a Heading`

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

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

2. 段落

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

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

2.1 段落最佳实践

不要用空格(spaces)或制表符(tabs)缩进段落。

✅ Do this	❌ Don’t do this
`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.`

3. 换行

在一行的末尾添加两个或多个空格，然后按回车键,即可创建一个换行(<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>`

3.1 换行最佳实践

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

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

还有两种其他方式不推荐使用。CommonMark和其它几种轻量级标记语言支持在行尾添加反斜杠(\)的方式实现换行，但是并非所有Markdown应用程序都支持此种方式，因此从兼容性的角度来看，不推荐使用。并且至少有两种轻量级标记语言支持无须在行尾添加任何内容，只须键入回车键(return)即可实现换行。

✅ Do this	❌ Don’t do this
`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.`

4. 强调

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

4.1 粗体

要加粗文本，请在单词或短语的前后各添加两个星号(**)或两个下划线(__)。如需加粗一个单词或短语的中间部分用以表示强调的话，请在要加粗部分的两侧各添加两个星号(**)，中间不要带空格。

Markdown	HTML
`I just love bold text.`	`I just love <strong>bold text</strong>.`
`I just love __bold text__.`	`I just love <strong>bold text</strong>.`
`Loveisbold`	`Love<strong>is</strong>bold`

4.2 粗体最佳实践

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

✅ Do this	❌ Don’t do this
`Loveisbold`	`Love__is__bold`

4.3 斜体

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

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 <em>cat's meow</em>.`
`Acatmeow`	`A<em>cat</em>meow`

4.4 斜体最佳实践

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

✅ Do this	❌ Don’t do this
`Acatmeow`	`A_cat_meow`

4.5 粗体和斜体

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

Markdown	HTML
`This text is *really important*.`	`This text is <strong><em>really important</em></strong>.`
`This text is ___really important___.`	`This text is <strong><em>really important</em></strong>.`
`This text is __really important__.`	`This text is <strong><em>really important</em></strong>.`
`This text is _really important_.`	`This text is <strong><em>really important</em></strong>.`
`This is really*very*important text.`	`This is really<strong><em>very</em></strong>important text.`

4.6 粗体和斜体最佳实践

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

✅ Do this	❌ Don’t do this
`This is really*very*important text.`	`This is really___very___important text.`

5. 引用

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

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

5.1 多个段落的块引用

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

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.

5.2 嵌套块引用

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

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.

5.3 带有其它元素的块引用

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

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

5.4 引用最佳实践

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

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

6. 列表

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

6.1 有序列表

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

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

6.2 有序列表最佳实践

CommonMark和其它几种轻量级标记语言允许您使用括号())作为分隔符(例如：1) First item)，但是并非所有Markdown应用程序都支持此种方式，因此从兼容性的角度来看，不推荐使用。为了兼容性，请仅使用(.)。

✅ Do this	❌ Don’t do this
`1. First item` `2. Second item`	`1) First item` `2) Second item`

6.3 无序列表

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

Markdown	HTML
`- First item` `- Second item` `- Third item` `- Fourth item`	`<ul>` `<li>First item</li>` `<li>Second item</li>` `<li>Third item</li>` `<li>Fourth item</li>` `</ul>`
`* First item` `* Second item` `* Third item` `* Fourth item`	`<ul>` `<li>First item</li>` `<li>Second item</li>` `<li>Third item</li>` `<li>Fourth item</li>` `</ul>`
`+ First item` `+ Second item` `+ Third item` `+ Fourth item`	`<ul>` `<li>First item</li>` `<li>Second item</li>` `<li>Third item</li>` `<li>Fourth item</li>` `</ul>`
`- First item` `- Second item` `- Third item` `- Indented item` `- Indented item` `- Fourth item`	`<ul>` `<li>First item</li>` `<li>Second item</li>` `<li>Third item` `<ul>` `<li>Indented item</li>` `<li>Indented item</li>` `</ul>` `</li>` `<li>Fourth item</li>` `</ul>`

6.3.1 以数字开始无序列表

如果需要以数字后跟句点的无序列表项开头，可以使用反斜杠(\)来转义句点。

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

6.4 无序列表最佳实践

Markdown应用程序无法处理同一列表中的不同分隔符。为了兼容性，不要在同一列表中混用分隔符，选择一个并坚持使用。

✅ Do this	❌ Don’t do this
`- First item` `- Second item` `- Third item` `- Fourth item`	`+ First item` `* Second item` `- Third item` `+ Fourth item`

6.5 在列表中嵌套其他元素

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

💡 提示： 如果内容未按预期方式显示，请仔细检查是否已将列表中的元素缩进四个空格或一个制表符。

6.5.1 段落

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

6.5.2 引用块

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

6.5.3 代码块

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

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.

6.5.4 图片

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.

6.5.5 列表

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

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

7. 代码

要将单词或短语表示为代码，请将其包裹在反引号(`)中。

Markdown	HTML
At the command prompt, type `nano`.	`At the command prompt, type <code>nano</code>.`

7.1 转义反引号

如果你要表示为代码的单词或短语中包含一个或多个反引号，则可以通过将单词或短语包裹在双反引号(``)中。

Markdown	HTML
``Use `code` in your Markdown file.``	<code>Use `code` in your Markdown file.</code>

7.2 代码块

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

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

8. 分隔线

要创建分隔线，请在单独一行上使用三个或多个星号(***)、破折号(---)或下划线(___)，并且不能包含其他内容。

---
---

---

8.1 分隔线最佳实践

为了兼容性，请在分隔线的前后均添加空白行。

✅ Do this	❌ Don’t do this
`Try to put a blank line before...` `---` `...and after a horizontal rule.`	`Without blank lines, this would be a heading.` `---` `Don't do this!`

9. 链接

链接文本放在中括号内，链接地址放在后面的括号中，链接 title 可选。

超链接Markdown语法代码：[超链接显示名](超链接地址 "超链接title")

对应的HTML代码：<a href="超链接地址" title="超链接title">超链接显示名</a>

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

9.1 给链接增加 Title

链接 title 是当鼠标悬停在链接上时会出现的文字，这个 title 是可选的，它放在圆括号中链接地址后面，跟链接地址之间以空格分隔。

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

9.2 网址和 Email 地址

使用尖括号可以很方便地把 URL 或者 email 地址变成可点击的链接。

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

9.3 带格式化的链接

要强调链接, 在链接语法前后增加(*)。要将链接表示为代码，请在方括号中添加(`)。

1
2
3

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

9.4 引用类型链接

引用样式链接是一种特殊的链接，它使 URL 在Markdown中更易于显示和阅读。参考样式链接分为两部分：与文本保持内联的部分以及存储在文件中其他位置的部分，以使文本易于阅读。

9.4.1 链接的第一部分格式

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

尽管不是必需的，可以在第一组和第二组括号之间包含一个空格。第二组括号中的标签不区分大小写，可以包含字母，数字，空格或标点符号。

以下示例格式对于链接的第一部分效果相同：

[hobbit-hole][1]
[hobbit-hole] [1]

9.4.2 链接的第二部分格式

引用类型链接的第二部分使用以下属性设置格式：

放在括号中的标签，其后紧跟一个冒号和至少一个空格(例如[label]:)。
链接的 URL，可以选择将其括在尖括号中。
链接的可选标题，可以将其括在双引号，单引号或括号中。

以下示例格式对于链接的第二部分效果相同：

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

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

9.5 将两部分组合在一起使用的示例

假设你将一个 URL 作为一个标准 URL 链接添加到段落中，在Markdown中如下所示：

1
2
3

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
>

9.6 链接最佳实践

不同的Markdown应用程序处理 URL 中间的空格方式不一样。为了兼容性，请尽量使用%20代替空格。

✅ Do this	❌ Don’t do this
`[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)`

10. 图片

要添加图像，请使用感叹号(!)，然后在方括号增加替代文本，图片链接放在圆括号里，括号里的链接后可以增加一个可选的图片标题文本。

插入图片Markdown语法代码：![图片alt](图片链接 "图片title")。

对应的HTML代码：<img src="图片链接" alt="图片alt" title="图片title">

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

10.1 链接图片

给图片增加链接，请将图像的Markdown括在方括号中，然后将链接添加在圆括号中。

[![An old rock in the desert](/assets/images/shiprock.jpg "Shiprock, New Mexico by 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)

11. 转义字符

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

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

11.1 可做转义的字符

以下列出的字符都可以通过使用反斜杠字符从而达到转义目的。

Character	Name
`\`	`backslash`
`	`backtick (see also escaping backticks in code)`
`*`	`asterisk`
`_`	`underscore`
`{ }`	`curly braces`
`[ ]`	`brackets`
`( )`	`parentheses`
`#`	`pound sign`
`+`	`plus sign`
`-`	`minus sign (hyphen)`
`.`	`dot`
`!`	`exclamation mark`
`\|`	`pipe (see also escaping pipe in tables)`

11.2 特殊字符自动转义

在HTML文件中，有两个字符需要特殊处理：<和&。<符号用于起始标签，&符号则用于标记HTML实体，如果你只是想要使用这些符号，你必须要使用实体的形式，像是<和&。

&符号其实很容易让写作网页文件的人感到困扰，如果你要打「AT&T」，你必须要写成「AT&T」，还得转换网址内的&符号，如果你要链接到：

1	http://images.google.com/images?num=30&q=larry+bird

你必须要把网址转成：

1	http://images.google.com/images?num=30&q=larry+bird

才能放到链接标签的href属性里。不用说也知道这很容易忘记，这也可能是HTML标准检查所检查到的错误中，数量最多的。

Markdown允许你直接使用这些符号，它帮你自动转义字符。如果你使用&符号的作为HTML实体的一部分，那么它不会被转换，而在其它情况下，它则会被转换成&。所以你如果要在文件中插入一个著作权的符号，你可以这样写：

&copy;

Markdown将不会对这段文字做修改，但是如果你这样写：

AT&T

Markdown就会将它转为：

AT&amp;T

类似的状况也会发生在<符号上，因为Markdown支持行内 HTML，如果你使用<符号作为HTML标签的分隔符，那Markdown也不会对它做任何转换，但是如果你是写：

4 < 5

Markdown将会把它转换为：

4 &lt; 5

需要特别注意的是，在Markdown的块级元素和内联元素中，<和&两个符号都会被自动转换成HTML实体，这项特性让你可以很容易地用Markdown写HTML。在HTML语法中，你要手动把所有的<和&都转换为HTML实体。

12. 内嵌`HTML`标签

对于Markdown涵盖范围之外的标签，都可以直接在文件里面用HTML本身。如需使用HTML，不需要额外标注这是HTML或是Markdown，只需HTML标签添加到Markdown文本中即可。

12.1 行级內联标签

HTML的行级內联标签如<span>、<cite>、<del>不受限制，可以在Markdown的段落、列表或是标题里任意使用。依照个人习惯，甚至可以不用Markdown格式，而采用HTML标签来格式化。例如：如果比较喜欢HTML的<a>或<img>标签，可以直接使用这些标签，而不用Markdown提供的链接或是图片语法。当你需要更改元素的属性时(例如为文本指定颜色或更改图像的宽度)，使用HTML标签更方便些。

HTML行级內联标签和区块标签不同，在內联标签的范围内，Markdown的语法是可以解析的。

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

12.2 区块标签

区块元素 ── 比如<div>、<table>、<pre>、<p>等标签，必须在前后加上空行，以便于内容区分。而且这些元素的开始与结尾标签，不可以用tab或是空白来缩进。Markdown会自动识别这区块元素，避免在区块标签前后加上没有必要的<p>标签。

例如，在Markdown文件里加上一段HTML表格：

This is a regular paragraph.

<table>
    <tr>
        <td>Foo</td>
    </tr>
</table>

This is another regular paragraph.

请注意，Markdown语法在HTML区块标签中将不会被进行处理。例如，你无法在HTML区块内使用Markdown形式的强调。

12.3 HTML 用法最佳实践

出于安全原因，并非所有Markdown应用程序都支持在Markdown文档中添加HTML。如有疑问，请查看相应Markdown应用程序的手册。某些应用程序只支持HTML标签的子集。

对于HTML的块级元素<div>、<table>、<pre>和<p>，请在其前后使用空行(blank lines)与其它内容进行分隔。尽量不要使用制表符(tabs)或空格(spaces)对HTML标签做缩进，否则将影响格式。

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