Markdown 语法速查
Markdown 的全部语法其实很少，难的是那些「写了但不生效」的坑。 这一页按「源码 → 效果 → 说明」对照着排，左边是你该敲的字，中间是渲染出来的样子， 右边是要注意的地方。基础、进阶、GitHub 专属、中文排版、常见坑、可直接抄的模板， 一页到底。
基础语法
学会这十几个，日常写笔记和文档就够了。
# 一级标题
# 和文字之间必须有空格，#标题 不生效。最多 6 级。
## 二级标题 ### 三级标题
别跳级：h2 下面直接跟 h4，导出或生成目录时会乱。
**粗体**
也可以用 __粗体__，但下划线形式在中文里容易出问题，建议统一用星号。
*斜体*
同上，_斜体_ 可用但不如星号稳。
~~删除线~~
这是 GFM（GitHub 风格）扩展，极简解析器可能不支持。
- 项目一 - 项目二
符号可用 -、*、+，同一份文档里建议统一。
1. 第一步 2. 第二步
数字写错也没关系，渲染时会按顺序自动编号 —— 但源码最好写对，便于阅读。
> 引用的文字
可以嵌套（>>），引用里也能放列表、代码块。
[链接文字](https://example.com)
圆括号里是地址，网址里带括号时要用尖括号包起来。
前面多个感叹号。方括号里是替代文字（图挂了会显示，也影响 SEO）。
`行内代码`
行内代码内容里本身有反引号时，用两个反引号包裹。
```js const a = 1; ```
三个反引号开头，紧跟语言名（js / python / bash）才能高亮。
---
单独一行写三个减号，前后都要空行，否则会把上一行变成二级标题。
| 表头 | 表头 | | --- | --- | | 内容 | 内容 |
第二行是分隔行，控制对齐（:--- 左、:---: 居中、---: 右）。表格前要空一行。
- [x] 已完成 - [ ] 未完成
任务列表，在 GitHub 上可以直接点。中括号里打 x 表示已完成。
进阶语法
写长文、技术文档、论文时会用到。注意：这部分依赖解析器支持，不是所有地方都能渲染。
这里是正文[^1] [^1]: 底部的注释
脚注：正文标引用，文末给定义，渲染时会自动跳到页面底部。
[链接文字][ref] [ref]: https://example.com
引用式链接：地址集中放文末，正文里保持干净，同一地址多处复用。
$E = mc^2$
数学公式。行内用单个美元符，独立成行用两个。需要 KaTeX / MathJax 才能渲染，GitHub 已内置支持。
<details> <summary>点开看答案</summary> 藏在里面的内容 </details>
折叠块：必须用 HTML 写，<summary> 后面要空一行，否则内容不渲染。
\*这不是斜体\*
转义：在符号前加反斜杠，让它按字面显示。
[跳到附录](#附录)
页内锚点：括号里是 # 加标题文字。中文标题一般也能跳，但不同解析器规则不完全一致。
<!-- 这是注释 -->
注释：写给自己或协作者的提醒，最终页面里不显示。
GitHub 专属（GFM）
这些在别的编辑器里可能不生效，但在 GitHub 的 README、Issue、PR 里都好用。
> [!NOTE] > 有用的补充说明
GitHub 警告框，五种：NOTE / TIP / IMPORTANT / WARNING / CAUTION。首字母大写、方括号包住、必须写在引用里。
```js {2-3}在语言名后加花括号，可以高亮指定行，讲代码变化时很直观。
```mermaid graph TD; A-->B; ```
代码块语言写 mermaid，平台会渲染成流程图 —— 这也是本站图表类目里最值得学的一个。
@someone 看下 #123
GitHub 专属：@ 提及会通知对方，# 加编号自动变成 issue / PR 链接。
:smile: :rocket:
emoji 短代码，两端的冒号不能省。各平台支持的名单不完全一样。
```diff + 新增的一行 - 删掉的一行 ```
diff 代码块会自动标出增删，写变更说明时很好用。
中文排版的几条习惯
语法之外的事 —— 决定了你的文档「看起来专不专业」。
在 Markdown 里写中文
中英文之间加空格，读起来呼吸感更好。这是中文排版最基本的习惯。
总共 100 个工具
中文与数字之间也加空格。
文件 50 MB，占 30%
数字与单位之间加空格，但 % 和 °C 是例外，不加。
他说：「这样就好。」
中文用全角标点（，。：；！？「」），英文和代码用半角，不要混用。
# 怎么写好一篇笔记
标题结尾不加句号 —— 大部分排版规范都不加。
常见坑
排版的语法对了、内容也没问题，但显示出来就是不对劲 —— 八成是下面这几条之一。
回车不等于换行
Markdown 里写完一行直接回车，渲染出来还是在同一段里。要分段就空一行；只想换行不断段，就在行尾打两个空格再回车。这是新手最常卡的地方。
# 后面必须有空格
#标题 不生效，# 标题 才是标题。 顺带一提：#标签这种写法在社交平台常见，在 Markdown 里不是标题。
列表缩进要一致
嵌套列表用 2 个或 4 个空格，同一份文档里只用一种。 混着写会出现「子项跑到外面去」或者列表被拆成两段。
表格里竖线要转义
单元格内容里本身有竖线时，写成 \|，否则会被当成新的列。
代码块里出现三个反引号
内容本身含三个反引号时，外面改用四个反引号包裹， 或者整体缩进 4 个空格。
变量名里的下划线被吃掉
some_var_name 在某些解析器里会被当成斜体。稳妥做法是把变量包进行内代码，或者把斜体统一改用星号。
照抄就能用的模板
两个最高频的场景，结构已经排好了，把内容换掉即可。
项目 README 骨架
开源项目最常用的结构：一句话说清是什么、能做什么、怎么开始用。
# 项目名
一句话说明这个项目解决什么问题。
## 特性
- 特性一
- 特性二
## 快速开始
```bash
npx 项目名 --help
```
## 用法
```js
import { something } from "项目名";
```
## 许可证
MIT笔记模板（带元信息）
顶部用 front-matter 记录标题、日期、标签，几乎所有笔记工具和静态站都认这个格式。
--- title: 笔记标题 date: 2026-09-10 tags: [读书, 普洱] --- ## 一句话结论 先写结论，再展开。 ## 要点 - 要点一 - 要点二 ## 参考 - [来源](https://example.com)