Markdown 语法教程手册

Markdown 语法教程手册
Markdown 是一种轻量级的标记语言，它允许你使用易于阅读和编写的纯文本格式来创建结构化的文档。Markdown 的设计目标是尽可能地易读易写。它被广泛应用于编写文档、笔记、博客、书籍以及在各种 2025-1-11 09:44:25 Author: blog.axiaoxin.com(查看原文) 阅读量:4 收藏

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

基本语法

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

标题 (Headings)

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

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

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

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

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

最佳实践：

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

段落 (Paragraphs)

段落由一个或多个文本行组成，使用空行来分隔不同的段落。

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

换行 (Line Breaks)

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

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

粗体 (Bold)

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

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

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

斜体 (Italic)

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

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

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

粗体和斜体 (Bold and Italic)

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

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

最佳实践:

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

引用 (Blockquotes)

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

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

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

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

> 这是第一层引用

> > 这是第二层引用

> > > 这是第三层引用

列表 (Lists)

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

有序列表 (Ordered Lists)

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

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

无序列表 (Unordered Lists)

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

最佳实践：

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

嵌套列表 (Nested Lists)

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

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

在列表中添加其他元素

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

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

代码 (Code)

Markdown 中可以使用两种方式来标记代码：行内代码 和 代码块。

行内代码 (Code Spans)

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

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

最佳实践:

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

代码块 (Code Blocks)

可以使用两种方式来创建代码块：缩进和围栏式。

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

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

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

```python
def hello():
    print("Hello, world!")
```

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

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

分割线 (Horizontal Rules)

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

***、--- 或 ___ 渲染为 <hr />。

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

链接 (Links)

行内链接 (Inline Links)

使用 方括号 [] 包裹链接文本，紧接着使用 圆括号 () 包裹 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)

引用式链接 (Reference Links)

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

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

[链接文本][标签]

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

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

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

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

最佳实践：

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

图片 (Images)

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

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

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

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

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

引用式图片：

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

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

转义字符 (Escaping Characters)

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

可以转义的字符包括：

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

HTML 元素

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

最佳实践：

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

扩展语法

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

删除线 (Strikethrough)

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

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

任务列表 (Task Lists)

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

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

表情符号 (Emoji)

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

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

下标 (Subscript)

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

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

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

上标 (Superscript)

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

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)

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

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

最佳实践:

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

脚注 (Footnotes)

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

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

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

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

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

标题 ID (Heading IDs)

可以使用 { #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 来创建定义列表。在第一行键入术语，在下一行键入冒号加空格，然后是定义。

高亮

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

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

Markdown 技巧

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

下划线 (Underline)

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

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

缩进 (Indent)

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

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

居中 (Center)

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

也可以可以使用 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>

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

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

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

提示框 (Admonitions)

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

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

图片大小 (Image Size)

使用 <img> HTML 标签的 width 和 height 属性来调整图片大小。例如：

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

图片标题 (Image Captions)

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

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

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

链接目标 (Link Targets)

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

例如:

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

符号 (Symbols)

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

例如: © 渲染为 ©

常见 HTML 实体代码:

© (版权符号 ©)
® (注册商标符号 ®)
™ (商标符号 ™)
€ (欧元符号 €)
← (左箭头 ←)
↑ (上箭头 ↑)
→ (右箭头 →)
↓ (下箭头 ↓)
° (度 °)
π (圆周率 π)

表格格式化

表格内换行: 使用 <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 的特殊含义。
数字字符引用：十进制字符引用由 &# + 1-7 位阿拉伯数字 + ; 组成，例如：# 代表 #。十六进制字符引用由 &# + x 或 X + 1-6 位十六进制数字 + ; 组成，例如 &#X22; 代表 "。
HTML 块：HTML 块是指由 HTML 标签组成的块，其起始和结束条件由特定规则定义。
容器块：包括块引用和列表项。列表是列表项的元容器。
列表项：列表项的标记可以是项目符号或有序列表标记。项目符号列表标记使用 -，+ 或 *；有序列表标记使用 1-9 位数字后跟 . 或 )。
内联元素：Markdown 的内联元素按从左到右的顺序解析，包括代码跨度、强调、链接、图片等。
代码跨度：由反引号包裹，内容会进行规范化处理，例如删除首尾空格。
强调和加粗：使用 * 或 _ 实现强调，使用 ** 或 __ 实现加粗，具体的规则较复杂。
链接和图片：链接使用 [] 和 ()，图片语法类似于链接，只是在前面添加一个 !。
自动链接：使用尖括号 <> 包裹 URL 会被自动解析为链接。
原始 HTML：在尖括号 <> 中看起来像 HTML 标签的文本会被解析为原始 HTML。

关键点：

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

总结

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

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

文章来源: https://blog.axiaoxin.com/post/markdown-guide/
如有侵权请联系:admin#unsafe.sh