Markdown 教程

Markdown 是一种轻量级标记语言，用简单的符号（#、*、- 等）就能写出结构清晰、格式美观的文档。它是程序员写 README、写博客、记笔记的事实标准。

为什么用 Markdown

优势	说明
极简语法	几分钟即可学会，几乎零成本
纯文本	任何编辑器都能打开，易版本管理（Git 友好）
通用性强	GitHub、博客、笔记软件全部支持
专注内容	写作时不用纠结排版，交给渲染器

一次看全基本语法

# 一级标题
## 二级标题

**加粗文本** 和 *斜体文本*

- 无序列表项
- 另一个列表项

1. 有序列表项
2. 第二个列表项

> 引用块内容

[链接文字](https://example.com)
![图片描述](image.png)

`行内代码`

```python
print("代码块")
```

Markdown 的渲染流程

用编辑器书写 Markdown 纯文本
渲染器（如 marked、markdown-it）解析为 HTML
浏览器/应用展示美观的排版效果

适用场景

GitHub 项目的 README.md、issue、PR 描述
个人博客（Hexo、Hugo、VuePress 等静态站）
笔记软件（Obsidian、Typora、语雀）
技术文档、API 文档、会议纪要

💡 提示

本教程所有示例都可以在你的 Markdown 编辑器里直接复制体验；Typora、Obsidian 支持"所见即所得"渲染。

Markdown 编辑器

工欲善其事，必先利其器。选择一个顺手的 Markdown 编辑器，写作体验会大大提升。

编辑器	平台	特点
Typora	Win/macOS/Linux	所见即所得，界面极简（付费）
Obsidian	全平台	双向链接、知识库管理、插件丰富（免费）
VS Code	全平台	程序员首选，插件生态强大
语雀	Web/App	国内团队协作，云端同步
StackEdit	Web	在线编辑，支持同步云盘

VS Code 配置

VS Code 内置 Markdown 预览：打开 .md 文件后按 Ctrl+Shift+V（Win）或 Cmd+Shift+V（Mac）即可预览。推荐安装插件：

Markdown All in One：快捷键、自动格式化
markdownlint：语法规范检查
Paste Image：粘贴图片自动存为文件

在线编辑器

dillinger.io：经典在线编辑
markdown-it demo：语法演示
GitHub 在线编辑：直接改 README

选择建议

写代码文档 → VS Code
个人知识库 → Obsidian
极简写作 → Typora
团队协作 → 语雀

💡 提示

不管用哪个编辑器，最终生成的都是标准 Markdown 文本，换工具零成本迁移。

Markdown 第一个文件

创建你的第一个 Markdown 文件，走通"编写 → 渲染"的完整流程。

创建文件

新建文本文件，命名为 first.md（扩展名 .md 或 .markdown）
用任意编辑器（记事本也可以）写入以下内容
用 Typora/Obsidian/VS Code 打开预览

# 我的第一个 Markdown 文档

这是我的 **第一篇** Markdown 文档。

## 今天学了什么

- 创建 .md 文件
- 使用标题
- 添加文本格式

> 千里之行，始于足下。

预览效果

渲染后会看到：一级标题"我的第一个 Markdown 文档"、一段含加粗的文字、二级标题、列表和引用块——完全由简单符号生成。

文件命名规范

GitHub 项目主页固定用 README.md（大小写敏感）
文件名用短横线连接：getting-started.md
中文文件名可用，但跨平台注意编码

常见问题

问题	解决
编辑器没有预览	安装渲染插件或换 Typora/Obsidian
中文乱码	确认文件保存为 UTF-8 编码
换行不生效	Markdown 段内换行需在行尾加两个空格或空一行

⚠️ 注意

Markdown 中的单个换行在渲染时通常不生效（视为同一段落），需要空一行才产生新段落——这是初学者最常见的困惑。

Markdown 标题

标题是文档结构的骨架。Markdown 用 # 号表示标题，数量越多级别越低。

六级标题

# 一级标题（最大）
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题（最小）

书写规范

# 与文字之间建议留一个空格：# 标题
标题应有层级：一级 → 二级 → 三级，不要跳级
一个文档通常只有一个一级标题（即文档主标题）

标题的作用

结构：清晰组织内容层级
导航：自动生成目录（TOC）
折叠：GitHub 中标题自动生成锚点链接
大纲：Typora/Obsidian 侧边栏显示大纲

标题与目录

大多数渲染器支持自动目录：

[[toc]]        <!-- Typora 自动目录 -->
<!-- GitHub 自动在页面生成标题锚点 -->

标题的 HTML 对应

Markdown 标题渲染为 HTML 的 <h1> 到 <h6> 标签，对 SEO 和可访问性都友好。

💡 提示

别用加粗文本冒充标题——标题有语义（大纲、锚点、SEO），加粗只是样式。

Markdown 文本格式

Markdown 的文本格式语法，让文字拥有加粗、斜体、删除线等效果。

基本文本格式

**加粗文本**
*斜体文本*
***加粗斜体***
~~删除线文本~~
`行内代码`
==高亮文本==（部分编辑器支持）

效果对照

语法	效果
`加粗`	加粗
`斜体`	斜体
`~~删除~~`	删除
`代码`	`代码`

行内代码

用反引号包裹表示行内代码，常用于提及函数名、命令、变量：

运行 `npm install` 安装依赖。
调用 `getUserById(42)` 获取用户。

转义特殊字符

若需要显示 *、#、` 等符号本身，用反斜杠转义：

\*不是斜体\*
\# 不是标题

组合使用

**加粗中的 *斜体* 文字**
`inline **代码** 中的标记一般不解析`

💡 提示

不同编辑器对 ==高亮==、<mark> 等扩展语法支持不一，跨平台分享时优先用标准语法。

Markdown 列表

列表是文档中最常用的结构之一。Markdown 支持无序列表、有序列表、嵌套列表和任务列表。

无序列表

- 苹果
- 香蕉
- 橙子

（* 和 + 也可以作为列表符号）
* 项目一
+ 项目二

有序列表

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

序号会自动递增，写成 1. 2. 3. 或全部 1. 都可以。

嵌套列表

- 后端
  - Python
    - FastAPI
    - Flask
  - Node.js
- 前端
  - Vue
  - React

子列表需要缩进（2 或 4 个空格，或用 Tab）。

任务列表（GitHub 风格）

- [x] 完成需求分析
- [x] 实现核心功能
- [ ] 编写测试
- [ ] 部署上线

列表中的其他元素

- 带代码的列表项：使用 `pip install requests`
- 带引用的列表：
  > 引用内容

1. 带链接的列表：[GitHub](https://github.com)
2. 带强调的列表：**重要**事项

⚠️ 注意

列表与其他元素（代码块、引用）混用时，注意缩进对齐，否则渲染会错乱。

Markdown 引用块

引用块用 > 符号表示，适合引用他人观点、标注注意事项、展示对话等。

基本引用

> 这是引用内容。
> 第二行引用。

嵌套引用

> 外层引用
>
> > 内层引用（两个 >）

引用中加其他语法

> **重要提示**：
>
> - 提交前先跑测试
> - 用 `git diff` 检查改动
>
> ```bash
> npm run test
> ```

引用块的常见用途

引用文献、他人观点
文档中的"注意 / 提示 / 警告"区块
论坛回复（如 GitHub issue 的引用回复）
邮件风格的对话展示

多行引用

连续多行以 > 开头即合并为一个引用块；引用块内空一行（仍带 >）可分隔段落。

💡 提示

在 GitHub 上引用他人评论时，用"引用回复"按钮会自动生成带用户名的引用格式。

Markdown 代码

展示代码是技术文档的核心需求。Markdown 支持行内代码和代码块两种方式，代码块还能高亮显示。

行内代码

使用 `git status` 查看工作区状态。

代码块（围栏式，推荐）

用三个反引号包裹，并标注语言即可高亮：

```python
def hello(name):
    print(f"Hello, {name}!")
```

```javascript
function hello(name) {
  console.log(`Hello, ${name}!`);
}
```

```bash
$ pip install requests
```

支持的常见语言标识

标识	语言
`python`	Python
`javascript` / `js`	JavaScript
`typescript` / `ts`	TypeScript
`bash` / `shell`	Shell 命令
`html`	HTML
`css`	CSS
`json`	JSON
`sql`	SQL
`diff`	代码差异

代码块内的反引号

如果代码内容本身含三个反引号（如 Markdown 示例），用四个反引号包裹外层：

````markdown
```python
print("嵌套代码块")
```
````

缩进式代码块（旧语法）

行首缩进 4 个空格或一个 Tab 也可生成代码块（无高亮）：

    <div>缩进式代码块</div>

💡 提示

标注语言能获得语法高亮；GitHub 支持 ```python title="example.py" 等扩展属性（部分渲染器）。

Markdown 链接

链接用于在文档中跳转：外链、站内锚点、邮箱等。图片语法与链接几乎相同（前面多一个 !）。

行内链接

[GitHub](https://github.com)
[CodeNest](https://www.laowang.click "悬停提示文字")

引用式链接

长链接用引用式定义，便于复用和维护：

访问 [GitHub][1] 和 [Python 官网][py]。

[1]: https://github.com
[py]: https://www.python.org

自动链接

<https://www.python.org>   <!-- URL 自动可点击 -->
<mailto:admin@example.com>  <!-- 邮箱链接 -->

站内锚点链接

跳转到文档内其他标题：

[跳到小结](#小结)

## 小结

锚点规则：标题转小写、空格转连字符（## 小结 → #小结）。

相对路径链接（GitHub 常用）

[查看代码](../../src/main.py)
[图片目录](./images/logo.png)

链接高级技巧

// 同一链接多次使用（引用式最省事）
[文档](https://example.com/docs) 和 [文档](https://example.com/docs)

// 新窗口打开（HTML 方式）
<a href="https://example.com" target="_blank">外部链接</a>

⚠️ 注意

链接文字中的 [] 括号需要转义（\[文档\]），否则会被误认为链接语法。

Markdown 图片

图片语法与链接类似，只需在链接前加一个感叹号 !。

基本图片语法

![替代文本](图片地址)

![Logo](https://example.com/logo.png)
![本地图片](./images/logo.png)

带尺寸的图片（HTML 方式）

标准 Markdown 不支持设置宽高，可用 HTML 标签：

<img src="./images/logo.png" width="200" alt="Logo">

图片加链接

[![点击查看大图](./thumb.png)](https://example.com/full.png)

GitHub 的相对路径图片

![架构图](./docs/architecture.png)

引用式图片

![Logo][logo]

[logo]: ./images/logo.png "Logo 图标"

替代文本的作用

图片加载失败时显示的文字
屏幕阅读器朗读的文本（无障碍）
SEO 图片检索

💡 提示

VS Code 装 "Paste Image" 插件后，粘贴剪贴板图片会自动保存到指定目录并生成语法，写文档效率翻倍。

Markdown 表格

表格用管道符 | 和连字符 - 绘制，适合展示结构化数据。

基本表格

| 功能 | 语法 | 说明 |
|------|------|------|
| 加粗 | **文字** | 强调 |
| 斜体 | *文字* | 倾斜 |
| 代码 | `code` | 行内代码 |

对齐方式

在分隔行加冒号控制对齐：

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

表格中的特殊内容

表格单元格内要显示管道符，用 \| 转义：

| 命令 | 说明 |
|------|------|
| `a \| b` | 管道操作 |
| **加粗**、`代码` | 支持行内格式 |

表格注意事项

表头与分隔行必须有（至少一个 ---）
列数对齐，但空格数量不必精确（渲染器自动对齐）
单元格内不支持换行、多行代码块

表格与 HTML

复杂表格（合并单元格等）可退化为 HTML：

<table>
  <tr><th>产品</th><th>价格</th></tr>
  <tr><td colspan="2">整行合并</td></tr>
</table>

💡 提示

VS Code 装 "Markdown Table" 插件后，可图形化编辑表格；在线工具 tableconvert.com 支持从 Excel 粘贴生成 Markdown 表格。

Markdown 高级技巧

除基础语法外，Markdown 还有一批高级技巧，让你的文档更专业。

1. 注释（不显示）

<!-- 这是注释，渲染时不会显示 -->

2. 折叠块（GitHub 支持）

<details>
<summary>点击展开查看详情</summary>

这里是折叠内容，支持 **Markdown** 语法。

```python
print("Hello")
```
</details>

3. 快捷键（Markdown All in One）

操作	快捷键（VS Code）
加粗	`Ctrl/Cmd + B`
斜体	`Ctrl/Cmd + I`
插入链接	`Ctrl/Cmd + K`
切换列表	`Ctrl/Cmd + Shift + ]`

4. 自动目录

[[toc]]   <!-- Typora 语法 -->

5. 上下标（部分支持）

H~2~O（下标，部分编辑器支持）
x^2^（上标，部分编辑器支持）

6. 脚注

这是一个带脚注的句子[^1]。

[^1]: 这是脚注内容，常用于补充说明。

7. 键盘键帽（GitHub）

<kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>S</kbd>

💡 提示

高级语法兼容性不一：发布到 GitHub 用 GitHub 支持的扩展；本地笔记可用 Typora/Obsidian 的扩展。

Markdown 分割线

分割线用于分隔不同内容区块，让文档结构更清晰。

三种写法

---      <!-- 三个以上连字符 -->
***      <!-- 三个以上星号 -->
___      <!-- 三个以上下划线 -->

注意事项

必须独立成行，前后最好有空行
--- 下面紧跟标题时会被当作"Setext 标题"语法，需注意
渲染效果均为一条水平线（<hr>）

错误示例

--->   <!-- 缺少符号，不是分割线 -->
---     <!-- 下方紧跟文字（非标题行）时OK，紧跟标题会变Setext标题 -->

分割线的使用场景

分隔独立章节
分隔正文与附录
README 中分隔说明区与版权区

## 使用方法

正文内容……

---

## 常见问题

FAQ 内容……

💡 提示

正文用标题层级组织（##）比大量分割线更规范；分割线适合轻量分隔。

Markdown 数学公式

Markdown 原生不支持公式，但主流编辑器（Typora、Obsidian、GitHub）都支持 LaTeX 数学公式。本节介绍常用语法。

行内公式

质能方程：$E = mc^2$

块级公式

$$
\frac{-b \pm \sqrt{b^2-4ac}}{2a}
$$

常用符号速查

含义	LaTeX
分数	`\frac{a}{b}`
上标/下标	`x^2`、`x_i`
根号	`\sqrt{x}`
求和	`\sum_{i=1}^{n}`
积分	`\int_{a}^{b}`
希腊字母	`\alpha \beta \gamma`
向量	`\vec{v}`
矩阵	`\begin{matrix} 1 & 2 \\ 3 & 4 \end{matrix}`

综合示例

欧拉公式：$e^{i\pi} + 1 = 0$

正态分布：
$$
f(x) = \frac{1}{\sigma\sqrt{2\pi}} e^{-\frac{(x-\mu)^2}{2\sigma^2}}
$$

注意事项

块级公式用 $$ 包裹，独占一行
GitHub 用 $$...$$ 或 \[...\]
反斜杠在部分语言里需双写（\\）

💡 提示

复杂公式可用在线 LaTeX 编辑器（如 Overleaf、公式在线生成器）编写后粘贴。

Markdown 图表绘制

部分编辑器（如 Typora、Obsidian + Mermaid 插件）支持在 Markdown 中直接绘制图表，最常用的是 Mermaid 语法。

流程图

```mermaid
graph TD
  A[开始] --> B{判断}
  B -- 是 --> C[执行]
  B -- 否 --> D[结束]
```

时序图

```mermaid
sequenceDiagram
  participant 客户端
  participant 服务器
  客户端->>服务器: GET /api/data
  服务器-->>客户端: 200 JSON
```

类图

```mermaid
classDiagram
  class User {
    +String name
    +login()
  }
  class Admin {
    +banUser()
  }
  Admin --|> User
```

甘特图

```mermaid
gantt
  title 项目计划
  dateFormat YYYY-MM-DD
  section 开发
  需求分析: a1, 2026-08-01, 5d
  编码实现: a2, after a1, 10d
```

mermaid 支持的环境

平台	支持
Typora	✅ 原生支持
Obsidian	✅ 内置支持
GitHub	✅ 支持（2022 起）
VS Code	✅ 插件 Markdown Preview Mermaid
语雀	✅ 支持

💡 提示

Mermaid 还有饼图、状态图、思维导图等类型；官方在线编辑器 mermaid.live 可实时预览。

Markdown 实战

综合运用前面所学，完成一个真实场景的 Markdown 实战：撰写项目 README。

目标

为一个小项目写一份规范、可读的 README.md，覆盖标题、简介、安装、用法、配置、许可证。

完整示例

# My Awesome Tool

一个用于自动化报表生成的开源工具。

![Build Status](https://img.shields.io/badge/build-passing-brightgreen)

## 功能特性

- 支持 Excel/CSV 数据导入
- 模板化报表输出
- 定时任务支持

## 安装

```bash
pip install my-tool
```

## 快速开始

```python
from my_tool import Report

report = Report("data.csv")
report.render("output.html")
```

## 配置

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `output_dir` | `./out` | 输出目录 |
| `lang` | `zh-CN` | 报表语言 |

## 常见问题

> **Q：支持数据库数据源吗？**
> A：支持，见[数据源文档](./docs/datasource.md)。

## 许可证

MIT License © 2026

README 最佳实践

名字 + 一句话简介 + 徽章（可选）
功能特性用列表清晰罗列
安装、快速开始给可复制的命令
配置用表格；FAQ 用引用块
附上文档链接与许可证

写作流程建议

先写骨架（标题 → 简介 → 各章节标题）
填充内容，保持简洁
用 markdownlint 检查规范
预览确认渲染效果

⚠️ 注意

README 中的命令和示例一定要真实可运行，否则会误导使用者。

Markdown 测验

本章测验检验你对 Markdown 的掌握程度。先独立作答，再看解析。

选择题

1. 哪个语法表示三级标题？

A. ## 标题
B. ### 标题 ✅
C. #### 标题
D. # 标题

2. 无序列表用哪个符号？

A. #
B. >
C. - ✅
D. |

3. 引用块用什么符号开头？

A. > ✅
B. <
C. *
D. @

4. 行内代码用什么包裹？

A. 单引号 'code'
B. 反引号 `code` ✅
C. 双引号 "code"
D. 括号 (code)

5. 图片语法与链接的区别是？

A. 多一个 ! ✅
B. 多一个 #
C. 完全相同
D. 多一个 *

6. 表格需要哪一行来定义表头？

A. 第一行 + 分隔行（---）✅
B. 只需要第一行
C. 需要 HTML 标签
D. 不需要表头

判断题

7. 单个换行在 Markdown 中会产生新段落。

❌ 错误。需要空一行才是新段落；段内换行行尾需两个空格。

8. 代码块标注语言后可以获得语法高亮。

✅ 正确。如 ```python。

简答题

9. 写出创建"任务列表"（勾选框）的语法。

- [ ] 待办事项
- [x] 已完成事项

10. 写一个包含加粗、斜体、链接、图片的示例。

**加粗**、*斜体*、[链接](https://example.com)、![图](image.png)

计分

答对	水平
9-10	优秀，可直接用于生产文档
6-8	良好，复习薄弱项即可
<6	建议重学基础章节

💡 提示

Markdown 重在多用多写，写几篇 README 和笔记自然就熟练了。

Obsidian 使用教程

Obsidian 是一款基于 Markdown 的本地知识库软件，以"双向链接"和"笔记即文件夹"著称，是个人知识管理（PKM）的利器。

核心特性

特性	说明
本地存储	笔记就是本地 `.md` 文件，数据完全自己掌控
双向链接	`[[笔记名]]` 快速关联，自动生成关系图谱
图谱视图	可视化笔记之间的连接关系
插件生态	上千款社区插件扩展能力
免费	个人使用免费

基本操作

// 链接另一篇笔记
[[Python 入门教程]]

// 链接到笔记内的标题
[[Python 入门教程#安装]]

// 嵌入另一篇笔记的内容
![[笔记片段]]

常用设置

仓库（Vault）：一个文件夹即一个知识库
附件目录：设置图片附件存放位置
同步：官方同步（付费）或 Git 插件/坚果云
模板：创建笔记模板提高效率

常用插件推荐

插件	用途
Dataview	用类 SQL 查询笔记元数据
Templater	高级模板与自动化
Excalidraw	手绘图解并嵌入笔记
Git	版本管理与云端同步
Kanban	看板管理任务

💡 提示

Obsidian 的笔记是标准 Markdown，即使以后不用 Obsidian，你的知识资产也随时可迁移。

第 1 / 18 节

Markdown 教程

Markdown 教程

为什么用 Markdown

一次看全基本语法

Markdown 的渲染流程

适用场景

Markdown 编辑器

推荐编辑器

VS Code 配置

在线编辑器

选择建议

Markdown 第一个文件

创建文件

预览效果

文件命名规范

常见问题

Markdown 标题

六级标题

书写规范

标题的作用

标题与目录

标题的 HTML 对应

Markdown 文本格式

基本文本格式

效果对照

行内代码

转义特殊字符

组合使用

Markdown 列表

无序列表

有序列表

嵌套列表

任务列表（GitHub 风格）

列表中的其他元素

Markdown 引用块

基本引用

嵌套引用

引用中加其他语法

引用块的常见用途

多行引用

Markdown 代码

行内代码

代码块（围栏式，推荐）

支持的常见语言标识

代码块内的反引号

缩进式代码块（旧语法）

Markdown 链接

行内链接

引用式链接

自动链接

站内锚点链接

相对路径链接（GitHub 常用）

链接高级技巧

Markdown 图片

基本图片语法

带尺寸的图片（HTML 方式）

图片加链接

GitHub 的相对路径图片

引用式图片

替代文本的作用

Markdown 表格

基本表格

对齐方式

表格中的特殊内容

表格注意事项

表格与 HTML

Markdown 高级技巧

1. 注释（不显示）

2. 折叠块（GitHub 支持）

3. 快捷键（Markdown All in One）

4. 自动目录

5. 上下标（部分支持）

6. 脚注

7. 键盘键帽（GitHub）

Markdown 分割线

三种写法

注意事项

错误示例

分割线的使用场景

Markdown 数学公式