Markdown 基础语法：附完整示例的速查指南

Markdown 基础语法是每一位开发者、写作者和内容创作者都需要熟练掌握的基本功。无论你是在写技术文档、撰写博客文章，还是在 GitHub 上提 Issue，这些核心语法元素都是你每天都会用到的构建模块。

这篇指南将带你逐一走过每个基础语法元素，配以清晰的示例、HTML 输出对照以及常见错误提示。建议收藏——你会比想象中更频繁地回来查阅。

标题

标题用于将内容组织成有逻辑的层级结构。Markdown 支持六个级别的标题，通过在文本前放置 # 符号来创建。

# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题

对应生成的 HTML 如下：

<h1>一级标题</h1>
<h2>二级标题</h2>
<h3>三级标题</h3>
<h4>四级标题</h4>
<h5>五级标题</h5>
<h6>六级标题</h6>

标题最佳实践

# 后面必须加空格。 没有空格的话，某些解析器不会将其识别为标题。

✅ ## 这样写才对
❌ ##这样写不行

按顺序使用标题级别。 不要从 H2 直接跳到 H4——这会破坏文档的逻辑大纲，同时影响无障碍访问和 SEO。把标题想象成目录：每一级都应该在上一级之下合理嵌套。

每页只用一个 H1。 H1 是你的页面主标题，其他内容都应使用 H2 及以下级别。

段落与换行

段落是 Markdown 中最简单的元素——直接写文字即可。用一个空行来分隔段落。

这是第一个段落。

这是第二个段落。

行内换行

这里是很多初学者容易踩坑的地方。在大多数 Markdown 渲染器中，按一次回车 并不会 产生新的一行。你需要：

1. 在行尾添加两个或更多空格（然后按回车）
2. 使用 <br> HTML 标签

这是第一行。
这是第二行。

或者使用 HTML：<br>
这样也能换行。

常见错误

在两行之间只按一次回车，在渲染后会被合并为同一段：

第一行
第二行

渲染结果是："第一行 第二行"——变成了一行。需要新段落时务必使用空行，需要同段换行时使用行尾空格。

文本格式

Markdown 让文本强调变得非常轻松。以下是核心格式选项：

粗体

用双星号或双下划线包裹文本：

**这是粗体文字**
__这也是粗体__

HTML 输出：<strong>这是粗体文字</strong>

斜体

用单星号或单下划线包裹文本：

*这是斜体文字*
_这也是斜体_

HTML 输出：<em>这是斜体文字</em>

粗斜体

用三个星号同时实现粗体和斜体：

***粗体加斜体***
___也是粗斜体___
**_或者混合使用_**

HTML 输出：<strong><em>粗体加斜体</em></strong>

删除线

使用双波浪号（这是 GFM 扩展，但几乎所有地方都支持）：

~~这段文字被划掉了~~

HTML 输出：<del>这段文字被划掉了</del>

常见错误

在单词 中间 使用下划线来强调并不总是有效。在需要词中强调时，请始终使用星号：

✅ 这是**非常**重要的
❌ 这是__非常__重要的

引用块

引用块通过 > 字符创建。常用于引用出处、突出重要提示或标注关键信息。

> Markdown 的目标是让阅读和书写尽可能地简单自然。
> — John Gruber

HTML 输出：

<blockquote>
  <p>Markdown 的目标是让阅读和书写尽可能地简单自然。
  — John Gruber</p>
</blockquote>

多段落引用

在段落之间的空行也加上 >：

> 引用的第一段。
>
> 引用的第二段。

嵌套引用

使用 >> 实现嵌套：

> 这是外层引用。
>
>> 这是嵌套在里面的引用。

引用块内混合其他元素

引用块可以和其他 Markdown 格式组合使用：

> ### 引用中的标题
>
> - 列表项一
> - 列表项二
>
> 包含 **粗体** 和 *斜体* 格式的文字。

列表

列表是 Markdown 中使用频率最高的元素之一。你会用到三种类型：无序列表、有序列表和任务清单。

无序列表

使用 -、* 或 + 作为标记。选定一种后保持一致：

- 第一项
- 第二项
- 第三项

HTML 输出：

<ul>
  <li>第一项</li>
  <li>第二项</li>
  <li>第三项</li>
</ul>

有序列表

使用数字加句点。实际的数字并不重要——Markdown 会自动编号：

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

有趣的是，下面这种写法也能得到相同结果：

1. 第一步
1. 第二步
1. 第三步

两者都会渲染为正确编号的 1-2-3 列表。不过，最佳实践是使用递增数字，这样源文件的可读性更好。

嵌套列表

缩进两个或四个空格来创建子列表：

1. 主项目
   - 子项 A
   - 子项 B
     - 子子项
2. 另一个主项目

任务清单

任务清单（GFM 特性）使用 - [ ] 表示未完成，- [x] 表示已完成：

- [x] 撰写初稿
- [x] 添加代码示例
- [ ] 校对文章
- [ ] 发布

常见错误

在段落后面紧跟列表但忘记加空行。某些解析器需要空行才能正确识别：

✅ 以下是我的列表：

- 第一项
- 第二项

❌ 以下是我的列表：
- 第一项
- 第二项

代码

展示代码是 Markdown 最强大的功能之一，正确使用至关重要。

行内代码

用单个反引号包裹代码以行内显示：

使用 `print()` 函数来输出文本。

HTML 输出：使用 <code>print()</code> 函数来输出文本。

如果代码本身包含反引号，使用双反引号：

``这里有一个 `反引号` 字面量。``

代码块

多行代码使用三个反引号（围栏式代码块），可选指定语言标识以启用语法高亮：

```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
```

语言标识（javascript、python、html、css、bash 等）可以在大多数渲染器中启用语法高亮。务必添加它——这能极大提升代码可读性。

缩进式代码块

你也可以通过给每行缩进四个空格或一个制表符来创建代码块：

    function add(a, b) {
      return a + b;
    }

但是，强烈推荐使用围栏式代码块，因为它支持语法高亮且不需要每行都缩进。

链接

链接是连接内容的关键。Markdown 支持多种链接格式。

行内链接

最常用的格式——文字放在方括号中，URL 放在圆括号中：

[访问示例网站](https://example.com)

HTML 输出：<a href="https://example.com">访问示例网站</a>

带标题的链接

在 URL 后面加引号内的标题（鼠标悬停时显示为提示）：

[访问示例网站](https://example.com "示例网站")

引用式链接

当文档中有大量链接时，引用式链接可以让源文本更整洁：

我每天使用 [Google][1] 和 [GitHub][2]。

[1]: https://google.com "Google"
[2]: https://github.com "GitHub"

这样可以保持段落的简洁，将所有 URL 集中在底部——在长文档中特别实用。

自动链接

用尖括号包裹 URL 或邮箱地址来自动创建链接：

<https://example.com>
<contact@example.com>

大多数现代渲染器（如 GitHub）也会自动识别裸 URL，但使用尖括号可以确保兼容性。

常见错误

忘记 URL 中的空格需要编码。空格应使用 %20：

✅ [我的文档](files/my%20document.pdf)
❌ [我的文档](files/my document.pdf)

图片

图片的语法与链接相同，只是前面多了一个感叹号 !：

![描述图片的替代文本](/path/to/image.webp)

HTML 输出：<img src="/path/to/image.webp" alt="描述图片的替代文本">

带标题的图片

![海上日落](/images/sunset.webp "美丽的日落")

可点击的图片

将链接语法和图片语法结合，让图片可以点击跳转：

[![替代文本](/images/photo.webp)](https://example.com)

Alt 文本最佳实践

始终编写描述性的 alt 文本。 它有两个关键作用：

1. 无障碍访问——屏幕阅读器使用它向视障用户描述图片内容
2. SEO 优化——搜索引擎使用它来理解图片内容

✅ ![展示标题、列表和链接的 Markdown 语法速查表](/images/cheatsheet.webp)
❌ ![图片](/images/cheatsheet.webp)
❌ ![](/images/cheatsheet.webp)

水平分隔线

使用三个或更多的短横线、星号或下划线来创建水平线（主题分隔符）：

---
***
___

三者生成的 HTML 相同：<hr>

最佳实践： 统一使用 ---，并且前后都留空行：

上方的内容。

---

下方的内容。

转义字符

如果你想显示字面意义上的星号或井号，而不想触发 Markdown 格式化怎么办？在字符前使用反斜杠 \：

\* 这不是斜体 \*
\# 这不是标题
\- 这不是列表项

以下是所有可以转义的字符列表：

\   反斜杠
`   反引号
*   星号
_   下划线
{}  花括号
[]  方括号
()  圆括号
#   井号
+   加号
-   短横线
.   句点
!   感叹号
|   管道符

语法速查表

以下是所有基础语法元素的速查对照表：

Element         Syntax              HTML
--------------  ------------------  -----------
Heading 1       # text              <h1>
Heading 2       ## text             <h2>
Heading 3       ### text            <h3>
Bold            **text**            <strong>
Italic          *text*              <em>
Bold + Italic   ***text***          <strong><em>
Strikethrough   ~~text~~            <del>
Blockquote      > text              <blockquote>
Ordered list    1. item             <ol><li>
Unordered list  - item              <ul><li>
Inline code     `code`              <code>
Link            [text](url)         <a href>
Image           ![alt](src)         <img>
Horizontal rule ---                 <hr>
Line break      spaces + Enter      <br>

开始实践吧

现在你已经学会了每个 Markdown 基础语法元素，是时候动手实践了。以下是建议的下一步：

1. 练习写作：创建一个 notes.md 文件，尝试每一种语法元素。写得越多，用起来就越自然。

2. 使用预览工具：VS Code 内置的 Markdown 预览功能（Ctrl+Shift+V / Cmd+Shift+V）可以在你打字的同时实时显示渲染效果。

3. 转换与分享：当你的 Markdown 文档准备好面对读者时，将它转化为精美的输出——将 Markdown 转换为 HTML 用于网页发布，生成 PDF 用于打印就绪的文档，或导出为 Word 用于协作编辑。

4. 深入探索：当你熟练掌握基础语法后，可以深入了解我们的 Markdown 扩展语法指南，学习表格、脚注、定义列表等更多高级功能。刚接触 Markdown？从什么是 Markdown 获取全局概览。

Markdown 基础语法的美妙之处在于，这些元素已经覆盖了你日常写作绝大多数的需求。掌握一次，受用终身——从 GitHub 到 Notion，从技术文档到你正在阅读的这篇博客。