Markdown 教程#

这是一个展示如何编写 Markdown 文件的示例。本文档集成了核心语法和扩展 (GFM)。

块级元素
- 段落和换行
- 标题
- 引用
- 列表
- 代码块
- 水平分割线
- 表格
行内元素
- 链接
- 强调
- 代码
- 图片
- 删除线
其他
- 自动链接
- 反斜杠转义
内联 HTML

块级元素#

段落和换行#

段落#

HTML 标签: <p>

一个或多个空行。（包含只有空格或制表符的行也被视为空行。）

代码:

1
这段文字
2
在同一行。
3

4
这是第二个段落。

预览:

这段文字在同一行。

这是第二个段落。

换行#

HTML 标签: <br />

在一行的末尾加上两个或更多的空格。

代码:

1
这段文字
2
不在同一行。

预览:

这段文字
不在同一行。

标题#

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

Setext#

HTML 标签: <h1>, <h2>

使用等号 (=) 作为 <h1> 和减号 (-) 作为 <h2> 进行“下划线”标注，数量不限。

代码:

1
这是一级标题
2
=============
3
这是二级标题
4
-------------

预览:

这是一级标题#

这是二级标题#

atx#

HTML 标签: <h1>, <h2>, <h3>, <h4>, <h5>, <h6>

在行首使用 1-6 个井号 (#)，对应 <h1> - <h6>。

代码:

1
# 这是一级标题
2
## 这是二级标题
3
###### 这是六级标题

预览:

这是一级标题#

这是二级标题#

这是六级标题#

可选地，您可以“闭合”atx 风格的标题。闭合用的井号不需要匹配开启标题时使用的井号数量。

代码:

1
# 这是一级标题 #
2
## 这是二级标题 ##
3
### 这是三级标题 ######

预览:

这是一级标题#

这是二级标题#

这是三级标题#

引用#

HTML 标签: <blockquote>

Markdown 使用邮件风格的 > 字符进行引用。最好对文本进行硬换行，并在每一行前都加上 >。

代码:

1
> 这是一个包含两个段落的引用块。这里是示例文本，
2
> 这里是示例文本。这里是示例文本。
3
>
4
> 这是第二个段落。这里是示例文本。这里是示例文本。
5
> 这里是示例文本。

预览:

这是一个包含两个段落的引用块。这里是示例文本，这里是示例文本。这里是示例文本。

这是第二个段落。这里是示例文本。这里是示例文本。这里是示例文本。

Markdown 允许您偷懒，只在硬换行段落的第一行前加上 >。

代码:

1
> 这是一个包含两个段落的引用块。这里是示例文本，
2
这里是示例文本。这里是示例文本。
3

4
> 这是第二个段落。这里是示例文本。这里是示例文本。
5
这里是示例文本。

预览:

这是一个包含两个段落的引用块。这里是示例文本，这里是示例文本。这里是示例文本。

这是第二个段落。这里是示例文本。这里是示例文本。这里是示例文本。

引用可以嵌套（即引用中的引用），只需添加额外层级的 >。

代码:

1
> 这是第一层引用。
2
>
3
> > 这是嵌套引用。
4
>
5
> 回到第一层。

预览:

这是第一层引用。

这是嵌套引用。

回到第一层。

引用可以包含其他 Markdown 元素，包括标题、列表和代码块。

代码:

1
> ## 这是一个标题。
2
>
3
> 1.   这是第一个列表项。
4
> 2.   这是第二个列表项。
5
>
6
> 这里是一些示例代码:
7
>
8
>     return shell_exec("echo $input | $markdown_script");

预览:

这是一个标题。#

这是第一个列表项。

这是第二个列表项。

这里是一些示例代码:
1
return shell_exec("echo $input | $markdown_script");

列表#

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

无序列表#

HTML 标签: <ul>

无序列表使用星号 (*)、加号 (+) 和减号 (-)。

代码:

1
*   红色
2
*   绿色
3
*   蓝色

预览:

红色
绿色
蓝色

等同于：

代码:

1
+   红色
2
+   绿色
3
+   蓝色

以及：

代码:

1
-   红色
2
-   绿色
3
-   蓝色

有序列表#

HTML 标签: <ol>

有序列表使用数字后跟句点：

代码:

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

预览:

第一项
第二项
第三项

可能会因写出如下内容而意外触发有序列表：

代码:

1
1986. 这是一个伟大的赛季。

预览:

这是一个伟大的赛季。

您可以对句点进行反斜杠转义 (\)：

代码:

1
1986\. 这是一个伟大的赛季。

预览:

1986. 这是一个伟大的赛季。

缩进#

引用#

要在列表项中放入引用，引用的 > 分隔符需要缩进：

代码:

1
*   一个包含引用的列表项:
2

3
    > 这是列表项内的
4
    > 引用。

预览:

一个包含引用的列表项:

这是列表项内的引用。

代码块#

要在列表项中放入代码块，代码块需要缩进两次 —— 8 个空格或两个制表符：

代码:

1
*   一个包含代码块的列表项:
2

3
        <代码在这里>

预览:

一个包含代码块的列表项:
```
1
<代码在这里>
```

嵌套列表#

代码:

1
* 列表 A
2
  * 子项 A1
3
  * 子项 A2
4
* 列表 B
5
* 列表 C

预览:

列表 A
- 子项 A1
- 子项 A2
列表 B
列表 C

代码块#

HTML 标签: <pre>

将块的每一行缩进至少 4 个空格或 1 个制表符。

代码:

1
这是一个普通段落:
2

3
    这是一个代码块。

预览:

这是一个普通段落:

1
这是一个代码块。

代码块会一直持续，直到遇到未缩进的行（或文章结束）。

在代码块内，和号 (&) 和 尖括号 (< 和 >) 会自动转换为 HTML 实体。

代码:

1
    <div class="footer">
2
        &copy; 2004 Foo Corporation
3
    </div>

预览:

1
<div class="footer">
2
    &copy; 2004 Foo Corporation
3
</div>

接下来的“围栏代码块”和“语法高亮”部分是扩展功能，您可以使用另一种方式编写代码块。

围栏代码块#

只需用 ``` 包裹您的代码（如下所示），您就不需要缩进四个空格了。

代码:

1
这是一个示例:
2

3
```
4
function test() {
5
  console.log("注意这个函数前的空行？");
6
}
7
```

预览:

这是一个示例:

1
function test() {
2
  console.log("注意这个函数前的空行？");
3
}

语法高亮#

在您的围栏块中，添加可选的语言标识符，我们将对其进行语法高亮 (支持的语言)。

代码:

1
```ruby
2
require 'redcarpet'
3
markdown = Redcarpet.new("你好，世界！")
4
puts markdown.to_html
5
```

预览:

1
require 'redcarpet'
2
markdown = Redcarpet.new("你好，世界！")
3
puts markdown.to_html

水平分割线#

HTML 标签: <hr />

在一行中单独放置三个或更多的减号 (-)、星号 (*) 或下划线 (_)。您可以在减号或星号之间使用空格。

代码:

1
* * *
2
***
3
*****
4
- - -
5
---------------------------------------
6
___

预览:

表格#

HTML 标签: <table>

这是一个扩展功能。

使用竖线 (|) 分隔列，使用减号 (-) 分隔表头，并使用冒号 (:) 进行对齐。

外部的竖线 (|) 和对齐是可选的。每个单元格至少要有 3 个分隔符用于分隔表头。

代码:

1
| 左对齐 | 居中 | 右对齐 |
2
|:-----|:------:|------:|
3
|aaa   |bbb     |ccc    |
4
|ddd   |eee     |fff    |
5

6
 列 A | 列 B
7
---|---
8
123|456
9

10

11
列 A |列 B
12
--|--
13
12|45

预览:

左对齐	居中	右对齐
aaa	bbb	ccc
ddd	eee	fff

列 A	列 B
123	456

列 A	列 B
12	45

行内元素#

链接#

HTML 标签: <a>

Markdown 支持两种风格的链接：行内和引用。

行内#

行内链接格式如下：[链接文本](URL "标题")

标题是可选的。

代码:

1
这是一个 [示例](http://example.com/ "标题") 行内链接。
2

3
[这个链接](http://example.net/) 没有标题属性。

预览:

这是一个示例行内链接。

这个链接没有标题属性。

如果您引用同一服务器上的本地资源，可以使用相对路径：

代码:

1
查看我的 [关于](/about/) 页面了解详情。

预览:

查看我的关于页面了解详情。

引用#

您可以预定义链接引用。格式如下：[id]: URL "标题"

标题也是可选的。然后您引用该链接，格式如下：[链接文本][id]

代码:

1
[id]: http://example.com/  "这里是可选标题"
2
这是一个 [示例][id] 引用类型链接。

预览:

这是一个示例引用类型链接。

即：

包含链接标识符的方括号（不区分大小写，可选择从左边距缩进最多三个空格）；
后跟一个冒号；
后跟一个或多个空格（或制表符）；
后跟链接的 URL；
链接 URL 可选地可以用尖括号括起来。
可选地后跟链接的标题属性，用双引号或单引号括起来，或者用圆括号括起来。

以下三个链接定义是等效的：

代码:

1
[foo]: http://example.com/  "这里是可选标题"
2
[foo]: http://example.com/  '这里是可选标题'
3
[foo]: http://example.com/  (这里是可选标题)
4
[foo]: <http://example.com/>  "这里是可选标题"

使用一组空的方括号，链接文本本身将被用作名称。

代码:

1
[Google]: http://google.com/
2
[Google][]

预览:

Google

强调#

HTML 标签: <em>, <strong>

Markdown 将星号 (*) 和下划线 (_) 视为强调的指示符。一个分隔符将是 <em>；两个分隔符将是 <strong>。

代码:

1
*单个星号*
2

3
_单个下划线_
4

5
**双星号**
6

7
__双下划线__

预览:

单个星号

单个下划线

双星号

双下划线

但是，如果您在 * 或 _ 周围加上空格，它将被视为字面意义上的星号或下划线。

您可以对其进行反斜杠转义：

代码:

1
\*这段文本被字面星号包围\*

预览:

*这段文本被字面星号包围*

代码#

HTML 标签: <code>

用反引号 (`) 包裹它。

代码:

1
使用 `printf()` 函数。

预览:

使用 printf() 函数。

要在代码跨度内包含字面反引号字符，您可以使用多个反引号作为开启和关闭分隔符：

代码:

1
``这里有一个字面反引号 (`)。``

预览:

这里有一个字面反引号 (`)。

包围代码跨度的反引号分隔符可以包含空格 —— 开启后一个，关闭前一个。这允许您在代码跨度的开头或结尾放置字面反引号字符：

代码:

1
代码段中的单个反引号: `` ` ``
2

3
代码段中反引号分隔的字符串: `` `foo` ``

预览:

代码段中的单个反引号: `

代码段中反引号分隔的字符串: `foo`

图片#

HTML 标签: <img />

Markdown 使用一种旨在类似于链接语法的图片语法，允许两种风格：行内和引用。

行内#

行内图片语法如下：![Alt text](URL "标题")

标题是可选的。

代码:

1
![替代文本](/path/to/img.jpg)
2

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

预览:

替代文本

即：

一个感叹号: !;
后跟一组方括号，包含图片的 alt 属性文本；
后跟一组圆括号，包含图片的 URL 或路径，以及用双引号或单引号括起来的可选标题属性。

引用#

引用风格的图片语法如下：![Alt text][id]

代码:

1
[img id]: https://s2.loli.net/2024/08/20/5fszgXeOxmL3Wdv.webp  "可选标题属性"
2
![替代文本][img id]

预览:

替代文本

删除线#

HTML 标签: <del>

这是一个扩展功能。

GFM 增加了删除线文本的语法。

代码:

1
~~错误文本~~

预览:

~~错误文本~~

其他#

自动链接#

Markdown 支持一种创建 URL 和电子邮件地址“自动”链接的快捷方式：只需用尖括号包裹 URL 或电子邮件地址。

代码:

1
<http://example.com/>
2

3
<address@example.com>

预览:

http://example.com/

address@example.com

GFM 会自动链接标准 URL。

代码:

1
https://github.com/emn178/markdown

预览:

https://github.com/emn178/markdown

反斜杠转义#

Markdown 允许您使用反斜杠转义来生成字面字符，否则这些字符在 Markdown 的格式语法中具有特殊含义。

代码:

1
\*字面星号\*

预览:

*字面星号*

Markdown 为以下字符提供反斜杠转义：

代码:

1
\   反斜杠
2
`   反引号
3
*   星号
4
_   下划线
5
{}  花括号
6
[]  方括号
7
()  圆括号
8
#   井号
9
+   加号
10
-   减号
11
.   点
12
!   感叹号

内联 HTML#

对于 Markdown 语法未涵盖的任何标记，您只需使用 HTML 本身。无需前缀或定界符来指示您正在从 Markdown 切换到 HTML；只需使用标签即可。

代码:

1
这是一个普通段落。
2

3
<table>
4
    <tr>
5
        <td>Foo</td>
6
    </tr>
7
</table>
8

9
这是另一个普通段落。

预览:

这是一个普通段落。

Foo

这是另一个普通段落。

请注意，Markdown 格式语法不会在块级 HTML 标签内处理。

与块级 HTML 标签不同，Markdown 语法会在行内级标签内处理。

代码:

1
<span>**有效**</span>
2

3
<div>
4
    **无效**
5
</div>

预览:

有效

**无效**

***