Markdown 语法全面解析：从入门到精通

在信息爆炸的时代，清晰、高效地书写和格式化文档变得至关重要。Markdown 应运而生，它是一种轻量级标记语言，由 John Gruber 和 Aaron Swartz 创建。其设计理念是让人们能够使用易于阅读、易于编写的纯文本格式来编写文档，然后可以转换成结构有效的 XHTML（或 HTML）。

简单来说，Markdown 让你在写作时无需频繁使用鼠标点击复杂的工具栏，只需在文本中插入一些简单的符号（如 #、*、- 等），就能实现标题、列表、加粗、链接等丰富的排版效果。它广泛应用于博客、文档、README、论坛帖子以及即时消息中。本文将作为一份详尽的指南，带你系统掌握 Markdown 的核心语法与最佳实践。

目录#

  1. 标题
  2. 段落与换行
  3. 文本强调
  4. 列表
  5. 链接与图片
  6. 代码
  7. 引用
  8. 分割线
  9. 表格
  10. 高级元素
  11. 最佳实践与常见问题
  12. 总结
  13. 参考与扩展

标题#

标题是组织内容结构的关键。在 Markdown 中，有两种方式创建标题。

方法一：使用 # (Atx 风格)#

在行首放置 1 到 6 个 # 字符，对应 HTML 的 <h1> 到 <h6> 标题。# 后面最好跟一个空格。

语法示例：

# 这是一级标题 (H1)
## 这是二级标题 (H2)
### 这是三级标题 (H3)
#### 这是四级标题 (H4)
##### 这是五级标题 (H5)
###### 这是六级标题 (H6)

方法二：使用下划线 (Setext 风格) - 仅支持两级#

对于一级和二级标题，可以使用下划线符号。这种方式现在较少使用。

语法示例：

这是一级标题
=============
 
这是二级标题
-------------

最佳实践：

  • 推荐使用 # 方法，因为它更清晰，并且支持所有六级标题。
  • 在 # 和标题文字之间留一个空格，这是公认的规范。
  • 确保文档中只有一个一级标题（H1），这通常被视为文档的标题。

段落与换行#

段落： 创建一个段落非常简单，只需用一个或多个空行将文本分隔开。在 Markdown 中，连续的同一行文本会被视为一个段落。

换行： 在 Markdown 中，仅仅在行末按回车（换行）不会在最终输出中产生新行。要强制换行，有两种方法：

  1. 在两个空格后按回车。这是最标准的方法。
  2. 在行末使用一个反斜杠 \。（某些解析器支持）

示例：

这是第一个段落。这里虽然换行了，但在渲染后还是同一行。
 
这是第二个段落，因为上面有一个空行。
 
这是第三段的第一行，后面有两个空格（你看不见）  
这样就会强制换到新的一行。

渲染效果：

这是第一个段落。这里虽然换行了，但在渲染后还是同一行。

这是第二个段落，因为上面有一个空行。

这是第三段的第一行，后面有两个空格（你看不见） 这样就会强制换到新的一行。

文本强调#

你可以使用星号 * 或下划线 _ 来表示强调。

  • 加粗（粗体）： 用两个 * 或 _ 包裹文字。
    • **这是加粗文字** 或 __这是加粗文字__ → 这是加粗文字
  • 斜体： 用一个 * 或 _ 包裹文字。
    • *这是斜体文字* 或 _这是斜体文字_ → 这是斜体文字
  • 加粗并斜体： 用三个 * 或 _ 包裹文字。
    • ***这是加粗斜体*** 或 ___这是加粗斜体___ → 这是加粗斜体

最佳实践：

  • 为了清晰和一致性，推荐统一使用星号 *。

列表#

无序列表#

使用 -、* 或 + 作为列表标记，后面跟上空格。

示例：

-   项目一
-   项目二
    -   嵌套项目二点一
    -   嵌套项目二点二
-   项目三

渲染效果：

  • 项目一
  • 项目二
    • 嵌套项目二点一
    • 嵌套项目二点二
  • 项目三

有序列表#

使用数字接着一个英文句点，然后跟一个空格。

关键点： 数字本身并不重要，最终渲染结果总是会从 1 开始顺序编号。这让你可以方便地重新排序列表项。

示例：

1.  第一项
2.  第二项
    1.  嵌套有序项一
    2.  嵌套有序项二
3.  第三项

渲染效果：

  1. 第一项
  2. 第二项
    1. 嵌套有序项一
    2. 嵌套有序项二
  3. 第三项

任务列表#

这是 GitHub Flavored Markdown (GFM) 等扩展语法中的功能。用于创建带有复选框的列表。

语法： 在无序列表的标记后使用 [ ] 表示未完成，[x] 表示已完成。

示例：

- [x] 完成博客大纲
- [x] 撰写引言部分
- [ ] 添加代码示例
- [ ] 校对全文

渲染效果：

  • 完成博客大纲
  • 撰写引言部分
  • 添加代码示例
  • 校对全文

链接与图片#

链接#

创建链接的语法是：[链接文本](链接地址 "可选的标题")。

  • 链接文本： 显示的可点击文字。
  • 链接地址： 可以是 URL 或本地文件路径。
  • 可选的标题： 当鼠标悬停在链接上时显示的提示文字，用引号包裹。

示例：

这是一个 [百度](https://www.baidu.com) 的链接。
这是一个带标题的 [谷歌](https://www.google.com "全球搜索引擎") 链接。

渲染效果： 这是一个 百度 的链接。 这是一个带标题的 谷歌 的链接。

引用式链接： 为了保持行内整洁，可以将链接地址定义在文档末尾。

这是一个引用式链接到 [Markdown 官网][1] 和 [Google][2]。
 
[1]: https://daringfireball.net/projects/markdown/
[2]: https://www.google.com

图片#

插入图片的语法与链接类似，只是在前面加一个感叹号 !：![替代文本](图片地址 "可选的标题")。

  • 替代文本： 如果图片无法加载，将显示此文字。对无障碍访问至关重要。
  • 图片地址： 可以是网络 URL 或本地相对/绝对路径。
  • 可选的标题： 鼠标悬停时显示的提示文字。

示例：

![Markdown 标志](https://example.com/markdown-logo.png "Markdown Logo")

代码#

行内代码#

用一个反引号 ` 将代码包裹起来，用于在段落中标记小段代码或命令。

示例：

在 Python 中，可以使用 `print("Hello, World!")` 函数来输出文本。
请运行 `npm install` 命令来安装依赖。

渲染效果： 在 Python 中，可以使用 print("Hello, World!") 函数来输出文本。

代码块#

要创建多行代码块（预格式化文本），有两种方式：

  1. 缩进四个空格或一个制表符（原始标准）。

        这是一个代码块。
    它保留了所有的空格和换行。
    function hello() {
      console.log("Hello!");
    }

  2. 使用三个反引号 `````（围栏式代码块，更常用，是 GFM 等扩展的一部分）。这是强烈推荐的做法，因为它支持语法高亮。

    • 在代码块的开头和结尾各放一行三个反引号。
    • 可以在开始的反引号后指定语言名称，以实现语法高亮。

示例（带语法高亮）：

```python
def greet(name):
    """一个简单的问候函数"""
    print(f"Hello, {name}!")
 
greet("World")
```
 
```javascript
// JavaScript 代码示例
const add = (a, b) => a + b;
console.log(add(2, 3));
```

渲染效果（取决于你的 Markdown 查看器）：

def greet(name):
    """一个简单的问候函数"""
    print(f"Hello, {name}!")
 
greet("World")

引用#

使用 > 符号来表示引用块。可以嵌套使用。

示例：

> 这是一个一级引用块。
> 这是同一引用的第二行。
>
> > 这是一个嵌套的引用块。
>
> - 引用块中甚至可以包含列表。
> - 就像这样。

渲染效果：

这是一个一级引用块。 这是同一引用的第二行。

这是一个嵌套的引用块。

  • 引用块中甚至可以包含列表。
  • 就像这样。

分割线#

你可以使用三个或更多的连字符 ---、星号 *** 或下划线 ___ 来创建一条水平分割线。行内不能有其他内容。

示例：

上面是内容
 
---
 
下面是其他内容

最佳实践：

  • 为了清晰，推荐使用 ---。

表格#

表格是 GFM 等扩展语法中的功能。使用连字符 - 来分隔表头，使用管道符 | 来分隔列。

语法：

| 左对齐 | 居中对齐 | 右对齐 |
| :----- | :------: | -----: |
| 单元格 |  单元格  | 单元格 |
| 内容   |   内容   |   100  |
  • :--- 表示左对齐
  • :--: 表示居中对齐
  • ---: 表示右对齐

渲染效果：

左对齐居中对齐右对齐
单元格单元格单元格
内容内容100

高级元素#

脚注#

用于添加注释。

示例：

这是一个带有脚注的句子[^1]。这是另一个脚注[^2]。
 
[^1]: 这是第一个脚注的详细解释。
[^2]: 这是第二个脚注的内容。

定义列表#

示例：

Markdown
: 一种轻量级标记语言。
 
HTML
: 超文本标记语言。

删除线#

使用两个波浪号 ~~ 包裹文字。

示例：

原价：~~100元~~ 现价：80元。

渲染效果： 原价：100元 现价：80元。

表情符号#

在 GFM（如 GitHub、GitLab）中，可以直接使用表情符号的短代码。

示例：

:+1: :sparkles: :tada:

渲染效果： :+1: :sparkles: :tada:

最佳实践与常见问题#

  1. 兼容性： 本文涵盖了 CommonMark 和 GFM 等主流标准。但请注意，不同平台（如 GitHub, GitLab, 语雀, 知乎）的 Markdown 解析器可能有细微差别或特有扩展。在特定平台写作时，请查阅其文档。
  2. 转义特殊字符： 如果你想显示原本用于 Markdown 格式的字符（如 *、#），可以在它前面加上反斜杠 \ 进行转义。例如：\*这不是斜体\* 会渲染为 *这不是斜体*。
  3. 保持简洁： Markdown 的核心是简洁。避免过度复杂的嵌套，如果内容确实需要复杂的布局，可以考虑直接使用 HTML 嵌入。
  4. 工具推荐：
    • 编辑器： Visual Studio Code（配合 Markdown 插件）、Typora（所见即所得）、Obsidian。
    • 在线工具： StackEdit、Dillinger。

总结#

Markdown 以其简洁、直观的语法，极大地提升了书写效率和阅读体验。掌握本文介绍的标题、列表、代码块、链接图片等核心语法，足以应对 90% 以上的日常文档编写需求。记住，最好的学习方式就是实践，立即找一个支持 Markdown 的编辑器或平台开始写作吧！

参考与扩展#

最后更新： 2023年10月27日

2026-03