Markdown 语法手册
说明：Markdown 是一种轻量级标记语言，语法简洁、易上手，无需复杂排版操作，即可快速生成结构清晰、美观的文档，广泛应用于笔记、博客、接口文档、README等场景，兼容几乎所有主流编辑器（Typora、VS Code、Obsidian、GitHub等）。
一、基础语法
1. 标题
语法：使用 # 开头，# 数量对应标题层级（1-6级），# 与标题文本之间需加1个空格；建议1级标题（#）仅用1个（文档标题），避免层级混乱。
示例：
# 1级标题（文档主标题）
## 2级标题（一级小节）
### 3级标题（二级小节）
#### 4级标题
##### 5级标题
###### 6级标题（最低层级，不建议再往下）
效果：对应不同大小和权重的标题，层级分明，便于阅读和导航。
2. 段落与换行
2.1 段落
语法：直接输入文本，段落之间空1行即可区分（无需缩进，Markdown 忽略多余缩进）。
示例：
这是第一段文本，无需特殊标记，直接输入即可。
这是第二段文本，与第一段之间空1行，即为两个独立段落。
2.2 换行
语法：在需要换行的位置，输入 两个空格 + 回车（强制换行）；或使用 <br/> 标签（兼容所有编辑器）。
示例：
这是第一行文本 （此处两个空格）
这是第二行文本（强制换行，与上一行紧密衔接）
这是第三行文本<br/>这是第四行文本（用标签换行，效果同上）
3. 文本样式
常用3种样式：加粗、斜体、删除线，可单独使用，也可组合使用（如加粗+斜体）。
| 样式 | 语法 | 示例 | 效果 |
|---|---|---|---|
| 加粗 | 文本前后各加2个 * 或 _ | **加粗文本** 或 __加粗文本__ | 加粗文本 |
| 斜体 | 文本前后各加1个 * 或 _ | *斜体文本* 或 _斜体文本_ | 斜体文本 |
| 删除线 | 文本前后各加2个 ~ | ~~删除线文本~~ | 删除线文本 |
| 组合样式 | 混合使用标记 | ***加粗斜体***、**~~加粗删除线~~** | 加粗斜体、删除线加粗 |
4. 列表
4.1 无序列表
语法：使用 *、+ 或 - 开头，符号与文本之间加1个空格；可嵌套（嵌套时，子列表缩进2个空格或1个Tab）。
示例：
* 无序列表项1（用*开头）
* 无序列表项2
* 子列表项2-1（缩进2个空格）
* 子列表项2-2
+ 无序列表项3（用+开头）
- 无序列表项4（用-开头）
4.2 有序列表
语法：使用「数字 + .」开头，数字可任意（最终会自动按顺序排列），. 与文本之间加1个空格；支持嵌套（子列表用无序列表或有序列表均可）。
示例：
1. 有序列表项1
2. 有序列表项2
1. 子列表项2-1（缩进2个空格）
2. 子列表项2-2
3. 有序列表项3
# 注意：数字不连续也会自动修正
1. 列表项A
3. 列表项B（最终显示为2. 列表项B）
5. 引用
语法：使用 > 开头，> 与文本之间加1个空格；支持多级引用（多个 > 叠加），也可在引用内使用其他语法（列表、文本样式等）。
示例：
> 一级引用文本（常用）
> 引用内容可换行，每行开头都加> 即可
>> 二级引用（嵌套引用，两个>）
>> *引用内可加斜体*
>> 1. 引用内可加有序列表
>> 2. 列表项2
效果：
一级引用文本（常用）
引用内容可换行，每行开头都加> 即可二级引用（嵌套引用，两个>）
引用内可加斜体
1. 引用内可加有序列表
2. 列表项2
6. 代码块与行内代码
6.1 行内代码
语法：代码片段前后各加1个 ```（反引号，键盘左上角，Tab键上方），用于嵌入句子中的短代码。
示例：
在Markdown中，用`#` 表示标题，用`**文本**` 表示加粗，使用`print()` 函数可打印内容。
效果：在Markdown中，用# 表示标题，用**文本** 表示加粗，使用print() 函数可打印内容。
6.2 代码块
语法：使用「3个反引号 `````」开头和结尾，开头的反引号后可加上编程语言（如python、java、html），实现代码高亮；无需手动缩进，直接粘贴代码即可。
示例（Python代码）：
# 这是Python代码示例
def hello_world():
print("Hello, Markdown!")
hello_world()
效果：代码高亮显示，语法清晰，便于阅读（不同编辑器高亮风格略有差异）。
7. 链接
7.1 普通链接
语法：[链接显示文本](链接地址 "可选提示文本")；提示文本：鼠标悬停在链接上时显示的内容，可省略。
示例：
[GitHub官网](https://github.com "点击跳转至GitHub")
[Markdown官方文档](https://daringfireball.net/projects/markdown/)
效果：GitHub官网（鼠标悬停显示提示文本）。
7.2 锚点链接
语法：先给目标位置设置「锚点」（通常用标题），再通过链接指向锚点；锚点格式：#标题文本（需与目标标题完全一致，区分大小写）。
示例：
# 目录
1. [基础语法](#一、基础语法)
2. [进阶语法](#二、进阶语法)
## 一、基础语法（锚点目标，标题文本需完全匹配）
...（内容省略）
## 二、进阶语法（锚点目标）
...（内容省略）
效果：点击目录中的链接，可快速跳转至对应章节。
8. 图片
语法：在链接语法前加1个 !，格式：。
图片地址来源：
-
网络图片：直接粘贴图片URL（需确保图片可访问，不失效）；
-
本地图片：粘贴本地图片路径（相对路径/绝对路径），不同编辑器兼容性略有差异（Typora、Obsidian支持良好）；
-
文档内嵌入：部分编辑器（如Typora）支持直接拖拽图片，自动生成本地路径或Base64编码。
示例：
（相对路径，图片放在当前文档同级images文件夹下）
二、进阶语法
1. 表格
语法：使用 | 分隔列，- 分隔表头与表体；- 可加 : 控制列对齐（左对齐、居中、右对齐），无: 则默认左对齐。
示例（完整表格，含对齐）：
# 表格示例（对齐方式）
| 姓名 | 年龄 | 职业 |
| :--- | :---: | ---: | # 左对齐（:在左）、居中（:在两端）、右对齐（:在右）
| 张三 | 25 | 程序员 |
| 李四 | 28 | 产品经理 |
| 王五 | 30 | 设计师 |
注意：| 可不对称，但建议对齐，便于编辑；表头与表体之间的 - 至少1个，越多越清晰。
2. 分隔线
语法：单独一行，输入3个及以上 *、- 或 _，可加空格（不影响效果）；建议整篇文档统一分隔线样式。
示例：
这是上一部分内容
*** # 分隔线（3个*）
--- # 分隔线（3个-）
___ # 分隔线（3个_）
这是下一部分内容
3. 脚注
语法：正文标注脚注：文本[^脚注标识]；文档末尾添加脚注内容：[^脚注标识]: 脚注说明文本；脚注标识可自定义（数字、字母均可），需唯一。
示例：
Markdown 是一种轻量级标记语言[^1]，由约翰·格鲁伯（John Gruber）于2004年创建[^2]。
[^1]: 轻量级指语法简洁，无需复杂操作，易学习、易使用。
[^2]: 约翰·格鲁伯与亚伦·斯沃茨（Aaron Swartz）共同设计了Markdown语法。
效果：正文中标注脚注序号，点击序号可跳转至文档末尾查看脚注说明（不同编辑器显示样式略有差异）。
4. 任务列表
语法：使用 - [ ] 表示待办任务，- [x] 表示已办任务（x不区分大小写），[ ] 与文本之间加1个空格；支持嵌套。
示例：
- [x] 学习Markdown基础语法
- [x] 练习列表、表格语法
- [ ] 学习进阶语法（脚注、公式）
- [ ] 撰写一篇Markdown文档
- [ ] 确定文档主题
- [ ] 整理文档结构
效果：勾选框可直接点击切换待办/已办状态（支持的编辑器：Typora、Obsidian、GitHub等）。
5. 公式
Markdown 支持LaTeX语法的公式，分为「行内公式」和「块级公式」，需编辑器支持（Typora、VS Code、GitHub等均支持）。
5.1 行内公式
语法：公式前后各加1个 $，嵌入正文之中。
示例：
行内公式示例：勾股定理为 $a^2 + b^2 = c^2$，圆的面积公式为 $S = \pi r^2$。
5.2 块级公式
语法：公式前后各加2个 $，单独占一行，居中显示。
示例：
块级公式示例（二次函数求根公式）：
$$
x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a} \quad (a \neq 0)
$$
常用公式符号参考：\pi（π）、\sqrt{}（平方根）、\frac{分子}{分母}（分数）、\sum（求和）、\int（积分）。
三、实用技巧
1. 快速编辑技巧
-
标题快速升级/降级：选中标题文本，按
Ctrl + =升级标题，Ctrl + -降级标题（Typora、VS Code支持）； -
快速加粗/斜体：选中文本，按
Ctrl + B加粗，Ctrl + I斜体（大部分编辑器支持）； -
快速插入链接/图片：
Ctrl + K插入链接，Ctrl + Shift + I插入图片（Typora支持）； -
批量缩进：选中多行文本，按
Tab缩进，Shift + Tab取消缩进。
2. 避坑指南
-
标题不生效：
#与标题文本之间必须加1个空格，否则会显示为普通文本（如#标题不生效，# 标题生效）； -
换行不生效：仅按回车不会换行，需输入「两个空格 + 回车」或
<br/>； -
代码块不高亮：开头的3个反引号后，必须加上正确的编程语言（如 ````python`），否则仅显示普通代码块；
-
表格对齐混乱：表头与表体之间的
-不可省略，:需放在-的对应位置（左、中、右）； -
图片加载失败：网络图片URL失效、本地图片路径错误，或编辑器不支持本地图片嵌入（可改用网络图片或Base64编码）。
3. 兼容性说明
-
基础语法（标题、列表、链接等）兼容所有Markdown编辑器，无差异；
-
进阶语法（脚注、公式、任务列表）在部分简易编辑器（如记事本Markdown插件）中可能不生效，优先使用主流编辑器；
-
GitHub的Markdown有轻微差异（如表格对齐、代码高亮），但基本语法一致，可直接套用；
-
若需导出为PDF、Word，建议使用Typora编辑（导出功能完善，格式保留完好）。
四、常用场景模板
1. 笔记模板
# 笔记标题：XXX
## 一、笔记目的
- 记录XXX知识点
- 掌握XXX技能
## 二、核心内容
### 2.1 知识点1
- 关键信息1
- 关键信息2（**重点突出**）
### 2.2 知识点2
> 引用相关内容（可选）
`核心代码/公式`
## 三、总结与疑问
### 3.1 总结
...
### 3.2 疑问
- [ ] 疑问1
- [ ] 疑问2
2. README模板
# 项目名称：XXX
## 项目介绍
简述项目功能、用途，核心价值（1-2段即可）。
## 快速开始
### 1. 环境要求
- 语言：XXX（如Python 3.8+）
- 依赖：XXX（如MySQL 8.0、Redis 6.0）
### 2. 安装步骤
1. 克隆项目：`git clone https://github.com/xxx/xxx.git`
2. 安装依赖：`pip install -r requirements.txt`
3. 配置环境：修改config.py文件中的配置信息
4. 启动项目：`python main.py`
## 目录结构
```text
xxx/
├── config.py # 配置文件
├── main.py # 入口文件
├── requirements.txt # 依赖列表
└── README.md # 项目说明