Markdown 写作与开发完全指南
从基础到进阶，全面掌握 Markdown 语法——表格、代码块、任务列表，以及不同 Markdown 风格之间的差异。
Markdown 是互联网上最接近通用写作格式的存在。它被广泛用于 GitHub README、Notion 文档、Slack 消息、文档网站、博客文章和开发者笔记。学一次，终身受用——贯穿你整个职业生涯。
什么是 Markdown？
Markdown 是由 John Gruber 于 2004 年创建的轻量级标记语言。其核心理念是：用简单的标点符号约定来写纯文本，即可渲染为格式精美的 HTML。
This **bold text** and *italic text* render instantly.
渲染效果：This bold text and italic text render instantly.
即使在渲染之前，原始文本依然清晰易读。
基础语法
标题
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
使用标题来构建文档层级结构。# H1 通常作为页面标题——每篇文档只使用一个。
强调
**bold text**
*italic text*
***bold and italic***
~~strikethrough~~
列表
Unordered list:
- Item one
- Item two
- Nested item (indent with 2 spaces)
- Another nested item
- Item three
Ordered list:
1. First step
2. Second step
3. Third step
链接与图片
[Link text](https://example.com)
[Link with title](https://example.com "Hover tooltip")
引用块
> This is a blockquote.
> It can span multiple lines.
> You can nest blockquotes:
> > Like this.
水平分割线
---
（在单独一行使用三个或更多短横线、星号或下划线）
代码块
行内代码使用单个反引号：
Use the `console.log()` function for debugging.
围栏代码块使用三个反引号，并可选填语言标识符以启用语法高亮：
```javascript
function greet(name) {
return `Hello, ${name}!`;
}
```
支持的语言包括 javascript、typescript、python、bash、sql、json、yaml、css、html、go、rust 等数十种——具体取决于渲染器。
表格
Markdown 表格使用竖线字符和短横线：
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Cell A | Cell B | Cell C |
| Cell D | Cell E | Cell F |
在分隔行中使用冒号来设置列对齐方式：
| Left | Center | Right |
|:-----|:------:|------:|
| L | C | R |
表格是 GitHub Flavored Markdown（GFM）的特性，并非标准 Markdown 的一部分。它在 GitHub、VS Code、大多数文档平台和 MDX 中均可使用。
任务列表（GFM）
- [x] Write the introduction
- [x] Add code examples
- [ ] Review and publish
- [ ] Add images
在 GitHub 上会渲染为可交互的复选框，现代 Markdown 渲染器对其支持也相当广泛。
Markdown 风格
原始 Markdown 有意保持简洁，因此衍生出了众多扩展版本：
| 风格 | 使用场景 | 主要新增特性 |
|---|---|---|
| CommonMark | 众多平台 | 标准化规范 |
| GitHub Flavored（GFM） | GitHub、GitLab | 表格、任务列表、删除线、自动链接 |
| MDX | React 网站 | 在 Markdown 中使用 JSX 组件 |
| Pandoc Markdown | 学术文档 | 脚注、引用、数学公式 |
| MultiMarkdown | macOS 工具 | 表格、元数据、脚注 |
如有疑问，优先使用 GFM——它是支持最广泛的扩展风格。
Front Matter
许多 Markdown 处理器支持在文件顶部使用 YAML front matter 来添加元数据：
---
title: "My Article Title"
date: "2026-03-24"
author: "Jane Doe"
tags: ["markdown", "writing", "tools"]
published: true
---
# Article content starts here
Front matter 会与文档正文分开解析，用于设置页面标题、日期和 SEO 元数据等。
MDX：Markdown + JSX
MDX 是可以包含 React 组件的 Markdown。它非常适合用于基于 React 的站点（Next.js、Gatsby、Astro）中的文档和博客文章：
import { Alert } from '../components/Alert'
## Important note
<Alert type="warning">
This feature is deprecated in v3.
</Alert>
Regular **Markdown** content continues below.
这将 Markdown 的简洁性与交互式组件的强大功能完美融合。
转义特殊字符
在特殊 Markdown 字符前加反斜杠，可将其按字面意思渲染：
\*not italic\*
\# not a heading
\[not a link\]
写出更好的 Markdown 文档的技巧
- 每句话单独一行 —— 让 Git 中的差异对比更清晰；由于 Markdown 会忽略单个换行符，渲染效果完全一致。
- 块与块之间留空行 —— 在段落、标题、列表和代码块之间始终保留一个空行。
- 统一列表标记符 —— 在无序列表中选择
-或*，并在整个项目中保持一致。 - 对重复 URL 使用引用链接 —— 定义一次，多处引用：
See the [documentation][docs] and [changelog][docs]. [docs]: https://example.com/docs - 为每张图片添加 Alt 文本 —— 对可访问性和 SEO 至关重要。
检查可读性
Markdown 让写作变得轻松——但轻松写出的内容未必易于阅读。使用我们的可读性评分工具来检查 Flesch-Kincaid 年级水平、句子复杂度和被动语态使用情况。面向大众读者时，建议将语言控制在 8–10 年级的清晰简洁水平。
Markdown 是那种只需 10 分钟就能上手、却能让你受益终身的工具。今天就开始使用吧——你未来的协作者（和未来的自己）都会感谢你。