Markdown 语法完全指南：从入门到实战应用

你是否曾在 GitHub 上看到格式整齐的 README 文件，或是在 Notion 笔记里用简单符号排出漂亮标题，却不知道背后那套语法叫什么名字？那就是 Markdown——一种诞生于 2004 年、如今已渗透进几乎所有数字写作场景的轻量级标记语言。本文将带你从历史背景到语法细节，再到实际应用场景，完整认识 Markdown 的一切。

一、Markdown 是什么？从一个故事说起

2004 年，美国作家兼程序设计师 John Gruber 和知名信息安全研究员 Aaron Swartz 共同设计了 Markdown。Gruber 当时的出发点很简单：当他在写文章时，需要一种语法让纯文本文件「读起来也很舒服」，同时又能一键转换成干净的 HTML，省去手动套标签的繁琐。他把这套语法命名为 Markdown，在语义上是 Markup（标记语言，例如 HTML）的「反义」——用最少的符号做到最多的格式表达。

Markdown 的核心设计哲学有三点：纯文本优先（任何文本编辑器都能打开与编辑，不绑定专属软件）、视觉直觉（语法符号的形状本身就暗示了它的功能）、可转换性（Markdown 文件可输出为 HTML、PDF、Word、LaTeX 等多种格式）。

二十多年后的今天，Markdown 已成为 GitHub、GitLab、Stack Overflow、Reddit、Discord、Notion、Obsidian、Confluence、VS Code 原生文档系统乃至各大博客平台的标准写作语言。

二、为什么选择 Markdown 而非 Word 或直接写 HTML？

格式	最适合场景	主要优点	主要限制
Word / Google Docs	商业文件、合同、正式报告	所见即所得、复杂版式、修订追踪	绑定软件、格式易乱、Git 版本管理困难
HTML	需要精确控制样式的网页	完全控制、浏览器原生支持	语法冗长、阅读源码不直观
Markdown	技术文档、README、博客、笔记	纯文本、轻量、易读、版本管理友好	复杂版式需借助 HTML

Markdown 的核心竞争力在于它是纯文本：可用 git diff 追踪每一行修改；在任何设备、任何操作系统以任何编辑器打开；通过 Pandoc 等工具批量转换格式；方便全文搜索与替换。

三、基本语法：标题、段落、文字样式

标题（Headings）

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

实践建议：正文章节从 H2 开始；避免跳级使用标题（例如从 H2 直接跳 H4），否则会破坏屏幕阅读器对文档结构的解析。

文字样式

**粗体** 或 __粗体__
*斜体* 或 _斜体_
***粗斜体***
~~删除线~~

四、列表：有序、无序与嵌套


- 第一项
- 第二项


1. 第一步
2. 第二步


- 前端技术
  - HTML
  - CSS
  - JavaScript
    1. 变量与类型
    2. 函数

五、链接与图片

[显示文字](https://example.com)
[显示文字](https://example.com "悬停提示")

![替代文字](https://example.com/image.png)

无障碍重点：图片的替代文字（Alt Text）应具有描述性，避免填写「image.png」这类无意义文字。

六、代码：行内代码与围栏代码块


请执行 `npm install` 后再启动 `npm run dev`。


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

常用语言标识符：javascript、python、php、bash、css、html、json、yaml、sql。

七、引用区块（Blockquote）

> 引用内容写在这里。
> 多行引用每行都要加 >。
>
> **注意**：这个功能在 v2.0 后已变更。

> 一层引用
> > 嵌套二层引用

八、表格（GFM 扩展语法）

| 语言       | 类型 | 入门难度 |
| ---------- | ---- | -------- |
| Python     | 解释 | 低       |
| JavaScript | 解释 | 中       |
| Rust       | 编译 | 高       |

冒号控制对齐：:--- 左对齐、---: 右对齐、:---: 居中对齐。

九、进阶语法

任务清单（GFM）

- [x] 阅读 Markdown 指南
- [x] 安装 VS Code
- [ ] 提交第一个 Pull Request

YAML Front Matter

静态网站生成器（Hugo、Jekyll、Next.js）使用 YAML Front Matter 定义文章元数据：

---
title: "Markdown 语法指南"
date: 2026-03-23
tags: ["Markdown", "写作"]
---

正文从这里开始...

十、Markdown 方言与规范

CommonMark：最严格的标准化规范，定义明确，测试完整。
GFM（GitHub Flavored Markdown）：在 CommonMark 基础上增加表格、任务清单、Alerts 等扩展语法，已成行业事实标准。
MDX：结合 Markdown 与 JSX，允许在文档中嵌入 React 组件，广泛用于现代前端框架文档系统。
Quarto：学术界与数据科学领域常用，支持嵌入可执行的 Python、R 代码。

十一、Markdown 的主要应用场景

GitHub / GitLab 项目文档：README.md、CHANGELOG.md、CONTRIBUTING.md 是开源项目的标配。
个人知识管理：Obsidian、Logseq、Joplin 均以 Markdown 为核心存储格式，避免厂商锁定。
技术博客与静态网站：Hugo、Jekyll、Astro、Next.js 均支持 Markdown 文章。
协作工具：Notion、Confluence、Slack、Discord 均支持 Markdown 的子集。
API 文档与技术规范：OpenAPI、npm README 等广泛采用 Markdown 格式。

十二、常见陷阱与最佳实践

段落之间必须有完全空白的行才能正确分段，单次回车不够。
标题 # 后面必须加空格，写成 #标题 在严格渲染器中无效。
列表嵌套超过三层时，考虑改用标题 + 表格的组合呈现。
同一文档中统一使用一种无序列表符号（- 或 *），避免混用。
在目标平台预览确认后再发布，不同平台渲染结果可能存在差异。
为团队 Markdown 文档配置 markdownlint，统一代码风格减少无意义 diff。

立刻动手试试看

打开本站的在线 Markdown 编辑器，将本文任意代码示例粘贴进去，左侧输入右侧即时预览——这是学习 Markdown 最高效的方式。

结语

Markdown 的魅力在于「低起点、高天花板」：五分钟内即可掌握基本语法，但随着深入使用，它与 Git、静态网站生成器、知识管理系统的结合可以构建出非常强大的写作工作流。更重要的是，Markdown 让你的专注力回归到内容本身。现在，建立一个 .md 文件，开始你的第一篇 Markdown 文章吧。