Markdown 完全指南：语法速查与新手陷阱

开发者工具箱 · 使用教程

写技术文档、README、博客，绕不开 Markdown。它语法极少，几十分钟就能学会——但新手最常遇到的问题是：“我明明写的没问题，为什么渲染出来不对？” 这篇文章一边给语法速查，一边把那些坑说清楚。

一、Markdown 是什么

Markdown 是一门轻量标记语言，目标是让纯文本本身就好看、好读，同时能转换成 HTML。它由 John Gruber 在 2004 年设计，现在几乎所有技术写作场景都用它：GitHub README、技术博客、笔记软件、文档站。

核心优势一句话：不写 Markdown，你写的就是纯文本；写了 Markdown，纯文本也能读，转换后还好看。

代码块的写法：

```python
def hello():
    print("hi")
```

开头三个反引号后面可以跟语言名，用于语法高亮。不写也能用，只是没颜色。

#标题         ← 渲染不出来，被当成普通文字
# 标题        ← 正确

这是最高频的问题。几乎所有 Markdown 标记都要和内容之间留一个空格。

Markdown 的原则是“软换行”——你按一次回车，渲染出来还是在同一段里：

第一行
第二行        ← 渲染后是「第一行 第二行」，连在一起

第一行

第二行        ← 空一行才分段

想在段内强制换行，有两种办法：行尾加两个空格再回车，或者直接写 <br>。前者容易在编辑器里被自动删除，实践中后者更可靠。

这是文字
- 项目        ← 可能不渲染成列表，被当成普通文字

这是文字

- 项目        ← 正确，段落和列表之间空一行

变量名、文件名里含下划线时要小心：

my_var_name        ← 通常没事
my_var_name_x      ← 可能被解释成斜体，吃掉中间的字符
`my_var_name_x`    ← 用反引号包起来最安全

列表里的代码块、嵌套列表，对缩进要求严格。用空格不要用 Tab，同一个列表里缩进要保持一致（通常 2 或 4 个空格）。混用 Tab 和空格是玄学问题的常见来源。

Markdown 里可以直接写 HTML，多数渲染器都支持：

<br>                  强制换行
<details>...</details>  折叠块，适合 FAQ
<sub>下标</sub>

但要注意：HTML 块内部的 Markdown 通常不会被解析。也就是说，你在 <div> 里写 **加粗**，渲染出来就是字面的星号。需要加粗就写 <strong>。

转换全程在浏览器本地完成，草稿不会上传。

为什么同一个文档在不同平台渲染不一样？: 因为 Markdown 没有统一的标准实现。CommonMark 是较为公认的规范，但各家（GitHub、掘金、语雀、Typora）都有自己的方言扩展。表格、任务列表、脚注这些“常见功能”在原始 Markdown 里其实都不存在。
表格怎么对齐？: 在分隔行里用冒号控制。左对齐 :---，右对齐 ---:，居中 :---:。不写冒号默认左对齐。
怎么在 Markdown 里显示一个真正的星号？: 用反斜杠转义：\*。同理 \_、\` 都是转义。这在写包含这些符号的技术内容时经常要用。
有序列表的数字必须连续吗？: 不必。全写 1. 也可以，渲染器会自动编号。这在调整列表顺序时很方便——不用挨个改数字。
Markdown 能写数学公式吗？: 原始 Markdown 不行，但多数平台通过扩展支持 LaTeX 语法（用 $...$ 或 $$...$$）。能不能用、怎么用，取决于你用的那个渲染器，写之前最好先查平台文档。
该用 Markdown 还是直接写 HTML？: 内容为主就用 Markdown，需要精细控制样式再用 HTML。Markdown 的价值在于“写得快、读得清”，一旦你发现自己在 Markdown 里塞满 HTML 标签来实现排版，就该考虑换工具了。