Markdown 基础语法篇
# Markdown 从零到一完全指南
# 一、前言
# 1.1 什么是 Markdown
Markdown 是一种轻量级标记语言，由 John Gruber 于 2004 年创建。它的核心理念是「易读易写」——用纯文本格式编写文档，通过简单的符号标记排版，最终可以转换成 HTML、PDF、Word 等多种格式。
Markdown 的文件扩展名通常是 .md 或 .markdown。今天你在 GitHub、GitLab、Notion、Obsidian、Typora、VuePress 等几乎所有开发者工具中都能看到它的身影。
# 1.2 为什么学习 Markdown
- 所有开发者都在用：GitHub 的 README、Issue、Pull Request 全部使用 Markdown
- 效率极高：手不离开键盘，纯文本操作，排版速度快 3-5 倍
- 跨平台：纯文本文件，任何编辑器都能打开，永不格式错乱
- 版本管理友好：纯文本便于 Git 追踪变更、diff 对比
- 扩展性强：支持 HTML、LaTeX 数学公式、Mermaid 图表、代码高亮等
# 1.3 Markdown 的方言与标准
由于原始 Markdown 语法过于简单，社区衍生出多种「方言」，其中 CommonMark 和 GitHub Flavored Markdown (GFM) 最为主流。本文以 GFM 为主要参考，并补充 VuePress 等平台的扩展语法。
# 二、基础语法
# 2.1 标题
使用 # 号标记标题，# 的数量决定标题级别（1~6级）。建议在 # 后加一个空格。
# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题
2
3
4
5
6
最佳实践：
- 一级标题 (
#) 通常留给文档标题，正文内从二级开始 - 标题后空一行更美观
- 也可以用
===和---表示一级和二级标题，但不推荐，因为兼容性差
一级标题
===
二级标题
---
2
3
4
5
# 2.2 文本样式
Markdown 提供了丰富的行内文本格式：
| 语法 | 效果 | 说明 |
|---|---|---|
**粗体** | 粗体 | 双星号包裹 |
*斜体* | 斜体 | 单星号包裹 |
***粗斜体*** | 粗斜体 | 三星号包裹 |
~~删除线~~ | 双波浪线包裹 | |
==高亮== | ==高亮== | 双等号包裹（部分平台） |
`行内代码` | 行内代码 | 反引号包裹 |
这是 **粗体文字**，这是 *斜体文字*，这是 ***粗斜体文字***。
这是 ~~被删除的文字~~，这是 ==高亮文字==。
这是一段 `行内代码` 的例子。
下划线可以用 <u>HTML标签</u> 实现。
上标：X<sup>2</sup> + Y<sup>2</sup> = Z<sup>2</sup>
下标：H<sub>2</sub>O
2
3
4
5
6
7
8
9
10
11
转义字符：如果需要显示 * # ` 等特殊符号本身，在前面加反斜杠 \：
\* 这不是斜体 \*
\# 这不是标题
\` 这不是代码
\\ 这是反斜杠
2
3
4
完整转义字符列表：
| 符号 | 转义写法 | 说明 |
|---|---|---|
\* | \\* | 星号 |
\_ | \\_ | 下划线 |
\# | \\# | 井号 |
\` | \\` | 反引号 |
\~ | \\~ | 波浪号 |
\{ \} | \\{ \\} | 花括号 |
\[ \] | \\[ \\] | 方括号 |
\( \) | \\( \\) | 圆括号 |
\| | \\| | 竖线 |
# 2.3 段落与换行
Markdown 中，连续两个换行（即空一行）才会生成一个新段落。单个换行在大多数渲染器中不会产生 <br> 效果，除非末尾加两个空格。
这是第一段。
这是第二段（中间有空行）。
这是第三段，末尾加两个空格
这样就会换行了。
另一种换行方式是用 <br> HTML标签。
2
3
4
5
6
7
8
VuePress 提示：VuePress 默认开启 lineNumbers，单个换行也可能生效。建议统一用空行分段，保持可读性。
# 2.4 列表
# 无序列表
使用 -、* 或 + 作为标记：
- 项目一
- 项目二
- 子项目 2.1
- 子项目 2.2
- 孙子项目 2.2.1
- 项目三
2
3
4
5
6
# 有序列表
使用数字加 . 作为标记：
1. 第一步
2. 第二步
1. 子步骤 2.1
2. 子步骤 2.2
3. 第三步
2
3
4
5
注意：有序列表的数字不需要连续，Markdown 会自动递增。你甚至可以全部写成 1.：
1. 苹果
1. 香蕉
1. 橙子
2
3
渲染结果会显示为 1, 2, 3。
# 任务列表（GFM 扩展）
- [x] 已完成的待办事项
- [x] 学习 Markdown 基础
- [ ] 学习 Markdown 高级语法
- [ ] 完成项目文档
2
3
4
# 列表嵌套
列表中嵌套代码块或引用块时，需要在前面加 4 个空格 或 1 个 Tab：
1. 第一步说明
```python
print("这是嵌套的代码块")
```
2. 第二步说明
> 这是嵌套的引用块
3. 第三步说明
2
3
4
5
6
7
8
9
10
11
# 列表中的段落
如果列表项内需要多段内容，第二段开始需要缩进对齐：
- 第一项
这是第一项的第二段，前面缩进了两个空格。
- 第二项
2
3
4
5
# 2.5 链接
# 行内链接
[链接文字](URL)
[GitHub](https://github.com)
[编程进阶网](https://example.com "鼠标悬停提示文字")
2
3
# 引用式链接
适合长文档中多次引用同一个链接，方便统一管理：
这是一个指向 [GitHub][1] 的链接，这是另一个指向 [Google][2] 的链接。
[1]: https://github.com
[2]: https://www.google.com
2
3
4
# 自动链接
用尖括号包裹 URL 或邮箱：
<https://github.com>
<user@example.com>
2
# 锚点链接
链接到文档内部的标题：
[跳转到第二章](#二基础语法)
注意：中文标题的锚点会被 URL 编码，建议用英文标题或手动指定锚点。
# VuePress 扩展：目录页链接
[首页](/)
[关于页](/about/)
[某篇文章](/pages/xxxxx/)
2
3
# 2.6 图片
# 基本语法
2
# 引用式图片
![GitHub Logo][github-logo]
[github-logo]: https://github.githubassets.com/favicons/favicon.png
2
3
# 带链接的图片
[](点击跳转的URL)
# 图片尺寸控制
Markdown 原生不支持设置图片大小，需要通过 HTML 标签或平台扩展语法实现：
<!-- HTML方式 -->
<img src="image.png" width="300" height="200" alt="描述">
<!-- GFM / VuePress 方式 -->
2
3
4
5
# 图片对齐
<!-- 居中 -->
<div align="center">
<img src="image.png" alt="描述" />
</div>
<!-- 右对齐 -->
<div align="right">
<img src="image.png" alt="描述" />
</div>
2
3
4
5
6
7
8
9
# 2.7 代码
# 行内代码
用单个反引号包裹：
使用 `console.log()` 输出日志。
如果代码内包含反引号，用双反引号包裹：
`` 在代码中使用 ` 反引号 ``
# 代码块
用三个反引号（或三个波浪号）包裹，指定语言可以启用语法高亮：
```javascript
function greet(name) {
console.log(`Hello, ${name}!`);
}
greet('Markdown');
```
2
3
4
5
6
7
常见语言标识：
| 语言 | 标识符 | 语言 | 标识符 |
|---|---|---|---|
| JavaScript | js, javascript | Python | py, python |
| TypeScript | ts, typescript | Java | java |
| HTML | html | C | c |
| CSS | css | C++ | cpp, c++ |
| JSON | json | Go | go |
| YAML | yaml, yml | Rust | rust |
| Bash | bash, sh | SQL | sql |
| Markdown | md, markdown | Dockerfile | docker, dockerfile |
| Diff | diff | 纯文本 | text, 不填 |
# 行号与高亮
部分平台（如 VuePress）支持代码行号和行高亮：
```javascript{2,4-6}
function add(a, b) { // ← 第2行高亮
return a + b;
}
console.log(add(1, 2)); // ← 第4~6行高亮
console.log(add(3, 4));
console.log(add(5, 6));
```
2
3
4
5
6
7
8
# 2.8 引用
使用 > 创建引用块：
> 这是一段引用文字。
> 这是另一段引用，
> 可以跨多行。
2
3
4
# 嵌套引用
> 第一层引用
>> 第二层引用
>>> 第三层引用
2
3
# 引用中嵌套其他元素
> ### 引用中的标题
>
> - 列表项一
> - 列表项二
>
> ```python
> print("引用中的代码")
> ```
>
> > 引用中的引用
2
3
4
5
6
7
8
9
10
# 2.9 分隔线
一行中用三个或以上的 ---、*** 或 ___ 创建分隔线：
---
***
___
2
3
4
5
注意：--- 容易和 YAML frontmatter 的结束标记冲突，建议前后加空行。
# 2.10 表格
# 基本表格
| 左对齐 | 居中对齐 | 右对齐 |
| :----- | :------: | -----: |
| 内容1 | 内容2 | 内容3 |
| A | B | C |
2
3
4
渲染效果：
| 左对齐 | 居中对齐 | 右对齐 |
|---|---|---|
| 内容1 | 内容2 | 内容3 |
| A | B | C |
对齐方式：
:---或---→ 左对齐（默认）:---:→ 居中对齐---:→ 右对齐
# 表格中的特殊内容
| 功能 | 代码 | 说明 |
| :--- | :--- | :--- |
| 加粗 | `**文字**` | 表格中可以加粗 |
| 代码 | `` `code` `` | 表格中嵌套反引号需要转义 |
| 换行 | 第一行<br>第二行 | 使用 `<br>` 换行 |
| 竖线 | `\|` 或 `|` | 显示竖线符号 |
2
3
4
5
6
# 表格内容对齐的小技巧
在 IDE 中对齐表格的 | 能大幅提升可读性：
| 短 | 中等长度 | 非常非常长的列名 |
|:---|:--------|:-----------------|
| A | B | C |
2
3
# 2.11 注释
Markdown 原生不支持注释，但可以用 HTML 注释：
<!-- 这是注释，渲染时不可见 -->
这是一段文字。<!-- 行内注释 -->
2
3
