Markdown语法示例大全：从基础到高级的完整代码与效果对照

为什么你需要一份 Markdown 示例参考

说实话，Markdown 语法本身不难，但有时候就是想不起来某个具体写法——表格对齐怎么搞来着？引用里面能不能嵌套列表？任务列表的语法是什么来着？

这篇文章把所有常用的 Markdown 语法示例整理在一起，每个都附带源代码和渲染效果。你可以把它当速查表用，也可以从头到尾看一遍，基本就能覆盖日常写作的 90% 需求了。

顺便说一句，下面所有示例我用的是标准 Markdown 和 GitHub Flavored Markdown（GFM）语法，这是目前最通用的标准，在 GitHub、VS Code、Obsidian、Notion 等主流平台上都能正常渲染。

标题示例

Markdown 用 # 号来标记标题，几个 # 就是几级标题：

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

渲染效果就是你现在看到的这些大小不同的标题样式。实际使用中，一级标题通常用作文章大标题，二级和三级标题用来组织章节结构。一篇文档里只用一个一级标题是比较好的习惯。

对了，还有另一种标题写法叫 Setext 风格，用 === 和 --- 分别表示一级和二级标题：

一级标题
========

二级标题
--------

这种写法现在用得比较少了，但有些旧文档里还能见到。

文本格式化示例

加粗和斜体

这是最基础也是最常用的 markdown 格式示例：

**加粗文本**
*斜体文本*
***加粗斜体***
~~删除线~~

效果：

加粗文本：用双星号包裹
斜体文本：用单星号包裹
加粗斜体：用三星号包裹
~~删除线~~：用双波浪号包裹（GFM 扩展语法）

加粗也可以用双下划线 __加粗__，斜体也可以用单下划线 _斜体_，不过我个人习惯一直用星号，保持一致性比纠结选哪个更重要。

段落和换行示例

这是第一段。

这是第二段。

段落之间用空行分隔。
同一段落内换行需要在行尾加两个空格。

这点很容易被忽略——直接回车不会换行，需要行尾加两个空格，或者用 <br> 标签。我之前就踩过这个坑，写了一大段文字想分行显示，结果渲染出来全挤在一行里。

列表示例

无序列表

- 苹果
- 香蕉
  - 小米蕉
  - 大蕉
- 橘子

效果：

苹果
香蕉
- 小米蕉
- 大蕉
橘子

无序列表可以用 -、*、+ 三种符号，效果一样。子列表通过缩进实现，一般缩进 2 或 4 个空格。

有序列表

1. 第一步：安装依赖
2. 第二步：配置环境
3. 第三步：启动项目

效果：

第一步：安装依赖
第二步：配置环境
第三步：启动项目

任务列表

这是 GFM 扩展语法，在 GitHub 的 README 和 Issue 里特别常用：

- [x] 已完成的任务
- [ ] 待完成的任务
- [ ] 另一个待办

效果：

[x] 已完成的任务
[ ] 待完成的任务
[ ] 另一个待办

链接示例

[访问 GitHub](https://github.com)
[带标题的链接](https://github.com "GitHub 首页")

效果：点击访问 GitHub 就能跳转。

还有一种引用式链接写法，适合文章中多处引用同一个 URL 的场景：

[Markdown Guide][1] 是一个很好的学习资源，里面有很多实用的 [markdown 示例][2]。

[1]: https://www.markdownguide.org "Markdown Guide"
[2]: https://www.markdownguide.org/basic-syntax "Basic Syntax"

引用式链接把 URL 集中放在文章末尾，正文部分更干净。写长文章的时候我会用这种方式。

图片示例

![替代文字](https://picsum.photos/200/100)
![带标题的图片](https://picsum.photos/200/100 "示例图片")

语法跟链接很像，就是前面多了一个 !。方括号里写替代文字，当图片加载不出来的时候会显示这段文字，对 SEO 和无障碍访问也有帮助。

如果你想给图片加链接，可以这样嵌套：

[![点击图片](https://picsum.photos/200/100)](https://github.com)

标准 Markdown 不支持直接调整图片大小，但在 GitHub 和不少编辑器里可以用 HTML 的 <img> 标签来控制尺寸。

代码示例

行内代码

使用 `console.log()` 输出调试信息。

效果：使用 console.log() 输出调试信息。

代码块

用三个反引号包裹，可以在后面指定语言实现语法高亮：

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

渲染效果：

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

支持的语言高亮非常多，常用的有 python、java、go、rust、bash、css、html、json、yaml 等。

引用示例

> 这是一段引用文本。
>
> 引用可以包含多个段落。
>
> > 引用也可以嵌套。
>
> - 甚至可以包含列表
> - 以及 **格式化文本**

效果：

这是一段引用文本。
引用可以包含多个段落。
引用也可以嵌套。
甚至可以包含列表
以及 格式化文本

引用块很适合用来标注注意事项、引述他人观点或者突出某些信息。

表格示例

这是日常使用频率很高的一个 markdown 语法示例：

| 语法 | 说明 | 支持情况 |
|------|------|---------|
| `**粗体**` | 加粗文本 | 通用 |
| `*斜体*` | 斜体文本 | 通用 |
| `~~删除线~~` | 删除线 | GFM |
| `[]()` | 链接 | 通用 |

效果：

语法	说明	支持情况
`粗体`	加粗文本	通用
`斜体`	斜体文本	通用
`~~删除线~~`	删除线	GFM
`[]()`	链接	通用

表格对齐

| 左对齐 | 居中对齐 | 右对齐 |
|:-------|:--------:|-------:|
| 内容 | 内容 | 内容 |

效果：

左对齐	居中对齐	右对齐
左边	中间	右边

表格用冒号位置控制对齐：左边有冒号是左对齐，两边都有是居中，右边有冒号是右对齐。

说实话表格是 Markdown 里写起来最累的部分，超过 5 列维护起来就比较痛苦了。复杂表格我一般先用在线表格生成器做好再粘贴过来。

分割线示例

---

***

___

三种写法效果一样，都渲染为一条水平分割线。习惯上用 --- 的最多。注意分割线前后留空行，避免被识别为 Setext 标题。

脚注示例

这是一段带有脚注的文本[^1]，脚注会在文章末尾显示。

[^1]: 这是脚注的内容。

效果：点击上标编号就能跳转到对应注释。脚注是扩展语法，在 Obsidian、Typora、Pandoc 等编辑器中支持，但 GitHub 原生不支持。

转义字符示例

当你想显示 Markdown 的特殊符号本身时，用反斜杠转义：

\*这不是斜体\*
\# 这不是标题
\[这不是链接\]

效果：*这不是斜体*，# 这不是标题。

以下字符可以转义：\、`、*、_、{}、[]、()、#、+、-、.、!、|。

一个完整的 Markdown 文档示例

把上面的语法串起来，这里是一个完整的项目 README 风格的 markdown 文档示例：

# 我的开源项目

一个简洁高效的 **Web 组件库**，帮助开发者快速构建现代化界面。

## 功能特性

- 🎨 丰富的主题定制
- 📦 支持 tree-shaking
- ✅ 完整的 TypeScript 类型定义
- 🧪 测试覆盖率 > 95%

## 快速开始

```bash
npm install my-components
```

```javascript
import { Button } from 'my-components';

const app = () => {
  return <Button type="primary">点击我</Button>;
};
```

## API 参考

| 属性 | 类型 | 默认值 | 说明 |
|:-----|:-----|:------:|:-----|
| type | string | 'default' | 按钮类型 |
| size | string | 'medium' | 按钮尺寸 |
| disabled | boolean | false | 是否禁用 |

> **注意：** 本组件库需要 React >= 18.0。

## 开发计划

- [x] 基础组件开发
- [x] 文档站点搭建
- [ ] 国际化支持
- [ ] 暗色主题

## 贡献

欢迎提交 PR！请先阅读 [贡献指南](https://github.com/example/contributing)。

---

© 2024 我的开源项目

这个示例可以直接复制使用，改改内容就是一份不错的 README。

不同平台的兼容性说明

同样是 Markdown，不同平台支持的程度不一样。这里简单列一下常见的差异：

语法	GitHub	VS Code	Obsidian	Notion
基础语法	完全支持	完全支持	完全支持	完全支持
表格	支持	支持	支持	支持
任务列表	支持	支持	支持	支持
脚注	不支持	视插件而定	支持	不支持
数学公式	支持 LaTeX	视插件而定	支持	支持
Mermaid 图表	支持	视插件而定	支持	不支持

实测发现 GitHub 上嵌套列表的缩进要求比较严格，必须跟上一级的列表标记对齐。而 Obsidian 在这方面宽容一些。如果你的文档需要跨平台使用，建议优先用标准 Markdown 语法，避免依赖特定平台的扩展功能。

参考来源

CommonMark Spec — Markdown 标准规范
GitHub Flavored Markdown Spec — GitHub 扩展语法规范
Daring Fireball: Markdown Syntax — Markdown 创始人的原始规范
Markdown Guide — 综合学习资源