这是ai写的一篇汇总，主要是用来测试的，顺便用来随时复习markdown啦

一、Markdown 是什么

Markdown 是一种轻量级标记语言，由 John Gruber 于 2004 年发布。核心理念：

  1. 易读易写：纯文本就能表达排版，不依赖 Word 那种”所见即所得”编辑器。
  2. 可转换：一份 .md 文件可以转换成 HTML、PDF、Word、幻灯片等几乎所有格式。
  3. 生态庞大：GitHub、GitLab、语雀、飞书、知乎、掘金、Typora、Obsidian、VS Code……到处都在用它。

简单说：你用记事本写，它给你排版；你用任何编辑器写，它都能渲染。

本手册遵循 GFM（GitHub Flavored Markdown） 标准，这是目前最主流的方言，兼容性最好。

二、基本语法

1. 标题

用 # 的个数表示级别，1~6 级：

1
2
3
4
5
6
# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题

规则与坑：

  • # 后面必须有一个空格，否则可能不识别（部分方言仍识别，但不规范）。
  • 标题下加 ===（一级）或 ---（二级）是 Setext 旧式写法，现在少用。
  • 分级要连续：别从一级直接跳三级，爬楼没有跳层的。

2. 段落与换行

1
2
3
这是第一段。

这是第二段（中间空一行才是新段落）。

关键坑——换行规则（本手册最值得背的一条）：

写法 效果
段落内直接回车 渲染为空格，不换行
行尾加两个空格再回车 硬换行（<br>）
行尾加反斜杠 \ 部分方言支持，等同于硬换行
空一行 新段落 
1
2
3
4
5
这是第一行
这是第二行（会被拼成一行）

这是第一行··（两个空格）
这是第二行（换行了）

3. 文字强调

1
2
3
4
5
*斜体* 或 _斜体_
**粗体** 或 __粗体__
***粗斜体***
~~删除线~~
==高亮==

渲染效果：斜体、粗体、粗斜体、删除线。

坑：

  • 中文语境下，_斜体_ 常与中文下划线冲突，统一用 *。
  • 强调符号与文字之间不能有空格：* 斜体 * 不生效。

4. 列表

无序列表（-、*、+ 均可）：

1
2
3
4
- 苹果
- 香蕉
  - 嵌套项（缩进两个或四个空格）
- 橙子

有序列表：

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

坑：

  • 有序列表的数字不要求连续，GFM 会自动重新编号——写 1、2、3 只是方便人看，渲染时从 1 开始。
  • 嵌套列表：子项缩进必须一致，否则会渲染错乱。
  • 列表项之间空行：部分方言会拆成多个 <li>，表格里容易出现多余间距。

任务列表（GFM 特有）：

1
2
- [ ] 待办事项
- [x] 已完成事项

渲染效果：

  • 待办事项
  • 已完成事项

5. 链接

行内式：

1
[文字](https://example.com "可选悬停标题")

参考式（正文干净，链接集中管理）：

1
2
3
[文字][引用名]

[引用名]: https://example.com "可选标题"

自动链接（< > 包裹 URL 或邮箱）：

1
2
<https://example.com>
<me@example.com>

相对链接（用于文档内部文件跳转）：

1
2
[跳转到另一篇](other.md)
[跳转到图片](../img/avatar.png)

6. 图片

1
![替代文字](图片URL "可选标题")
  • 与链接的唯一区别：前面多一个 !。
  • 替代文字必写：图片加载失败时显示它，也是无障碍访问的要求。

控制图片大小：标准 Markdown 不支持，需要 HTML（见进阶部分）。

7. 代码

行内代码：

1
用 `code` 包裹行内代码

围栏代码块（三个反引号 + 语言名）：

1
2
3
```python
print("Hello, Markdown")
```

坑：

  • 围栏语言名大小写敏感：Python 和 python 可能只有后者能高亮。
  • 代码块内想显示三个反引号，用四个反引号包裹外层。
  • 行内代码中的特殊字符无需转义。

缩进式代码块（旧式，每行缩进 4 个空格或 1 个 Tab）：

1
这是一段代码

8. 引用

1
2
3
4
> 这是引用
> 多行引用
>
> 引用里的空行也要带 >

嵌套引用：

1
2
> 第一层
>> 第二层

引用内可用其他语法：标题、列表、代码块都能塞进引用里。

9. 分隔线

三个及以上 -、* 或 _，独占一行：

1
2
3
---
***
___

坑： --- 上面如果紧跟文字且无空行，会被识别成二级标题而不是分隔线——这是高频翻车点。

10. 转义字符

反斜杠 \ 转义特殊字符：

1
2
3
4
\* 不是列表
\# 不是标题
\[ 不是链接
\\ 显示反斜杠本身

坑： 转义在代码块内不需要（代码块里一切都是字面量）。

三、GFM 扩展语法

GitHub Flavored Markdown 在标准语法之上增加的常用能力：

1. 表格

1
2
3
4
| 左对齐 | 居中 | 右对齐 |
| :--- | :---: | ---: |
| 内容 | 内容 | 内容 |
| 内容 | 内容 | 内容 |
左对齐 居中 右对齐
单元格 单元格 单元格
单元格 单元格 单元格

坑：

  • 表头分隔行必须有（--- 那行），否则整表不渲染。
  • 对齐冒号的位置：:--- 左、:---: 中、---: 右。
  • 单元格内要显示竖线 |，用 \| 转义。
  • 单元格内的换行用 <br>。
  • 分隔行中 --- 数量不限，但至少一个。

2. 任务列表

见基本语法的任务列表部分。GFM 的 - [x] / - [ ] 必须出现在列表项开头。

3. 删除线

1
~~这段文字被删了~~

4. 脚注

1
2
3
这句话需要注释[^1]。

[^1]: 注释内容写在文档任意位置。

渲染后点击上标数字即可跳转。

5. 自动链接

裸 URL 直接书写即自动转链接（部分方言需要 < > 包裹）：

1
直接写 https://example.com 就变成链接

6. 高亮标记

==文字== 高亮，Typora 等编辑器支持，GitHub 网页端不渲染（兼容性注意）。

四、进阶语法

1. 数学公式（LaTeX）

部分渲染器（Typora、Obsidian、GitHub 的 math 模式）支持 KaTeX / MathJax：

行内公式：

1
质能方程 $E = mc^2$

块级公式：

1
2
3
$$
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$

常用符号速记：

写法 渲染 写法 渲染
\frac{a}{b} 分数 \sqrt{x} 根号
\sum_{i=1}^{n} 求和 \alpha α
\leq ≤ \times ×
x^2 上标 x_2 下标

2. Mermaid 图表

Mermaid 是画流程图的 DSL，代码块语言写 mermaid：

1
2
3
4
5
6
```mermaid
flowchart LR
    A[开始] --> B{判断}
    B -->|是| C[执行]
    B -->|否| D[结束]
```
1
2
3
4
flowchart LR
    A[开始] --> B{判断}
    B -->|是| C[执行]
    B -->|否| D[结束]

支持类型：flowchart（流程图）、sequenceDiagram（时序图）、gantt（甘特图）、pie（饼图）、classDiagram（类图）等。

3. HTML 嵌入

Markdown 允许混写 HTML，用于标准语法做不到的事：

1
2
3
4
5
6
7
8
9
10
<kbd>Ctrl</kbd> + <kbd>C</kbd>

<img src="图片URL" width="200" alt="控制宽度">

<div align="center">居中内容</div>

<details>
<summary>点击展开</summary>
隐藏内容在这里
</details>

规则：

  • 块级 HTML 前后必须空行，且不能缩进。
  • HTML 标签内的 Markdown 语法不生效（如 <div>**粗体**</div> 中的 ** 不渲染）。

4. YAML Front Matter

部分工具（Jekyll、Hexo、Obsidian、Typora）用文件开头的 YAML 元数据：

1
2
3
4
5
6
7
---
title: Markdown 全知识手册
date: 2026-10-20
tags: [markdown, 教程]
categories: 文档
author: hshzspndd
---
  • 必须放在文件最开头，前后用 --- 包裹。
  • 两个 --- 之后必须紧跟换行，不能有其他字符。

5. Emoji

快捷码（GitHub 支持）：

1
:smile: :rocket: :fire:

直接粘贴 Unicode Emoji 也可：😄 🚀 🔥

6. 锚点跳转

文档内跳转：

1
[回到目录](#目录)
  • 锚点 = 标题文本小写化、空格转连字符、去掉标点。
  • 中文标题的锚点在 GitHub 上可用，在其他平台可能失效（兼容性坑）。

五、常见坑与兼容性

坑 表现 解法
--- 被识别为标题 分隔线变二级标题 上方留空行
换行不生效 两行拼成一行 行尾两空格 / 空行
* 与中文粘连 斜体不生效 符号与文字间不留空格，统一用 *
表格缺分隔行 整表不渲染 检查 `
列表缩进不一致 嵌套错乱 子项缩进统一
_ 用于斜体 中文下划线冲突 用 *
代码块内三个反引号 提前结束 外层用四个反引号
中文标点后换行 部分平台断句异常 使用中文全角标点 + 规范换行
同一个文件跨平台渲染不同 表格/脚注/高亮时有时无 以 GFM 为准，少用方言特性

兼容性分级速查：

  • 全平台通用：标题、列表、链接、图片、粗斜体、引用、分隔线、代码。
  • GFM 层（GitHub/掘金/知乎等支持）：表格、任务列表、删除线、围栏代码。
  • 编辑器私有（Typora/Obsidian 等）：脚注、高亮 ==、数学公式、Mermaid、Front Matter。

原则：公开分享用 GFM 能渲染的语法；自己笔记随便用方言。

六、工具与生态

工具 定位 亮点
Typora 所见即所得编辑器 实时渲染、导出 PDF/Word、主题丰富（收费）
VS Code 代码编辑器 插件 Markdown All in One、Markdown Preview Enhanced
Obsidian 双链笔记 双向链接、知识图谱、本地存储、插件生态
语雀 / 飞书 在线文档 云端协作、无需本地安装，支持 Markdown 粘贴转换
Hexo / Hugo / Jekyll 静态博客 写 .md → 生成静态站点 → 部署（你正在用的路线）
Pandoc 万能转换器 .md ⇄ PDF/Word/HTML/LaTeX，转换界的瑞士军刀
Jupyter Notebook 数据笔记 代码 + Markdown 混合

Pandoc 常用命令示例：

1
2
3
4
5
6
7
8
# Markdown 转 Word
pandoc input.md -o output.docx

# Markdown 转 PDF（需要 LaTeX）
pandoc input.md -o output.pdf

# 带目录转 HTML
pandoc input.md -o output.html --toc

七、最佳实践

  1. 标题层级从 1 级开始且连续，一篇文档不要出现多个一级标题（除了文档标题）。
  2. 段落之间空行，段落内不硬换行，交给渲染器自动折行。
  3. 列表与文字之间空行，避免列表粘连正文。
  4. 表格不要太宽：超过 6~8 列就该考虑拆表或换思路。
  5. 图片永远写替代文字，为自己的可访问性和后期维护负责。
  6. 长文档加目录，目录用锚点实现，或依赖渲染器自动生成 TOC。
  7. 代码块永远标注语言，否则没有高亮，等于白写。
  8. 引用的引用少嵌套，超过两层基本没人看得懂。
  9. 文件名用连字符而非空格：markdown-guide.md 优于 markdown guide.md。
  10. 写给别人看的，用 GFM 子集；写给自己看的，随便用。

八、一页速查表

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# 标题1            → 一级标题
## 标题2           → 二级标题
**粗体**           → 粗体
*斜体*             → 斜体
~~删除线~~         → 删除线
==高亮==           → 高亮（方言）
`code`             → 行内代码
```lang             → 围栏代码块（注明语言）
> 引用             → 引用块
---                → 分隔线（上方需空行）
[文字](url)        → 链接
![描述](url)       → 图片
- 项目             → 无序列表
1. 项目            → 有序列表
- [ ] 任务          → 未完成任务（GFM）
- [x] 任务          → 完成任务（GFM）
| a | b |          → 表格（表头下必须有 --- 行）
~~删~~             → 删除线
[^1] 与 [^1]:      → 脚注（方言）
$公式$ / $$公式$$   → 数学公式（方言）
:smile:            → Emoji 快捷码
\# 转义             → 转义特殊字符
<!-- 注释 -->       → HTML 注释，不渲染

结语

Markdown 的全部知识，本质就是三条：

  1. 符号即语义：#、*、-、>、反引号，每个符号都对应一个排版动作。
  2. 标准有方言：先掌握通用语法，再用 GFM，最后才碰编辑器私有特性。
  3. 纯文本是王道：任何编辑器都能写，任何系统都能读，永不失效。

现在，去把这篇手册变成你自己的第一篇真正的博客文章吧——总比留在 Hello World 里强。

（本手册由 Markdown 写成，全文 2000 余字，所有语法示例均可在支持 GFM 的编辑器中直接复制验证。）