Markdown 详细语法指南

前言

Markdown 是一种轻量级标记语言，由 John Gruber 于 2004 年创建。它允许使用简单的文本语法来编写结构化文档，最终转换为 HTML 格式显示。由于其简洁易用的特性，Markdown 已成为技术文档、博客写作、README 文件的标准格式，广泛应用于 GitHub、掘金、CSDN、知乎等平台。

本文将详细介绍 Markdown 的完整语法体系，涵盖基础语法、扩展语法、最佳实践等内容，帮助读者全面掌握 Markdown 编写技巧。

一、基础语法

1.1 标题

Markdown 支持六级标题，使用 # 符号表示，# 数量对应标题级别。

markdown

# 一级标题 (H1)

## 二级标题 (H2)

### 三级标题 (H3)

#### 四级标题 (H4)

##### 五级标题 (H5)

###### 六级标题 (H6)

渲染效果：

一级标题 (H1)

二级标题 (H2)

三级标题 (H3)

四级标题 (H4)

五级标题 (H5)

六级标题 (H6)

注意事项：

# 与标题文本之间必须有空格
建议一篇文档只有一个 H1 标题
标题后不应紧跟空行（部分渲染器要求空行）

1.2 段落与换行

Markdown 中的段落由空行分隔，换行需要在行尾添加两个空格。

markdown

这是第一段。

这是第二段。

这是一行  
这是同一行的下一部分（行尾有两个空格）

渲染效果：

这是第一段。

这是第二段。

这是一行
这是同一行的下一部分（行尾有两个空格）

1.3 强调

Markdown 提供两种强调方式：斜体和粗体。

markdown

_斜体文本_ 或 _斜体文本_

**粗体文本** 或 **粗体文本**

**_粗斜体文本_** 或 **_粗斜体文本_**

渲染效果：

斜体文本 或 斜体文本

粗体文本 或 粗体文本

粗斜体文本 或 粗斜体文本

1.4 删除线

使用 ~~ 包裹文本表示删除线。

markdown

~~删除的文本~~

渲染效果：

~~删除的文本~~

1.5 引用

使用 > 符号表示引用，支持嵌套引用。

markdown

> 这是一级引用
>
> > 这是二级引用
> >
> > > 这是三级引用

> 引用段落可以包含多个
> 连续的行

渲染效果：

这是一级引用
这是二级引用
这是三级引用

引用段落可以包含多个连续的行

1.6 列表

无序列表

使用 -、* 或 + 表示无序列表项。

markdown

- 列表项一
- 列表项二
- 列表项三

* 列表项一
* 列表项二
* 列表项三

- 列表项一
- 列表项二
- 列表项三

渲染效果：

列表项一
列表项二
列表项三

有序列表

使用数字加 . 表示有序列表项。

markdown

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

渲染效果：

第一步
第二步
第三步

嵌套列表

列表项可以嵌套，嵌套时缩进两个空格。

markdown

1. 外层列表项一
   - 内层无序列表项
   - 内层无序列表项
2. 外层列表项二
   1. 内层有序列表项
   2. 内层有序列表项

渲染效果：

外层列表项一
- 内层无序列表项
- 内层无序列表项
外层列表项二
1. 内层有序列表项
2. 内层有序列表项

1.7 代码

行内代码

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

markdown

使用 `console.log()` 输出日志。

变量 `name` 的类型是 `string`。

渲染效果：

使用 console.log() 输出日志。

变量 name 的类型是 string。

代码块

使用三个反引号 ``` 包裹代码块，可指定语言高亮。

markdown

```javascript
function hello(name) {
  console.log(`Hello, ${name}!`);
}
```

python

def hello(name):
    print(f"Hello, {name}!")

bash

npm install vue


**渲染效果：**

```javascript
function hello(name) {
  console.log(`Hello, ${name}!`);
}

python

def hello(name):
    print(f"Hello, {name}!")

bash

npm install vue

1.8 链接

基础链接

markdown

[链接文本](URL地址)

[访问 GitHub](https://github.com)

渲染效果：

链接文本

访问 GitHub

带标题的链接

markdown

[链接文本](URL地址 "链接标题")

[访问 GitHub](https://github.com "GitHub 官方网站")

渲染效果：

访问 GitHub

引用链接

markdown

[访问 GitHub][github]
[访问 VitePress][vitepress]

[github]: https://github.com
[vitepress]: https://vitepress.dev

渲染效果：

访问 GitHub 访问 VitePress

自动链接

markdown

<https://github.com>
<email@example.com>

渲染效果：

https://github.com email@example.com

1.9 图片

基础图片

markdown

![图片替代文本](图片URL)

![示例图片](https://picsum.photos/400/200)

渲染效果：

示例图片

带标题的图片

markdown

![图片替代文本](图片URL "图片标题")

![示例图片](https://picsum.photos/400/200 "这是一张示例图片")

引用图片

markdown

![示例图片][example-img]

[example-img]: https://picsum.photos/400/200

图片作为链接

markdown

[![示例图片](https://picsum.photos/200/100)](https://picsum.photos)

渲染效果：

1.10 分割线

使用 ---、*** 或 ___ 表示分割线，需要单独占一行。

markdown

---
---

---

渲染效果：

二、扩展语法

2.1 表格

Markdown 支持简单的表格语法。

markdown

| 姓名 | 年龄 | 职业     |
| ---- | ---- | -------- |
| 张三 | 25   | 工程师   |
| 李四 | 30   | 设计师   |
| 王五 | 28   | 产品经理 |

渲染效果：

姓名	年龄	职业
张三	25	工程师
李四	30	设计师
王五	28	产品经理

对齐方式

markdown

| 左对齐 | 居中对齐 |             右对齐 |
| :----- | :------: | -----------------: |
| 内容一 |  内容二  |             内容三 |
| 短     | 中等长度 | 这是一个很长的内容 |

渲染效果：

左对齐	居中对齐	右对齐
内容一	内容二	内容三
短	中等长度	这是一个很长的内容

2.2 任务列表

使用 - [ ] 和 - [x] 表示待办和已完成任务。

markdown

- [x] 完成项目文档
- [x] 编写单元测试
- [ ] 优化代码性能
- [ ] 部署到生产环境

渲染效果：

完成项目文档
编写单元测试
优化代码性能
部署到生产环境

2.3 脚注

使用 [^标记] 定义脚注，在文档末尾添加脚注内容。

markdown

这是带有脚注的文本[^1]。

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

渲染效果：

这是带有脚注的文本

2.4 定义列表

部分 Markdown 渲染器支持定义列表。

markdown

术语一
: 术语一的定义说明

术语二
: 术语二的第一个定义
: 术语二的第二个定义

渲染效果：

术语一 : 术语一的定义说明

术语二 : 术语二的第一个定义 : 术语二的第二个定义

2.5 数学公式

使用 $$ 包裹 LaTeX 数学公式。

markdown

$$
E = mc^2
$$

$$
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
$$

渲染效果：

$$ E = mc^2 $$

$$ \sum_{i=1}^{n} i = \frac{n(n+1)}{2} $$

2.6 目录

使用 [[toc]] 或特定语法生成目录（取决于渲染器）。

markdown

[[toc]]

2.7 代码高亮

在代码块中指定语言，支持多种编程语言。

markdown

```html
<div class="container">
  <p>Hello World</p>
</div>
```

css

.container {
  display: flex;
  justify-content: center;
}

json

{
  "name": "markdown",
  "version": "1.0.0"
}


**渲染效果：**

```html
<div class="container">
  <p>Hello World</p>
</div>

css

.container {
  display: flex;
  justify-content: center;
}

json

{
  "name": "markdown",
  "version": "1.0.0"
}

三、Frontmatter

Frontmatter 是位于文档顶部的元数据区域，使用 --- 包裹。

markdown

---
title: Markdown 详细语法指南
date: 2026-07-02
tags: [Markdown, 语法, 教程]
categories: [前端]
author: 作者名称
description: 文章描述信息
---

常见字段：

字段	说明	示例
`title`	文章标题	`Markdown 详细语法指南`
`date`	发布日期	`2026-07-02`
`tags`	标签数组	`[Markdown, 语法, 教程]`
`categories`	分类数组	`[前端]`
`author`	作者名称	`作者名称`
`description`	文章描述	`文章描述信息`
`draft`	是否草稿	`true` 或 `false`
`hidden`	是否隐藏	`true` 或 `false`

四、转义字符

使用反斜杠 \ 转义特殊字符。

markdown

\*斜体文本\* 不会被渲染为斜体

\\ 显示反斜杠

\[链接文本](URL) 显示为普通文本

\# 标题

渲染效果：

*斜体文本* 不会被渲染为斜体

\ 显示反斜杠

[链接文本](URL) 显示为普通文本

# 标题

需要转义的字符：

markdown

\ 反斜杠
` 反引号

- 星号
  \_ 下划线
  {} 花括号
  [] 方括号
  () 圆括号

# 井号

- 加号

* 减号
  . 点号
  ! 感叹号

五、常见踩坑点

5.1 标题与内容之间缺少空行

markdown

## 标题

内容

问题： 部分渲染器可能无法正确识别标题。

解决方案： 在标题和内容之间添加空行。

markdown

## 标题

内容

5.2 列表项换行问题

markdown

- 列表项一
  继续列表项一

问题： 第二行可能被解析为新段落。

解决方案： 行尾添加两个空格或使用缩进。

markdown

- 列表项一  
  继续列表项一

- 列表项一
  继续列表项一

5.3 代码块语言标识错误

markdown

```javascript
print("Hello");
```


**问题：** 使用了 JavaScript 语法高亮但代码是 Python。

**解决方案：** 使用正确的语言标识。

```markdown
```python
print("Hello")


### 5.4 链接中包含特殊字符

```markdown
[链接](https://example.com?a=1&b=2)

问题： & 字符可能导致渲染错误。

解决方案： 使用 HTML 实体编码。

markdown

[链接](https://example.com?a=1&b=2)

5.5 表格对齐错误

markdown

| 左对齐 | 右对齐 |
| :----- | -----: |
| 内容   |   内容 |

问题： 分隔行格式错误。

解决方案： 每个单元格都需要分隔符。

markdown

| 左对齐 | 右对齐 |
| :----- | -----: |
| 内容   |   内容 |

六、最佳实践

6.1 文档结构规范

文档顶部使用 Frontmatter 定义元数据
使用 H1 作为文档主标题（建议仅使用一个）
使用 H2-H6 组织内容层级
段落之间使用空行分隔
列表和引用前后添加空行

6.2 代码块规范

始终指定代码块的语言标识
代码保持适当缩进
代码注释清晰简洁
长代码行适当换行

6.3 链接规范

链接文本清晰描述目标内容
外部链接使用完整 URL
内部链接使用相对路径
定期检查链接有效性

6.4 图片规范

提供有意义的替代文本
控制图片尺寸
使用合适的图片格式
本地图片使用相对路径

6.5 版本兼容性

不同平台的 Markdown 渲染器可能存在差异，注意以下兼容性问题：

语法	GitHub	VitePress	CSDN	掘金
表格	✅	✅	✅	✅
任务列表	✅	✅	❌	✅
脚注	✅	✅	❌	✅
数学公式	❌	✅	✅	✅
定义列表	✅	✅	❌	❌

七、常用工具推荐

7.1 编辑器

VS Code：支持 Markdown 预览和丰富插件
Typora：所见即所得的 Markdown 编辑器
Obsidian：知识管理与 Markdown 写作工具
Notion：集成 Markdown 支持的协作平台

7.2 在线工具

Dillinger：在线 Markdown 编辑器
StackEdit：支持云端同步的在线编辑器
Markdown Live Preview：实时预览工具

7.3 转换工具

Pandoc：强大的文档格式转换工具
Markdown to PDF：在线转换工具
vitepress：将 Markdown 转换为静态网站

八、全文总结

本文详细介绍了 Markdown 的完整语法体系，包括：

基础语法：标题、段落、强调、删除线、引用、列表、代码、链接、图片、分割线
扩展语法：表格、任务列表、脚注、定义列表、数学公式、目录、代码高亮
Frontmatter：文档元数据配置
转义字符：特殊字符处理
踩坑点：常见问题及解决方案
最佳实践：文档规范和版本兼容性
工具推荐：编辑器和转换工具

Markdown 的核心优势在于简洁高效，掌握这些语法后，可以快速编写结构清晰、格式美观的技术文档。建议根据目标平台的渲染特性选择合适的语法，确保文档在不同环境下都能正确显示。

参考资源：

Markdown 详细语法指南 ​

前言 ​

一、基础语法 ​

1.1 标题 ​

一级标题 (H1) ​

二级标题 (H2) ​

三级标题 (H3) ​

四级标题 (H4) ​

五级标题 (H5) ​

六级标题 (H6) ​

1.2 段落与换行 ​

1.3 强调 ​

1.4 删除线 ​

1.5 引用 ​

1.6 列表 ​

无序列表 ​

有序列表 ​

嵌套列表 ​

1.7 代码 ​

行内代码 ​

代码块 ​

1.8 链接 ​

基础链接 ​

带标题的链接 ​

引用链接 ​

自动链接 ​

1.9 图片 ​

基础图片 ​

带标题的图片 ​

引用图片 ​

图片作为链接 ​

1.10 分割线 ​

二、扩展语法 ​

2.1 表格 ​

对齐方式 ​

2.2 任务列表 ​

2.3 脚注 ​

2.4 定义列表 ​

2.5 数学公式 ​

2.6 目录 ​

2.7 代码高亮 ​

三、Frontmatter ​

四、转义字符 ​

五、常见踩坑点 ​

5.1 标题与内容之间缺少空行 ​

5.2 列表项换行问题 ​

5.3 代码块语言标识错误 ​

5.5 表格对齐错误 ​

六、最佳实践 ​

6.1 文档结构规范 ​

6.2 代码块规范 ​

6.3 链接规范 ​

6.4 图片规范 ​

6.5 版本兼容性 ​

七、常用工具推荐 ​

7.1 编辑器 ​

7.2 在线工具 ​

7.3 转换工具 ​

八、全文总结 ​

Markdown 详细语法指南

前言

一、基础语法

1.1 标题

一级标题 (H1)

二级标题 (H2)

三级标题 (H3)

四级标题 (H4)

五级标题 (H5)

六级标题 (H6)

1.2 段落与换行

1.3 强调

1.4 删除线

1.5 引用

1.6 列表

无序列表

有序列表

嵌套列表

1.7 代码

行内代码

代码块

1.8 链接

基础链接

带标题的链接

引用链接

自动链接

1.9 图片

基础图片

带标题的图片

引用图片

图片作为链接

1.10 分割线

二、扩展语法

2.1 表格

对齐方式

2.2 任务列表

2.3 脚注

2.4 定义列表

2.5 数学公式

2.6 目录

2.7 代码高亮

三、Frontmatter

四、转义字符

五、常见踩坑点

5.1 标题与内容之间缺少空行

5.2 列表项换行问题

5.3 代码块语言标识错误

5.5 表格对齐错误

六、最佳实践

6.1 文档结构规范

6.2 代码块规范

6.3 链接规范

6.4 图片规范

6.5 版本兼容性

七、常用工具推荐

7.1 编辑器

7.2 在线工具

7.3 转换工具

八、全文总结