Markdown语法

# Markdown基本语法

> 以下内容整理自：[创始人 John Gruber 在 Daring Fireball 网站上发布内容](https://daringfireball.net/projects/markdown/syntax) | 整理人： 安玉

## 概述

### 设计理念

Markdown 的目标是尽可能易于阅读和编写，优先考虑可读性。Markdown 格式的文档应以纯文本形式直接发布，不显得被标签或格式指令标记。其语法受纯文本电子邮件格式启发，采用简单的标点字符（如 `*`、`#`），这些字符直观地反映其含义。例如，`*强调*` 看起来像是强调，列表看起来像是列表，引用看起来像是引用的文本。

Markdown 的灵感来源于多种文本转 HTML 的工具（如 Setext、atx、Textile、reStructuredText、Grutatext 和 EtText），但主要受电子邮件格式的影响。Markdown 不是 HTML 的替代品，仅涵盖 HTML 标签的子集，专注于纯文本格式化。

### 内联 HTML

Markdown 的设计目的是作为网页写作的格式。它并非 HTML 的替代品，语法仅覆盖一小部分 HTML 标签，旨在简化阅读、编写和编辑文本内容。对于 Markdown 语法未涵盖的格式，可直接使用 HTML 标签，无需特别标记切换。

**块级 HTML 元素**（如 `<div>`、`<table>`、`<pre>`、`<p>`）需与周围内容用空行分隔，且开始和结束标签不得缩进。例如：

```markdown
这是一个普通段落。

这是另一个普通段落。
```

**效果**：
> 这是一个普通段落。
>
> <table>
>     <tr>
>         <td>Foo</td>
>     </tr>
> </table>
>
> 这是另一个普通段落。

**注意**：
- 块级 HTML 标签内的 Markdown 语法（如 `*强调*`）不会被处理。
- Markdown 自动避免在块级 HTML 标签周围添加多余的 `<p>` 标签。
- **行内 HTML 标签**（如 `<span>`、`<cite>`、`<del>`）可在段落、列表或标题中直接使用，Markdown 语法在行内标签内仍有效。
- 可直接使用 HTML 的 `<a>` 或 `<img>` 标签替代 Markdown 的链接或图片语法。

### 特殊字符的自动转义

在 HTML 中，`<` 和 `&` 需特别处理，分别表示标签开始和 HTML 实体。若需显示其字面值，需转义为 `&lt;` 和 `&amp;`。Markdown 自动处理这些字符的转义，简化写作。

例如，`&` 若作为 HTML 实体（如 `&copy;`）的一部分，Markdown 保留不变；否则，自动转为 `&amp;`。

```markdown
&copy;  # 保留为版权符号
AT&T    # 转为 AT&amp;T
```

**效果**：
> &copy;  
> AT&amp;T

对于 `<`，若用于 HTML 标签，Markdown 保留不变；否则，转为 `&lt;`。

```markdown
4 < 5
```

**效果**：
> 4 &lt; 5

在代码块或行内代码中，`&` 和 `<` 自动转为 HTML 实体，便于展示 HTML 示例代码。例如：

```markdown
    <div class="footer">
        &copy; 2004 Foo Corporation
    </div>
```

**效果**：
```html
<pre><code>&lt;div class="footer"&gt;
    &amp;copy; 2004 Foo Corporation
&lt;/div&gt;
</code></pre>
```

**注意**：
- 自动转义简化了 HTML 代码的编写，尤其适合描述 HTML 语法。
- 在代码块中，Markdown 语法（如 `*`）被视为字面字符，无需额外转义。

## 块级元素

### 段落与换行

段落由一个或多个连续的文本行组成，段落间通过一个或多个空行分隔。空行指仅包含空格或制表符的行。段落不应使用空格或制表符缩进。

```markdown
这是一个段落。包含多个句子。

这是另一个段落。
```

**效果**：
> 这是一个段落。包含多个句子。
>
> 这是另一个段落。

要在段落内插入换行（`<br />`），在行尾添加两个或更多空格后回车。

```markdown
第一行  
第二行
```

**效果**：
> 第一行  
> 第二行

**注意**：
- Markdown 支持“硬换行”段落，与其他文本转 HTML 工具不同，单回车不生成 `<br />`。
- 硬换行需手动添加空格，确保格式清晰。

### 标题

Markdown 支持两种标题风格：Setext 和 atx。

#### Setext 风格

使用 `=`（一级标题）或 `-`（二级标题）在文本下方“下划线”。

```markdown
一级标题
========

二级标题
--------
```

**效果**：
# 一级标题
## 二级标题

**注意**：
- `=` 或 `-` 的数量不限，至少三个。
- Setext 风格适用于简单文档。

#### atx 风格

使用 1 到 6 个 `#` 表示一级到六级标题，后跟空格。

```markdown
# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题
```

**效果**：
从大到小逐级递减。

可选地，可在标题行尾添加 `#`（仅用于美观，数量无需与开头匹配）。

```markdown
# 一级标题 #
## 二级标题 ##
### 三级标题 ######
```

**效果**：同上。

**注意**：
- `#` 后需加空格，否则可能不被解析为标题。
- atx 风格更灵活，推荐使用。

### 引用

Markdown 使用电子邮件风格的 `>` 符号创建引用，最好每行都加 `>`。

```markdown
> 这是一个引用，包含两个段落。Lorem ipsum dolor sit amet,
> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
> 
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
> id sem consectetuer libero luctus adipiscing.
```

**效果**：
> 这是一个引用，包含两个段落。Lorem ipsum dolor sit amet,  
> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.  
> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
>
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse  
> id sem consectetuer libero luctus adipiscing.

Markdown 允许只在段落首行加 `>`（“懒惰”写法），但建议每行添加以确保兼容性。

```markdown
> 这是一个引用，包含两个段落。Lorem ipsum dolor sit amet,
consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
id sem consectetuer libero luctus adipiscing.
```

#### 嵌套引用

使用多个 `>` 符号创建嵌套引用。

```markdown
> 第一级引用。
>
> > 嵌套引用。
>
> 返回第一级。
```

**效果**：
> 第一级引用。
>
> > 嵌套引用。
>
> 返回第一级。

#### 引用中的其他元素

引用可包含标题、列表、代码块等。

```markdown
> ## 引用中的标题
> 
> 1. 列表项 1
> 2. 列表项 2
> 
> 示例代码：
> 
>     return shell_exec("echo $input | $markdown_script");
```

**效果**：
> ## 引用中的标题
>
> 1. 列表项 1
> 2. 列表项 2
>
> 示例代码：
>
>     return shell_exec("echo $input | $markdown_script");

**注意**：
- 引用中的元素需保持正确的缩进。
- 部分编辑器（如 BBEdit）支持快捷键增加引用级别。

### 列表

Markdown 支持有序（编号）和无序（项目符号）列表。

#### 无序列表

使用 `*`、 `+` 或 `-` 作为列表标记，后跟空格，标记可互换。

```markdown
* 红色
* 绿色
* 蓝色
```

等同于：

```markdown
+ 红色
+ 绿色
+ 蓝色
```

或：

```markdown
- 红色
- 绿色
- 蓝色
```

**效果**：
- 红色
- 绿色
- 蓝色

#### 有序列表

使用数字加点号 `.` 创建有序列表，实际数字顺序不影响输出。

```markdown
1. Bird
2. McHale
3. Parish
```

等同于：

```markdown
1. Bird
1. McHale
1. Parish
```

或：

```markdown
3. Bird
1. McHale
8. Parish
```

**效果**：
1. Bird
2. McHale
3. Parish

**HTML 输出**：
```html
<ol>
<li>Bird</li>
<li>McHale</li>
<li>Parish</li>
</ol>
```

**注意**：
- 列表标记可缩进最多 3 个空格，后跟至少 1 个空格或制表符。
- 为美观，可使用悬挂缩进：

```markdown
*   Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
    Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
    viverra nec, fringilla in, laoreet vitae, risus.
*   Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
    Suspendisse id sem consectetuer libero luctus adipiscing.
```

- 懒惰写法无需每行缩进，但建议保持一致：

```markdown
*   Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
viverra nec, fringilla in, laoreet vitae, risus.
*   Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
Suspendisse id sem consectetuer libero luctus adipiscing.
```

- 列表项间若有空行，Markdown 将为每个列表项添加 `<p>` 标签：

```markdown
* Bird
* Magic
```

**效果**：
```html
<ul>
<li>Bird</li>
<li>Magic</li>
</ul>
```

```markdown
* Bird

* Magic
```

**效果**：
```html
<ul>
<li><p>Bird</p></li>
<li><p>Magic</p></li>
</ul>
```

- 列表项可包含多段落，续行需缩进 4 个空格或 1 个制表符：

```markdown
1.  这是一个包含两个段落的列表项。Lorem ipsum dolor
    sit amet, consectetuer adipiscing elit. Aliquam hendrerit
    mi posuere lectus.

Vestibulum enim wisi, viverra nec, fringilla in, laoreet
    vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
    sit amet velit.

2.  Suspendisse id sem consectetuer libero luctus adipiscing.
```

- 列表项内的引用需缩进 `>`：

```markdown
*   包含引用的列表项：

> 这是一个引用
    > 在列表项内。
```

- 列表项内的代码块需双倍缩进（8 个空格或 2 个制表符）：

```markdown
*   包含代码块的列表项：

<code goes here>
```

- 避免意外触发有序列表，例如：

```markdown
1986. What a great season.
```

需转义为：

```markdown
1986\. What a great season.
```

### 代码块

代码块用于展示编程或标记语言的源代码，Markdown 使用 `<pre>` 和 `<code>` 标签包裹。创建代码块需每行缩进 4 个空格或 1 个制表符。

```markdown
这是一个普通段落：

这是一个代码块。
```

**效果**：
```html
<p>这是一个普通段落：</p>

<pre><code>这是一个代码块。
</code></pre>
```

**示例**：

```markdown
这是一个 AppleScript 示例：

tell application "Foo"
        beep
    end tell
```

**效果**：
```html
<p>这是一个 AppleScript 示例：</p>

<pre><code>tell application "Foo"
    beep
end tell
</code></pre>
```

**注意**：
- 代码块持续到非缩进行或文档末尾。
- 每行缩进的 4 个空格或 1 个制表符会被移除。
- 代码块内的 `&` 和 `<` 自动转为 HTML 实体，便于展示 HTML 示例：

```markdown
    <div class="footer">
        &copy; 2004 Foo Corporation
    </div>
```

**效果**：
```html
<pre><code>&lt;div class="footer"&gt;
    &amp;copy; 2004 Foo Corporation
&lt;/div&gt;
</code></pre>
```

- 代码块内的 Markdown 语法（如 `*`）被视为字面字符。

### 水平线

使用三个或更多连字符 `-`、星号 `*` 或下划线 `_`，单独占一行，可包含空格，生成 `<hr />` 标签。

```markdown
* * *
***
*****
- - -
---------------------------------------
```

**效果**：
一条水平分割线。

## 行内元素

### 链接

Markdown 支持行内和参考两种链接风格。

#### 行内链接

使用 `[链接文本](URL)` 格式，可选添加标题 `[链接文本](URL "标题")`。

```markdown
这是一个 [示例链接](http://example.com/ "标题")。

[此链接](http://example.net/) 没有标题属性。
```

**效果**：
```html
<p>这是一个 <a href="http://example.com/" title="标题">示例链接</a>。</p>

<p><a href="http://example.net/">此链接</a> 没有标题属性。</p>
```

支持相对路径：

```markdown
查看我的 [关于页面](/about/) 获取详情。
```

#### 参考链接

使用 `[链接文本][id]` 和 `[id]: URL "可选标题"` 分离定义。

```markdown
这是一个 [示例链接][id]。

[id]: http://example.com/  "可选标题"
```

或使用空格分隔：

```markdown
这是一个 [示例链接] [id]。

[id]: http://example.com/  "可选标题"
```

**链接定义格式**：
- 方括号包含链接标识符（可缩进最多 3 个空格）。
- 后跟冒号 `:`。
- 后跟一个或多个空格/制表符。
- 后跟 URL。
- 可选后跟用双引号、单引号或括号包裹的标题。

以下定义等效：

```markdown
[foo]: http://example.com/  "可选标题"
[foo]: http://example.com/  '可选标题'
[foo]: http://example.com/  (可选标题)
```

**注意**：
- Markdown.pl 1.0.1 中单引号定义标题存在 bug，建议使用双引号或括号。
- URL 可使用 `<URL>` 包裹：

```markdown
[id]: <http://example.com/>  "可选标题"
```

- 标题可放在下一行，添加额外空格或制表符：

```markdown
[id]: http://example.com/longish/path/to/resource/here
    "可选标题"
```

- 链接标识符不区分大小写，`[a]` 和 `[A]` 等效。
- 隐式链接名称允许省略标识符，使用链接文本作为名称：

```markdown
访问 [Google][] 获取更多信息。

[Google]: http://google.com/
```

支持多词链接文本：

```markdown
访问 [Daring Fireball][] 获取更多信息。

[Daring Fireball]: http://daringfireball.net/
```

**示例**：

```markdown
我从 [Google][1] 获得的流量是 [Yahoo][2] 或 [MSN][3] 的 10 倍。

[1]: http://google.com/        "Google"
[2]: http://search.yahoo.com/  "Yahoo Search"
[3]: http://search.msn.com/    "MSN Search"
```

或使用隐式链接：

```markdown
我从 [Google][] 获得的流量是 [Yahoo][] 或 [MSN][] 的 10 倍。

[google]: http://google.com/        "Google"
[yahoo]:  http://search.yahoo.com/  "Yahoo Search"
[msn]:    http://search.msn.com/    "MSN Search"
```

**效果**：
```html
<p>我从 <a href="http://google.com/" title="Google">Google</a> 获得的流量是
<a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a> 或
<a href="http://search.msn.com/" title="MSN Search">MSN</a> 的 10 倍。</p>
```

**行内链接对比**：

```markdown
我从 [Google](http://google.com/ "Google") 获得的流量是
[Yahoo](http://search.yahoo.com/ "Yahoo Search") 或
[MSN](http://search.msn.com/ "MSN Search") 的 10 倍。
```

**优点**：
- 参考链接使源文档更简洁，减少标记干扰。
- 行内链接字符数为 176，参考链接仅 81，HTML 为 234。

### 强调

使用 `*` 或 `_` 表示强调，单个表示 `<em>`（斜体），双个表示 `<strong>`（粗体）。

```markdown
*单个星号*

_单个下划线_

**双星号**

__双下划线__
```

**效果**：
```html
<em>单个星号</em>

<em>单个下划线</em>

<strong>双下划线</strong>
```

**注意**：
- 开头和结尾必须使用相同字符。
- 可在单词内部使用：

```markdown
un*frigging*believable
```

**效果**：
> un*frigging*believable

- 若 `*` 或 `_` 周围有空格，则视为字面字符。
- 使用反斜杠转义：

```markdown
\*被星号包裹的文字\*
```

**效果**：
> *被星号包裹的文字*

### 行内代码

使用反引号 `` ` `` 包裹行内代码，自动转义 `&` 和 `<`。

```markdown
使用 `printf()` 函数。
```

**效果**：
```html
<p>使用 <code>printf()</code> 函数。</p>
```

包含反引号需使用多个反引号包裹，且可在开头后、结尾前加空格：

```markdown
``包含一个反引号 ` 的代码``
```

**效果**：
```html
<p><code>包含一个反引号 ` 的代码</code></p>
```

**示例**：

```markdown
请勿使用 `<blink>` 标签。
```

**效果**：
```html
<p>请勿使用 <code>&lt;blink&gt;</code> 标签。</p>
```

```markdown
`&#8212;` 是 `&mdash;` 的十进制编码等效形式。
```

**效果**：
```html
<p><code>&amp;#8212;</code> 是 <code>&amp;mdash;</code> 的十进制编码等效形式。</p>
```

### 图片

图片语法类似链接，使用 `![替代文本](URL)` 或参考风格。

#### 行内图片

```markdown
![替代文本](/path/to/img.jpg)

![替代文本](/path/to/img.jpg "可选标题")
```

**格式**：
- 感叹号 `!`。
- 方括号包含替代文本（`alt` 属性）。
- 括号包含图片 URL 和可选标题（用双引号或单引号）。

#### 参考图片

```markdown
![替代文本][id]

[id]: url/to/image  "可选标题"
```

**注意**：
- Markdown 不支持调整图片尺寸，需使用 HTML `<img>` 标签。
- 替代文本对可访问性重要。

## 其他

### 自动链接

URL 或邮箱地址用 `< >` 包裹，自动转为可点击链接。

```markdown
<http://example.com/>
```

**效果**：
```html
<a href="http://example.com/">http://example.com/</a>
```

邮箱地址会进行随机十进制和十六进制实体编码，防止垃圾邮件机器人抓取：

```markdown
<address@example.com>
```

**效果**：
```html
<a href="&#x6D;&#x61;i&#x6C;&#x74;&#x6F;:&#x61;&#x64;&#x64;&#x72;&#x65;...">address@example.com</a>
```

**注意**：
- 编码可降低但无法完全阻止垃圾邮件。
- 建议谨慎公开邮箱地址。

### 反斜杠转义

使用反斜杠 `\` 转义特殊字符，显示其字面值：

```markdown
\*字面星号\*
```

**效果**：
> *字面星号*

**支持的转义字符**：
```
\   反斜杠
`   反引号
*   星号
_   下划线
{}  大括号
[]  方括号
()  括号
#   井号
+   加号
-   减号（连字符）
.   点号
!   感叹号
```

## 注意事项

- **兼容性**：不同解析器可能有细微差异，建议使用 [Babelmark](https://babelmark.github.io/) 测试渲染效果。
- **扩展语法**：原始 Markdown 不支持表格、任务列表等，需依赖解析器（如 GitHub Flavored Markdown）。
- **工具**：
  - 在线编辑器：Dillinger (https://dillinger.io/)。
  - 参考资源：Markdown Guide (https://www.markdownguide.org/)，GitHub Markdown Cheatsheet。
- **脚本**：Markdown.pl（Perl 脚本）用于将 Markdown 转为 HTML，详见 [Daring Fireball](https://daringfireball.net/projects/markdown/)。