最全面的 Markdown 语法参考手册

精通Markdown,看这一篇就够了!

文章目录

Markdown 是一种轻量级的标记语言,它允许你使用易于阅读和编写的纯文本格式来创建结构化的文档。Markdown 的设计目标是尽可能地易读易写。它被广泛应用于编写文档、笔记、博客、书籍以及在各种在线平台上进行内容创作。本教程手册将全面介绍 Markdown 的基本语法和扩展语法,并提供一些实用的技巧,助你快速上手并精通 Markdown。

如果你还不知道 Markdown 是什么,请阅读文章:什么是 Markdown?一文带你了解这个内容创作者的效率神器

💡 为方便查看本手册中的 Markdown 语法渲染效果,可以将 Markdown 语法示例复制到 「人言兑.md」 中进行预览(人言兑.md 是一个使用 Markdown 语法编写公众号文章的在线编辑器,点击 这里 了解详情)。

Markdown 基本语法

以下是 Markdown 的核心语法元素,它们在所有 Markdown 应用中都应该被支持。

标题 (Headings)

Markdown 语法中支持六级标题,通过在行首添加 # 符号来定义标题级别,# 的数量对应标题的级别。

  • # 一级标题 渲染为 <h1>一级标题</h1>
  • ## 二级标题 渲染为 <h2>二级标题</h2>
  • ### 三级标题 渲染为 <h3>三级标题</h3>
  • #### 四级标题 渲染为 <h4>四级标题</h4>
  • ##### 五级标题 渲染为 <h5>五级标题</h5>
  • ###### 六级标题 渲染为 <h6>六级标题</h6>

另外,还可以使用 =- 来创建一级和二级标题:

一级标题
========

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

最佳实践

  • # 符号和标题文本之间添加一个空格。
  • 为了兼容性,在标题前后添加空行。

段落 (Paragraphs)

Markdown 语法中的段落由一个或多个文本行组成,使用空行来分隔不同的段落

这是第一段。

这是第二段。

最佳实践不要使用空格或制表符缩进段落,除非段落位于列表中。

换行 (Line Breaks)

Markdown 语法中,在一行的末尾添加 两个或多个空格,然后键入回车来创建一个换行。你也可以使用 <br> HTML 标签来换行。

最佳实践: 为了兼容性,建议使用尾随空格或 <br> 标签。

粗体 (Bold)

Markdown 语法支持两种强调方式:使用 两个星号 () 或 两个下划线 (__) 将文本括起来。

**粗体文本**__粗体文本__ 渲染为 <strong>粗体文本</strong>

**这是粗体文本**
__这也是粗体文本__

最佳实践:为了兼容性,使用星号来加粗单词中间部分。 例如: Love**is**bold,同时,建议在加粗的中文文本的前后添加空格。

斜体 (Italic)

Markdown 语法使用 一个星号 *一个下划线 _ 包裹需要斜体的文本。

*斜体文本*_斜体文本_ 渲染为 <em>斜体文本</em>

_这是斜体文本_
_这也是斜体文本_

最佳实践:为了兼容性,建议在单词中间使用星号 * 来倾斜。 例如:A*cat*meow

粗体和斜体 (Bold and Italic)

Markdown 语法使用 三个星号 ***三个下划线 ___ 包裹需要同时加粗和斜体的文本。

***这是粗斜体文本***
___这也是粗斜体文本___

最佳实践:

  • 为了兼容性,使用星号来斜体加粗单词中间部分。
  • 使用 **_粗斜体_**_**粗斜体**_ 更加直观。

引用 (Blockquotes)

在段落前添加 > 符号来创建引用。

> 这是引用的内容
>
> 这是引用的内容
>
> 这是引用的内容

最佳实践:在引用前后各留一个空行,以确保正确渲染。

引用可以包含其他 Markdown 格式的元素进行嵌套引用,使用多个 > 符号来创建嵌套引用

> 这是第一层引用

> > 这是第二层引用

> > > 这是第三层引用

列表 (Lists)

Markdown 语法支持有序列表和无序列表。

有序列表 (Ordered Lists)

使用 数字加英文句点 . 来创建有序列表。 数字不必按顺序排列,但列表应该以数字 1 开始。

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

最佳实践:为了兼容性,列表项分隔符建议只使用英文句点 .

无序列表 (Unordered Lists)

使用 减号 -星号 *加号 + 来创建无序列表。

- 第一项

* 第二项

+ 第三项

最佳实践

  • 在同一个列表中,不要混合使用不同的分隔符。
  • 要使无序列表的条目以数字开头,需要使用反斜杠 (\) 进行转义。 例如: - 1968\. A great year!

嵌套列表 (Nested Lists)

可以通过缩进列表项来创建嵌套列表。

1. 第一项
   1. 嵌套第一项
   2. 嵌套第二项
2. 第二项

在列表中添加其他元素

要在列表中添加其他元素(如段落、引用或代码块),需要将这些元素缩进。

- 这是第一项。
- 这是第二项。
  这是第二项下的一个段落。
- 这是第三项。

代码 (Code)

Markdown 语法中可以使用两种方式来标记代码:行内代码代码块

行内代码 (Code Spans)

使用 反引号 ` 包裹行内代码。

`这是行内代码`

如果代码本身包含反引号,可以使用 双反引号 (``) 来包裹。

`` 这是包含 ` 反引号的代码 ``

最佳实践:

  • 注意 `` 首尾的空格
  • 行内代码中的反斜杠不会被转义 例如:\` 不会被渲染成 `

代码块 (Code Blocks)

可以使用两种 Markdown 语法来创建代码块:缩进和围栏式。

缩进式代码块:将代码块的每一行缩进 至少四个空格 或一个制表符。

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

围栏式代码块:使用 三个反引号 ```三个波浪号 ~~~ 将代码块包裹起来,可以在开头的反引号或波浪号后添加代码语言的名称,以进行语法高亮。

```python
def hello():
    print("Hello, world!")
```
~~~html
<html>
  <head>
  </head>
</html>
~~~

最佳实践:围栏式代码块更易于使用和阅读,并且支持语法高亮。

分割线 (Horizontal Rules)

Markdown 语法使用 三个或更多星号 ***减号 ---下划线 ___ 来创建水平分割线。

***---___ 渲染为 <hr />

---

***

+++

最佳实践:在水平分割线前后各留一个空行。

Markdown 语法中如何添加 URL 链接?

使用 方括号 [] 包裹链接文本,紧接着使用 圆括号 () 包裹 URL 链接地址。

[链接文本](https://www.example.com)

还可以在 URL 后面的圆括号中添加链接标题

[链接文本](https://www.example.com "链接标题")

可以使用 尖括号 <> 来快速将 URL 或邮箱地址转换为链接。

<https://www.example.com>
<test@example.com>

格式化链接

使用星号 * 可以强调链接: **[链接](url)**, *[链接](url)*

**[链接文本](https://www.example.com)**
*[*链接文本*](https://www.example.com)*

使用反引号将链接表示为代码: [`code`](url)

引用链接将链接的定义与文本分开,提高了 Markdown 的可读性。

引用式链接分为两部分:链接文本链接定义。链接文本在文中直接使用,链接定义则放在文档的其他地方。

[链接文本][标签]

[标签]: https://www.example.com "链接标题"

链接文本使用两个方括号 [链接文本][标签]

链接定义可以出现在文档的任何地方,其格式是: [标签]: URL "链接标题"

标签不区分大小写。链接的定义部分可以放在文章结尾或段落后方。

最佳实践

  • URL 中如果包含空格,建议使用 %20 编码空格,或者使用 <a> 标签。
  • URL 中如果包含括号,建议分别使用 %28%29 来编码左右括号,或使用<a>标签。

图片 (Images)

Markdown 图片语法类似于链接,只是在最前面添加一个 感叹号 !

![图片描述](image.jpg)

还可以在 URL 之后的圆括号内添加图片标题

![图片描述](image.jpg "图片标题")

链接图片: 将图片 Markdown 语法用方括号括起来,然后在后面用圆括号括住链接地址。

[![alt text](image.jpg)](https://www.example.com)`

引用式图片:

![图片描述][图片标签]

[图片标签]: image.jpg "图片标题"

转义字符 (Escaping Characters)

Markdown 语法使用 反斜杠 \ 来转义 Markdown 中的特殊字符。 例如:\* 将显示为 * 而不是斜体。

可以转义的字符包括

  • 反斜杠 \
  • 反引号 `
  • 星号 *
  • 下划线 _
  • 花括号 {}
  • 方括号 []
  • 尖括号 <>
  • 圆括号 ()
  • 井号 #
  • 加号 +
  • 减号 -
  • 句点 .
  • 感叹号 !
  • 竖线 |

HTML 元素

可以在 Markdown 中直接使用 HTML 标签,当需要修改元素的属性时,使用 HTML 更方便,但并非所有 Markdown 应用都支持 HTML。

最佳实践

  • 使用空行分隔块级 HTML 元素,例如 <div><table><pre><p>
  • 不要用制表符或空格缩进 HTML 标签。
  • 不能在块级 HTML 标签中使用 Markdown 语法

Markdown 扩展语法

扩展语法是在基本语法的基础上添加的增强功能。并非所有的 Markdown 应用都支持这些扩展语法元素。

删除线 (Strikethrough)

使用 两个波浪号 ~~ 包裹需要添加删除线的文本。

~~这是删除线文本~~

~~被删除的文字~~ 渲染为 <del>被删除的文字</del>

任务列表 (Task Lists)

Markdown 语法使用 减号和方括号 - [ ] 创建任务列表,使用 - [x] 来标记已完成的任务。

- [x] 已完成的任务
- [ ] 未完成的任务

表情符号 (Emoji)

可以直接复制粘贴 emoji 或者使用 emoji 简码。例如: :joy: 会显示 😂

注意: 表情符号简码在不同应用中可能不同。

下标 (Subscript)

Markdown 语法使用 一个波浪号 ~ 包裹下标文本。

H~2~O

H~2~O 渲染为 H<sub>2</sub>O

最佳实践:可以在 HTML 中使用 <sub> 标签来实现下标。例如 H<sub>2</sub>O

上标 (Superscript)

使用 一个插入符号 ^ 包裹上标文本。

X^2^

X^2^ 渲染为 X<sup>2</sup>

最佳实践:可以在 HTML 中使用 <sup> 标签来实现上标。例如 X<sup>2</sup>

自动 URL 链接 (Automatic URL Linking)

许多 Markdown 处理器会自动将 URL 转换为链接。 例如:http://www.example.com 会被自动转换为链接。

使用反引号 ` 将 URL 括起来,以禁用自动链接: `http://www.example.com`

表格 (Tables)

Markdown 语法使用 三个或多个减号 (—) 创建表头,并使用 竖线 (|) 分隔列。

| 表头 1 | 表头 2 |
| ------ | ------ |
| 内容 1 | 内容 2 |

Markdown 表格语法最佳实践:

  • 为了兼容性,在每一行的开头和结尾添加竖线。
  • 表格单元格的宽度可以不同,渲染结果保持一致。
  • 表格中不能使用标题、引用、列表、水平线、图像或大多数 HTML 标签。
  • 可以在表格中使用 HTML <br>标签来实现单元格内的换行和使用 <ul> <li> 等标签来创建列表。
  • 转义表格中的竖线: 使用&#124;来在表格中显示竖线。

脚注 (Footnotes)

使用 [^数字] 来创建脚注标记,并在文档的其他地方使用 [^数字]: 来定义脚注内容。

这是一个带有脚注的句子。[^1]

[^1]: 这是脚注的内容。

脚注会在输出中按顺序编号。

注意: 标识符不能包含空格或制表符。

标题 ID (Heading IDs)

Markdown 可以使用 { #custom-id } 为标题添加自定义 ID,方便链接到文档内的特定部分。

## My Great Heading {#custom-id}

链接到标题 ID:

  • 可以使用 # 符号后跟自定义 ID 来创建链接。例如:
    [点击这个链接文本跳转到#custom-id 的位置](#custom-id)`
    
  • 其他网站可以通过在网页 URL 后添加自定义 ID 来链接到该标题。例如:
    [链接文本](https://www.example.com/extended-syntax#custom-id)
    

定义列表 (Definition Lists)

可以使用 term : definition 来创建定义列表。在第一行键入术语,在下一行键入冒号加空格,然后是定义。

术语
: 定义 1
: 定义 2

高亮 (Highlights)

使用 == 包裹需要高亮的文本。

==需要高亮的文字==

也可以使用 <mark> 标签: <mark>高亮文本</mark>

Markdown 技巧

以下是一些在 Markdown 中进行高级操作的技巧,这些技巧并非所有应用都支持。

下划线 (Underline)

Markdown 本身不支持下划线,可以使用 <ins> HTML 标签来实现。

<ins>下划线文字</ins> 渲染为 下划线文字

缩进 (Indent)

Markdown 对缩进有特殊含义,通常使用空格键或制表符缩进段落是不起作用的,但是可以使用以下方式实现:

  • 使用 Markdown 编辑器支持缩进的功能。
  • 使用 &nbsp; HTML 实体来创建缩进。
  • 例如: &nbsp;&nbsp;&nbsp;&nbsp; 这是缩进的段落。

居中 (Center)

Markdown 本身没有居中对齐的概念,可以使用 <center> HTML 标签来实现。

<center>居中文本</center>

也可以可以使用 CSS text-align:center 属性来实现居中, 例如:

<p style="text-align:center">居中文本</p>

颜色 (Color)

Markdown 本身没有改变文本颜色的功能,可以使用 <font> HTML 标签来实现。

<font color="red">红色文字</font> 渲染为 红色文字

可以使用 CSS color:blue 属性来改变颜色, 例如:

<p style="color:blue">蓝色文本</p>

注释 (Comments)

使用 [注释]: # 这种格式添加隐藏注释。

这是可见的段落。
[这是一个注释]: #
这是另一个可见的段落。

最佳实践: 在注释前后添加空行。

提示框 (Admonitions)

可以使用引用和表情符号以及加粗文本来模拟提示框。

> :warning: **警告:** 这是警告提示。
> :memo: **注意:** 这是注意提示。
> :bulb: **技巧:** 这是技巧提示。

图片大小 (Image Size)

使用 <img> HTML 标签的 widthheight 属性来调整图片大小。例如:

<img src="image.png" width="200" height="100">

图片标题 (Image Captions)

可以使用 <figure><figcaption> HTML 标签来为图片添加标题。

<figure>
  <img src="image.jpg" alt="图片描述" />
  <figcaption>这是图片标题</figcaption>
</figure>

也可以直接在图片下方添加文本,使用斜体强调,作为图片标题。

可以使用 <a> HTML 标签的 target="_blank" 属性来让链接在新标签页中打开。

例如:

<a href="https://www.example.com" target="_blank">在新标签页打开链接</a>

符号 (Symbols)

直接复制粘贴符号到 Markdown 文档中,也可以使用 HTML 实体代码来插入符号。

例如: &copy; 渲染为 ©

常见 HTML 实体代码:

  • &copy; (版权符号 ©)
  • &reg; (注册商标符号 ®)
  • &trade; (商标符号 ™)
  • &euro; (欧元符号 €)
  • &larr; (左箭头 ←)
  • &uarr; (上箭头 ↑)
  • &rarr; (右箭头 →)
  • &darr; (下箭头 ↓)
  • &#176; (度 °)
  • &#960; (圆周率 π)

表格格式化 (Table Formats)

表格内换行: 使用 <br> 标签来分隔表格内的段落。

表格内列表: 使用 HTML 标签 (<ul>, <li>)来在表格中添加列表。

目录 (Table of Contents)

有些 Markdown 应用可以自动生成目录,但是如果你的应用不支持此功能,可以使用列表和链接手动创建目录。

- [链接文本 1](#heading-id-1)
- [链接文本 2](#heading-id-2)
- [链接文本 3](#heading-id-3)

需要在文章中使用对应的标题 ID。

视频 (Videos)

如果应用支持 HTML, 可以直接嵌入视频网站提供的 HTML 代码。如果应用不支持,可以使用图片和链接来模拟视频嵌入。

[![视频标题](视频封面图.jpg)](视频链接)

CommonMark 规范

CommonMark 是一份对 Markdown 语法的标准化规范。以下是一些重要概念:

  • 字符和行:任何字符序列都是有效的 CommonMark 文档。字符是 Unicode 编码点。
  • 空格字符:包括 Unicode Zs 类别的字符、制表符(U+0009)、换行符(U+000A)、换页符(U+000C)和回车符(U+000D)。
  • 制表符:制表符不展开为空格,但在需要空格定义块结构时,制表符的表现如同被替换为制表符停止位为 4 个字符的空格。
  • 不安全字符:Unicode 字符 U+0000 必须替换为替换字符(U+FFFD)。
  • 反斜杠转义:任何 ASCII 标点字符都可以被反斜杠转义。反斜杠后的其他字符被视为字面反斜杠,转义字符会被视为常规字符,失去 Markdown 的特殊含义。
  • 实体引用:实体引用由 & + HTML5 实体名称 + ; 组成。例如 &amp; 代表 &&copy; 代表 ©
  • 数字字符引用:十进制字符引用由 &# + 1-7 位阿拉伯数字 + ; 组成,例如:&#35; 代表 #。十六进制字符引用由 &# + xX + 1-6 位十六进制数字 + ; 组成,例如 &#X22; 代表 "
  • HTML 块:HTML 块是指由 HTML 标签组成的块,其起始和结束条件由特定规则定义。
  • 容器块:包括块引用和列表项。列表是列表项的元容器。
  • 列表项:列表项的标记可以是项目符号或有序列表标记。项目符号列表标记使用 -+*;有序列表标记使用 1-9 位数字后跟 .)
  • 内联元素:Markdown 的内联元素按从左到右的顺序解析,包括代码跨度、强调、链接、图片等。
  • 代码跨度:由反引号包裹,内容会进行规范化处理,例如删除首尾空格。
  • 强调和加粗:使用 *_ 实现强调,使用 **__ 实现加粗,具体的规则较复杂。
  • 链接和图片:链接使用 [](),图片语法类似于链接,只是在前面添加一个 !
  • 自动链接:使用尖括号 <> 包裹 URL 会被自动解析为链接。
  • 原始 HTML:在尖括号 <> 中看起来像 HTML 标签的文本会被解析为原始 HTML。

关键点

  • 强调和加粗的规则:需要注意左侧和右侧的定界符,以及 Unicode 标点符号的影响。
  • 代码跨度:代码跨度的优先级高于除 HTML 标签和自动链接外的其他内联结构。
  • 链接:注意链接文本和链接地址的语法,以及如何使用引用式链接。
  • HTML 块:了解 HTML 块的起始和结束条件,以及如何在 Markdown 中使用 HTML 标签。
  • 列表:需要了解列表的类型,列表项的标记,以及列表的嵌套和懒惰延续行规则。

总结

本教程手册涵盖了 Markdown 的基本语法、扩展语法和一些实用技巧。Markdown 的目标是简化文档编写,让你专注于内容而不是格式。通过掌握这些语法,你可以更高效地创建结构化的文档。希望本教程手册能帮助你更好地使用 Markdown。

请注意,某些特性可能因不同的 Markdown 解析器而有所不同。为了获得最佳效果,请查阅你正在使用的特定 Markdown 应用的文档。

微信公众号二维码
本文已同步发布到微信公众号「人言兑
👈 扫描二维码关注,第一时间获取更新!

也可以看看