Markdown 常用写法详解(从入门到进阶)
一篇尽量详细的 Markdown 速查:标题、强调、列表、链接图片、代码、表格、引用、任务列表、脚注、转义,以及 GFM 扩展与常见坑。写博客、文档、README 都够用。
Markdown 用纯文本写出排版,几乎所有技术写作场景(博客、README、文档、Issue、笔记)都在用。本文按”基础 → 进阶 → 扩展 → 坑”的顺序尽量讲全。每个语法都给源码和效果。
用 # 表示,几个 # 就是几级标题(共 6 级):
# 一级标题## 二级标题### 三级标题建议:一篇文章只有一个
#(通常等于文章标题),正文从##开始。
| 写法 | 效果 |
|---|---|
*斜体* 或 _斜体_ | 斜体 |
**粗体** | 粗体 |
***粗斜体*** | 粗斜体 |
~~删除线~~ |
无序列表用 -、* 或 +:
- 苹果- 香蕉 - 子项(缩进 2 空格)有序列表用数字加点:
1. 第一步2. 第二步3. 第三步小技巧:有序列表的数字不必写对,全写
1.也会自动递增。
[链接文字](https://example.com)[带标题的链接](https://example.com "悬停提示")
图片就是在链接前加 !。alt 文字对 SEO 和无障碍很重要,别省。
引用式链接(同一个 URL 多处用,集中管理):
这是 [我的博客][blog],也欢迎看 [GitHub][gh]。
[blog]: https://blog.890714.xyz[gh]: https://github.com行内代码用反引号包起来:`const x = 1` 渲染成 const x = 1。
代码块用三个反引号包裹,并在后面标注语言以高亮:
```jsfunction hello(name) { console.log(`Hi, ${name}`);}```想在文档里展示三反引号本身(像上面这样),就用四个反引号作为外层围栏。
用 >,可嵌套:
> 一级引用>> 二级引用>> 引用里也能放 **粗体**、列表、代码。| 左对齐 | 居中 | 右对齐 ||:---|:---:|---:|| a | b | c || 长内容 | 内容 | 1 |:---左对齐,:---:居中,---:右对齐。- 表格不需要对齐美观,渲染时会自动整理;但对齐了源码更好读。
- [x] 已完成- [ ] 待办- [ ] 另一个待办渲染成可勾选的复选框,写 TODO、清单很好用。
单独一行写三个及以上的 -、* 或 _:
---注意:
---写在正文里是分割线;写在文件最顶部则是 front matter 的边界(见下)。
- 段落:空一行隔开。
- 换行(同段内):行尾打两个空格再回车,或用
\(部分解析器支持)。 - 直接回车而不空行,多数解析器会当成同一行 —— 这是新手最常踩的”我明明换行了为啥没换”坑。
想显示 Markdown 符号本身,在前面加反斜杠 \:
\*这样不会变斜体\*\# 这样不会变标题可转义字符:\ ` * _ {} [] () # + - . ! |。
不同平台支持程度不同(GitHub、博客引擎、Obsidian 等),常见的有:
脚注:
这里有个脚注[^1]。
[^1]: 这是脚注内容,会显示在页面底部。折叠块(用 HTML):
<details><summary>点击展开</summary>
藏起来的内容,支持 Markdown。
</details>数学公式(KaTeX/MathJax,需引擎支持):
行内 $E = mc^2$,独立公式:
$$\int_0^1 x^2 \, dx = \frac{1}{3}$$Front Matter(博客元数据): 文件最顶部用 --- 包裹的 YAML,定义标题、日期、标签等。本文开头那段就是:
---title: "文章标题"pubDate: 2026-06-25tags: [Markdown, 写作]---内嵌 HTML: Markdown 允许直接写 HTML 标签,需要 Markdown 不支持的排版时(如 <kbd>Ctrl</kbd>、<br>)很方便。
| 现象 | 原因 / 解法 |
|---|---|
| 换行没生效 | 行尾加两个空格,或空一行分段 |
| 列表/引用没渲染 | 符号后要有一个空格(-item ❌,- item ✅) |
| 代码块语言没高亮 | 语言名拼错,或引擎未加载该语言 |
| 表格错乱 | 表头下必须有 ` |
# 没变标题 | # 后要空格(#标题 ❌,# 标题 ✅) |
| 下划线词被变斜体 | 如 my_var_name,用反引号包成代码或转义 \_ |
#标题、*强调、-列表、>引用、`代码、[]()链接、|表格。符号后基本都要跟空格,记住这一条能避开一半的坑。