一、基础语法速查表

1.1 标题

语法	渲染效果	说明
# 一级标题	最大标题	通常用于文档标题
## 二级标题	次大标题	章节标题
### 三级标题	中等标题	小节标题
#### 四级标题	较小标题	子节标题
##### 五级标题	很小标题	很少使用
###### 六级标题	最小标题	极少使用

注意：# 与文字之间保留一个空格，部分编辑器不认无空格的写法。

1.2 文本样式

语法	渲染效果
**粗体**	粗体
*斜体*	斜体
***粗斜体***	粗斜体
~~删除线~~	删除线
`行内代码`	行内代码
<u>下划线</u>	下划线（HTML 扩展）
==高亮==	高亮（部分编辑器支持）

1.3 列表

- 无序列表项 1
- 无序列表项 2
  - 嵌套子项（缩进 2 空格）
    - 再嵌套一层

1. 有序列表项 1
2. 有序列表项 2
   1. 嵌套有序子项

- [ ] 待办任务（未完成）
- [x] 已完成任务

1.4 链接与图片

语法	说明
[链接文字](https://example.com)	行内链接
[链接文字][ref_id]	引用式链接
	行内图片
[](url)	可点击的图片链接
<https://example.com>	自动链接（URL 直接显示）

1.5 代码块

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

支持语言高亮标签：python、javascript、bash、json、html、css、sql、yaml、markdown 等。

1.6 表格

| 列A | 列B | 列C |
|-----|-----|-----|
| 内容 | 内容 | 内容 |

• 对齐方式：:--- 左对齐，:---: 居中，---: 右对齐。
• 管道符两侧空格不影响渲染，但保持统一风格更美观。

1.7 引用与分割线

> 一级引用
>> 二级嵌套引用
>>> 三级嵌套引用

---  或者  ***  或者  ___

1.8 其他常用

语法	效果
[^1] + [^1]: 脚注内容	脚注引用
- [ ] 未完成	任务列表
<!-- 注释 -->	HTML 注释（渲染时隐藏）
$\LaTeX$ 或 $$公式$$	数学公式（需渲染器支持）

---

二、进阶技巧

2.1 表格内换行与特殊字符

表格单元格内需要换行时，使用 <br> 标签：

| 列A | 列B |
|-----|-----|
| 第一行<br>第二行 | 内容 |

表格内需要显示 | 时，使用 | 或 \|（部分编辑器）。推荐 | 兼容性最佳。

2.2 代码块内嵌套反引号

需要在代码块内展示三个反引号时，外层使用四个反引号包裹：

````markdown
```python
print("hello")
```
````

2.3 转义反引号用于行内代码

如果行内代码内容本身包含反引号，使用两个反引号包裹：

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

2.4 折叠区块（细节摘要）

使用 HTML 的 <details> 标签实现可折叠内容块：

<details>
<summary>点击展开详情</summary>

这里是折叠的内容，可以包含任意 Markdown 元素。

- 列表项
- **粗体文字**
</details>

2.5 跳转到文档内锚点

[跳转到第二节](#二进阶技巧)

• 锚点名 = 标题文字转小写 + 空格换 - + 去掉标点符号。
• 中文标题的锚点各平台实现不一致，建议用 HTML 锚点：<a id="anchor"></a>。

2.6 多级任务列表缩进

- [ ] 一级任务
  - [x] 二级已完成
    - [ ] 三级待办

2.7 自定义容器（Callout / Admonition）

部分平台支持（GitHub、Obsidian、Typora 等），语法各有差异。GitHub 示例：

> [!NOTE]
> 这是一条注释信息。

> [!WARNING]
> 这是一个警告。

> [!TIP]
> 这是一个提示。

2.8 Mermaid 流程图与图表

```mermaid
graph TD
    A[开始] --> B{判断}
    B -->|是| C[执行]
    B -->|否| D[结束]
```

支持的图表类型：流程图 graph、时序图 sequenceDiagram、甘特图 gantt、类图 classDiagram 等。

2.9 表格内嵌代码块/列表

表格中不能直接嵌入多行代码块，但可以使用 <pre> 标签或单行反引号：

| 功能 | 示例 |
|------|------|
| 行内代码 | `print("hello")` |
| 多行 | <pre>line1<br>line2</pre> |

---

三、高效编辑习惯

3.1 语义化空行

• 标题前后各留一个空行，提升源码可读性。
• 列表与正文之间用空行分隔。
• 代码块前后各留一个空行。

## 标题

正文内容。

- 列表项 1
- 列表项 2

```python
print("hello")

继续正文。

### 3.2 表格源码对齐

手动对齐管道符让源码更易维护：

```markdown
| 名称   | 类型   | 说明         |
|--------|--------|--------------|
| name   | string | 用户名称     |
| age    | int    | 用户年龄     |
| email  | string | 电子邮箱     |

快捷技巧：VS Code 中选中表格后按 Shift + Alt + F 可自动格式化。

3.3 统一缩进规范

• 嵌套列表统一使用 2 个空格或 4 个空格缩进，全文保持一致。
• 不建议混用 Tab 和空格，推荐空格优先。

3.4 引用式链接管理长文档

大量外部链接时，将 URL 集中放置文末：

正文中引用：[Google][g] 和 [GitHub][gh]。

[g]: https://www.google.com
[gh]: https://github.com

3.5 使用目录（TOC）快速导航

多数平台支持自动生成目录：

<!-- TOC -->
- [一、基础语法速查表](#一基础语法速查表)
- [二、进阶技巧](#二进阶技巧)
- [三、高效编辑习惯](#三高效编辑习惯)
- [四、常见坑](#四常见坑)
<!-- /TOC -->

部分编辑器如 Typora 输入 [TOC] 后回车即可自动生成。

3.6 快捷键速记（VS Code / Typora 通用参考）

快捷键	功能
Ctrl + B	加粗
Ctrl + I	斜体
Ctrl + K	插入链接
Ctrl + Shift + K	删除线（部分编辑器）
Ctrl + Shift + `` ``	行内代码
Ctrl + Shift + [ / ]	调整标题级别

---

四、常见坑

4.1 标题 # 后忘加空格

#这样写        ← 错误：部分解析器不识别
# 这样写       ← 正确

4.2 列表嵌套缩进不足

- 父级
- 子级        ← 错误：与父级同级
  - 子级      ← 正确：至少缩进 2 空格

4.3 列表中间插入代码块缩进不对

代码块必须与列表项文字对齐（额外缩进），否则会打断列表：

1. 第一步

    ```bash
    echo "hello"
    ```

2. 第二步    ← 序号会重新开始计数，若代码块未正确缩进

正确做法：代码块前缩进与列表内容对齐。

4.4 表格的管道符对齐问题

部分编辑器（如 GitHub）要求表头分隔行至少三个连字符 ---，否则不识别为表格：

| A | B |
|-|-|       ← 可能不识别
|---|---|    ← 正确

4.5 列表符号与数字的误触发

以数字 + 点号 + 空格开头的行会被自动识别为有序列表。不想被识别时，在点号前加反斜杠转义：

2024\. 今年不开启列表

4.6 多个空行会被压缩

连续两个以上空行在渲染时通常会被压缩为一个空行（单一段落间距）。如需更大间距，使用 <br> 或 HTML 空块。

4.7 HTML 标签内的 Markdown 失效

在 HTML 块级标签（如 <div>、<table>）内部，Markdown 语法通常不会被解析。如需混合使用，在标签上添加 markdown=1 属性（仅部分实现支持），或尽量将 Markdown 内容放在 HTML 标签之外。

4.8 数学公式渲染不一致

不同平台对 LaTeX 公式的支持程度不同：

• $...$：行内公式（GitHub 不支持，Typora/Notion 支持）
• $$...$$：块级公式（多数平台支持）

建议为跨平台兼容，关键公式用图片替代或注明可能渲染失败。

4.9 中文与英文/数字间空格

为提升源码可读性，建议中文与英文单词、数字之间手动加空格：

本文介绍 Markdown 的 5 个常用技巧。

此条并非语法要求，而是社区推荐的最佳实践，有助于提高纯文本可读性。