全栈手账 订阅 RSS
← 回到列表
Markdown

Markdown 语法教程

一份实用的 Markdown 语法参考——从基础到进阶，覆盖日常开发中最常用的写法，以及不同平台的差异。

读了 22 分钟 更新于 8 月 5 日

一、基础语法

1. 标题

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

效果：

一级标题

二级标题

三级标题

注意：

  • # 后面必须加空格，否则不会被识别为标题
  • 建议一篇文章只有一个 H1（文档标题），其余用 H2/H3 组织层级
  • H4+ 在大多数主题中视觉差异不大，尽量用 H2/H3 管理层级

2. 段落与换行

markdown
这是第一段文字。想要换行，需要在行尾加两个空格，然后回车。或者用一个空行来分隔段落。这是第二段文字。

效果：
这是第一段文字。想要换行，需要在行尾加两个空格，然后回车。

或者用一个空行来分隔段落。

这是第二段文字。

最佳实践：段落之间用空行分隔（最直观），行内换行用两个空格（在 Typora 等编辑器中可以直接回车）。

3. 加粗与斜体

markdown
*斜体* 或 _斜体_**加粗** 或 __加粗__***加粗斜体*** 或 ___加粗斜体___~~删除线~~

效果：
斜体 加粗 加粗斜体 删除线

4. 列表

无序列表：

markdown
- 项目一- 项目二  - 子项目（缩进 2 个空格）  - 子项目- 项目三

有序列表：

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

嵌套列表：

markdown
1. 开发流程   - 需求分析（缩进 2 空格）   - 设计评审     1. UI 评审     2. 技术评审   - 编码实现2. 测试流程

5. 链接

markdown
[显示文字](https://example.com)[带标题的链接](https://example.com "鼠标悬停时显示的文字")[用变量复用链接][site][site]: https://example.com<!-- 后面的引用链接可以在文档底部集中管理 -->

6. 图片

markdown
![替代文字](https://example.com/image.png)![替代文字](图片路径 "图片标题")![带尺寸限制的图片](image.png){: width="600" height="400" }<!-- {: width=...} 部分编辑器支持，不是标准语法 --><!-- 本地图片用相对路径 -->![截图](./images/screenshot.png)

图片与链接的区别：图片前面多一个 !。

7. 分割线

markdown
---<!-- 三个或以上的横线/星号/下划线 -->***___

注意：分割线前后最好有空行，否则可能被解析为标题（--- 在两个 # 后会被当作 H2 的另一种写法）。

二、表格

1. 基本表格

markdown
| 序号 | 名称 | 说明 ||------|------|------|| 1 | 用户管理 | 管理用户账号与权限 || 2 | 内容管理 | 管理文章与分类 || 3 | 系统设置 | 全局配置参数 |

效果：

序号 名称 说明
1 用户管理 管理用户账号与权限
2 内容管理 管理文章与分类
3 系统设置 全局配置参数

2. 对齐方式

markdown
| 左对齐 | 居中对齐 | 右对齐 ||:-------|:--------:|-------:|| 张三   |  98 分   |  北京  || 李四   |  87 分   |  上海  || 王五   |  92 分   |  广州  |

效果：

左对齐 居中对齐 右对齐
张三 98 分 北京
李四 87 分 上海
王五 92 分 广州

3. 表格内换行

标准 Markdown 的表格单元格内不支持直接换行。如果编辑器支持 HTML，可以用 <br>：

markdown
| 功能 | 说明 ||------|------|| 登录 | 支持账号密码登录<br>支持微信扫码登录 || 注册 | 仅支持手机号注册 |

注意：<br> 在 GitHub、Typora、VS Code 中都能正常工作，但在某些纯文本渲染器（如部分 CLI 工具）中可能显示为纯文本。

4. 表格使用建议

  • 表头与内容之间的 ---|--- 分隔线不能省略，否则表格不生效
  • 单元格的 | 左右空格不是必须的，但加上更整齐（用编辑器插件自动格式化）
  • 表格内不要放太长的文字，必要时拆成多行或用列表代替

三、代码块

1. 行内代码

markdown
使用 `console.log()` 方法打印调试信息。变量声明推荐用 `const` 代替 `var`。

效果：使用 console.log() 方法打印调试信息。

2. 多行代码块（推荐方式）

markdown
```javascriptfunction greet(name) {  return `Hello, ${name}!`;}console.log(greet('World'));```

效果：

javascript
function greet(name) {  return `Hello, ${name}!`;}console.log(greet('World'));

3. 支持的语法高亮语言

语言 标识符
JavaScript / TypeScript js / javascript / ts / typescript
HTML / XML html / xml
CSS / SCSS css / scss
Java java
PHP php
Python python / py
SQL sql
Bash / Shell bash / sh / shell
JSON / YAML json / yaml
Diff diff
无高亮 text / plain / 不写标识符

4. Diff 代码块（展示变更）

diff
```difffunction greet(name) {-  return 'Hello, ' + name;+  return `Hello, ${name}!`;}```

效果：

diff
function greet(name) {-  return 'Hello, ' + name;+  return `Hello, ${name}!`;}

5. 代码块内的转义（展示 Markdown 语法本身）

如果你要在代码块中展示 Markdown 语法，需要用更多层的反引号包裹：

markdown
````markdown# 这是展示用的标题**这是展示用的加粗**```javascriptconsole.log("嵌套代码块");```````

外层用 ```（4 个反引号），内层用 ```（3 个反引号）。

四、引用与分割线

1. 引用块

markdown
> 这是一段引用文字。> 可以跨多行，每行前面都加 >。

效果：

这是一段引用文字。 可以跨多行，每行前面都加 >。

2. 嵌套引用

markdown
> 第一层引用>> > 第二层引用（嵌套）> >> > > 第三层引用>> 回到第一层

效果：

第一层引用

第二层引用（嵌套）

第三层引用

回到第一层

3. 引用内带其他元素

markdown
> **注意**：引用内可以使用其他 Markdown 语法。>> - 列表项 1> - 列表项 2>> ```javascript> console.log("引用内的代码块");> ```>> > 引用的引用（嵌套）

4. 引用使用建议

  • 引用适合标注：重点提示、引用来源、警告信息、备注说明
  • 引用块前后建议加空行，避免与正文粘连
  • 不要用引用块代替正文段落，否则阅读体验不好

五、高级语法

1. 任务列表（Task List）

markdown
- [x] 已完成的任务- [ ] 未完成的任务- [ ] 等待中的任务  - [x] 子任务 1  - [ ] 子任务 2

效果（GitHub / Typora 支持）：

  • 已完成的任务
  • 未完成的任务
  • 等待中的任务

注意：任务列表需要 - [ ] 格式（短横 + 空格 + 方括号 + 空格），方括号内的 x 大小写均可。不是所有编辑器都支持勾选交互。

2. 脚注

markdown
这是一段有脚注的文字[^1]。[^1]: 这是脚注内容，会显示在文档底部。

效果：这是一段有脚注的文字^1。

注意：脚注在 GitHub 上不支持。在 Typora、VS Code 预览、Obsidian 等工具中可用。

3. 锚点链接（跳转到文档内指定位置）

markdown
## 跳转到#三-代码块[点击跳转到代码块章节](#三-代码块)

效果：点击跳转到代码块章节

生成规则：

  1. 取标题文字
  2. 转小写
  3. 空格变横线 -
  4. 去掉标点符号
  5. 中文标题取决于编辑器实现（大多数直接用中文，如 #三-代码块）

4. 折叠详情（Details / Summary）

markdown
<details><summary>点击展开查看详情</summary>这里是折叠内容。可以包含 **Markdown** 语法：- 列表- 表格- 代码块```javascriptconsole.log("折叠内的代码");
```

效果：

点击展开查看详情

这里是折叠内容。 可以包含 Markdown 语法：

  • 列表
  • 表格
  • 代码块
javascript
console.log("折叠内的代码");

注意：<details> 是 HTML 标签，不是标准 Markdown。GitHub、GitLab 支持，部分编辑器（如纯文本 Typora 模式）不支持。

5. HTML 混写

Markdown 本质上是 HTML 的超集，可以直接嵌入 HTML：

markdown
<div style="text-align: center; padding: 20px; background: #f5f5f5; border-radius: 8px;">  <h3>居中卡片</h3>  <p>这是一段用 HTML 包裹的文字。</p>  <p style="color: #2577fd;">主色蓝色</p></div>

适用场景：

  • 文字居中、分栏布局
  • 彩色文字、背景色
  • 自定义按钮
  • 图片排版

警告：HTML 混写会破坏可移植性——GitHub、编辑器、博客平台渲染效果可能不同。仅在必要的场景下使用。

6. Emoji

markdown
GitHub 支持两种写法：:smile: :rocket: :warning: :white_check_mark: :x:直接粘贴 emoji：😄 🚀 ⚠️ ✅ ❌

效果：😄 🚀 ⚠️ ✅ ❌

:xxx: 语法只在 GitHub、GitLab 等特定平台有效。直接粘贴 emoji 字符兼容性最好。

六、扩展语法

1. Mermaid 图表

部分支持 Mermaid 的编辑器（GitHub、GitLab、Obsidian 等）可以直接渲染图表：

流程图：

markdown
```mermaidgraph TD    A[开始] --> B{是否登录?}    B -->|是| C[进入首页]    B -->|否| D[跳转登录页]    C --> E[选择线路]    D --> F[输入账号密码]    F --> G{验证通过?}    G -->|是| C    G -->|否| F```

效果（在支持的编辑器中会渲染为图形）：

mermaid
graph TD    A[开始] --> B{是否登录?}    B -->|是| C[进入首页]    B -->|否| D[跳转登录页]    C --> E[选择线路]    D --> F[输入账号密码]    F --> G{验证通过?}    G -->|是| C    G -->|否| F

时序图：

markdown
```mermaidsequenceDiagram    participant 用户    participant 前端    participant 后端    用户->>前端: 点击登录    前端->>后端: POST /api/login    后端->>后端: 校验账号密码    后端-->>前端: 返回 token    前端-->>用户: 跳转首页```

甘特图：

markdown
```mermaidgantt    title 项目排期    dateFormat  YYYY-MM-DD    section 需求阶段    需求分析       :done, 2024-01-01, 3d    原型设计       :active, 2024-01-04, 5d    section 开发阶段    后端 API       :2024-01-09, 10d    前端页面       :2024-01-09, 10d```

支持平台：GitHub（2022+）、GitLab、Obsidian、Notion（部分）、Typora（需启用） 不支持：VS Code 原生预览、飞书文档、语雀

2. 数学公式（LaTeX）

markdown
```mathE = mc^2```行内公式：$E = mc^2$独立公式：$$f(x) = \int_{-\infty}^{\infty} \hat{f}(\xi) e^{2\pi i \xi x} d\xi$$

支持平台：GitHub（部分）、Obsidian（需插件）、Typora（需启用） 不支持：绝大多数博客平台、飞书/语雀

3. 目录（TOC）

部分编辑器支持自动生成目录：

markdown
[[_TOC_]]  <!-- GitLab 语法 --><!-- 或 -->[TOC]       <!-- 部分编辑器支持的写法 -->

GitHub 不支持自动 TOC，需要手动写链接锚点：

markdown
- [一、基础语法](#一基础语法)  - [标题](#1-标题)  - [表格](#2-表格)- [二、代码块](#二代码块)

七、编辑器与平台差异

不同的 Markdown 编辑器/平台对语法的支持程度不同，这是最常见的"写出来效果不对"的原因。

语法特性 GitHub Typora VS Code 飞书文档 语雀 Obsidian
基础语法 ✅ ✅ ✅ ✅ ✅ ✅
表格 ✅ ✅ ✅ ✅ ✅ ✅
代码高亮 ✅ ✅ ✅ ❌ ❌ ✅
Diff 代码块 ✅ ✅ ✅ ❌ ❌ ✅
任务列表 ✅ ✅ ✅ ✅ ✅ ✅
脚注 ❌ ✅ ✅ ❌ ❌ ✅
折叠 Details ✅ ❌ ✅ ❌ ✅ ✅
Emoji :xxx: ✅ ❌ ✅ ❌ ❌ ❌
Mermaid ✅ ✅ ❌（需插件） ✅ ❌ ✅（需插件）
数学公式 ✅（部分） ✅（需启用） ❌ ❌ ✅ ✅（需插件）
HTML 混写 ✅ ✅ ✅ ❌ ❌ ✅
自动 TOC ❌ ✅ ❌ ❌ ❌ ✅

实用建议：

  • 写 GitHub 文档：只用基础语法 + 表格 + 代码块 + 任务列表 + 折叠（GitHub 都支持）
  • 写个人笔记（Typora / Obsidian）：可以用脚注、Mermaid、数学公式
  • 写飞书/语雀文档：只用基础语法，代码块不要期望有高亮

八、常见误区

误区 1：标题忘记加空格

markdown
❌ #标题✅ # 标题

没有空格的情况下，大多数解析器不会识别为标题。

误区 2：列表和段落之间没有空行

markdown
❌ 这是一段文字。- 列表项 1- 列表项 2✅ 这是一段文字。- 列表项 1- 列表项 2

没有空行时，有些解析器会把上一段文字视为列表的一部分。

误区 3：表格的 ---|--- 分隔线不对齐

markdown
❌| A | B | C ||---||---|- --|| 1 | 2 | 3 |✅| A | B | C ||---|---|---|| 1 | 2 | 3 |

分隔线里的 - 数量至少 3 个，| 的排列要规则，否则表格可能渲染失败。

误区 4：代码块语言标识符写错

markdown
❌ ```javascripts❌ ```typescripts✅ ```javascript✅ ```js✅ ```typescript✅ ```ts

写错标识符不会导致代码块失效（只是没有高亮），但注意 js 和 javascript 都行，javascripts 不行。

误区 5：中英文符号混用

markdown
❌ 【Markdown】**标题** —— 说明    （全角符号）✅ [Markdown]**标题** -- 说明      （半角符号）

Markdown 的语法符号（# * - | ` [等）必须使用半角符号。中文全角符号会被当作普通文字。

误区 6：不写空行导致格式混排

markdown
❌一段文字| 表头 | 表头 ||------|------|| 内容 | 内容 |另一段文字✅一段文字| 表头 | 表头 ||------|------|| 内容 | 内容 |另一段文字

表格、代码块、引用等块级元素，前后必须用空行与正文分隔。

误区 7：代码块内的反引号嵌套错误

如果需要展示代码块语法本身（比如写一篇 Markdown 教程）：

markdown
❌ 外层写 3 个反引号，里层也写 3 个：```javascript```markdown# 标题
文本
✅ 外层写 4 个反引号，里层写 3 个：````markdown```markdown# 标题
文本
```---## 九、实用模板### 1. README 模板```markdown# 项目名称> 一句话项目简介## 技术栈- 前端：Vue 3 + Vite + Pinia- 后端：Spring Boot 3.2 + MyBatis-Plus- 数据库：MySQL 8## 快速开始```bash# 克隆项目git clone https://github.com/user/project.git# 安装依赖npm install# 启动开发服务器npm run dev```## 项目结构```src/├── api/          # API 接口├── components/   # 公共组件├── views/        # 页面└── utils/        # 工具函数```## 功能模块- [x] 用户注册登录- [x] 线路浏览搜索- [ ] 预订支付- [ ] 评论系统```### 2. PRD 模板```markdown# PRD：[功能名称]## 版本记录| 版本 | 日期 | 作者 | 变更说明 ||------|------|------|----------|| v1.0 | 2024-xx-xx | 张三 | 初版 |## 背景与目标（为什么做、预期收益）## 用户角色- 普通用户：浏览、预订- 供应商：管理线路- 管理员：审核、配置## 功能需求### 模块 1：[功能名称]**需求描述**：（用户操作路径）**业务规则**：- 规则 1- 规则 2**异常处理**：- 超时场景- 无数据场景## 验收标准- [ ] 功能 A 正常可用- [ ] 边界情况 B 已覆盖- [ ] 性能要求 C 达标```### 3. 周报模板```markdown# 周报：第 X 周（2024-xx-xx ~ 2024-xx-xx）## 本周完成- [x] 登录模块重构- [x] 修复 3 个线上 Bug- [x] 参加产品评审## 进行中- 支付流程联调## 下周计划1. 完成支付功能2. 撰写 API 文档## 风险- 支付接口第三方对接进度未知，已催```### 4. API 文档模板```markdown# API 文档：用户模块## 注册```POST /api/user/register```**请求参数**：| 参数 | 类型 | 必填 | 说明 ||------|------|------|------|| username | string | 是 | 用户名，3-20 字符 || password | string | 是 | 密码，6-20 字符 |**响应示例**：```json{  "code": 200,  "message": "success",  "data": {    "token": "eyJhbGciOiJIUzI1NiJ9...",    "userId": 1  }}```**错误码**：| code | message | 说明 ||------|---------|------|| 400 | username already exists | 用户名已存在 || 400 | invalid password format | 密码格式不符 |```---## 十、总结Markdown 的设计理念是"**写的时候像纯文本，渲染出来像富文本**"。掌握它需要记住几件事：1. **语法符号用半角**：`#` `*` `-` `` ` `` `[` 必须是英文符号2. **空行是排版的生命线**：块级元素前后要空行3. **知其边界**：不同平台支持程度不同，跨平台写作只用基础语法4. **所见即所得**：Typora / VS Code 实时预览最方便，纯文本编辑器（Vim / VSCode 纯文本模式）更需要记牢语法> 不必死记所有语法——常用的就那么几个（标题、列表、代码块、表格、加粗斜体），其他查这份教程就行。

前端、后端、部署、客服都是我一个人。写这里的东西都是真踩过的坑，不是抄来的教程。