← 返回工具箱
Markdown 写作完全指南
📅 2026-04-19
⏱️ 约 15 分钟
🏷️ 写作工具
Markdown 是程序员和技术写作者最常用的纯文本标记语言。它简洁、跨平台、所见即所得，已成为 GitHub README、技术文档、博客文章的事实标准。本文从基础到高级，帮你建立完整的 Markdown 知识体系。
一、基础语法：掌握这 8 种就够了
Markdown 的设计哲学是"用最简单的符号，表达最常见的排版需求"。学完以下 8 种，你就覆盖了 90% 的写作场景。
1. 标题（Heading）
用 # 数量表示层级，最多支持 6 级：
# 一级标题（文章大标题）
## 二级标题（章节标题）
### 三级标题（小节标题）
#### 四级标题
##### 五级标题
###### 六级标题
2. 强调与删除线
**粗体文本**
*斜体文本*
***粗斜体***
~~删除线文字~~
`行内代码`
3. 列表
无序列表：使用 -、+ 或 *（效果相同，推荐统一使用 -）：
- 第一项
- 第二项
- 子项（缩进2个空格）
- 子项
- 第三项
有序列表：使用数字加句点，注意序号会自动处理：
1. 第一步
2. 第二步
3. 第三步
⚠️ 常见错误
有人会这样写：1. 第一 2. 第二 3. 第三。Markdown 会自动从 1 开始渲染，但
不要手动编序号，只管写数字即可，渲染器会自动处理。
4. 链接与图片
[显示文本](https://example.com)
[锚点链接](#section-id)
图片的懒人写法：先写链接文字的感叹号版，再把文字替换成描述即可。
5. 代码块
行内代码：用反引号包裹，如 `grep`、`git status`。
多行代码块：用三个反引号包裹，支持语法高亮：
```bash
echo "Hello, World!"
git add .
git commit -m "Initial commit"
```
```python
def hello(name):
return f
print(hello())
```
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: web-app
spec:
replicas: 3
6. 表格
| 列1 | 列2 | 列3 |
|-------|----------|---------|
| 数据1 | 数据2 | 数据3 |
| 数据4 | 数据5 | 数据6 |
| 左对齐 | 居中对齐 | 右对齐 |
|:------|:-------:|------:|
| L | C | R |
7. 引用块
> 这是引用文字
> 可以有多行
>
> 段内换行需要空行分隔
8. 分割线
---
或者：
***
二、高级语法：让文档更专业
1. 任务列表（Checkbox）
- [x] 已完成的任务
- [ ] 未完成的任务
- [ ] 另一个待办
- [x] 子任务已完成
- [ ] 子任务待做
GitHub Issues、GitHub Actions、Notion 都支持这种格式，在项目管理中非常实用。
2. 脚注（Footnote）
这是一段文字，需要解释[^1]。
[^1]: 这是脚注内容，会显示在文章底部。
脚注可以有第二行，会自动缩进对齐。
3. Mermaid 图表
在支持 Mermaid 的渲染器（如 GitHub、GitLab、Typora）中，可以用代码块画流程图和架构图：
```mermaid
graph LR
A[输入] --> B{判断}
B -->|条件1| C[处理A]
B -->|条件2| D[处理B]
C --> E[输出]
D --> E
```
4. 目录自动生成
大多数 Markdown 编辑器（如 VS Code + Markdown All in One）支持自动根据标题生成目录：
按 Ctrl+Shift+P → 输入 "Table of Contents" → 选择 "Create Table of Contents"
三、主流工具推荐
| 工具 | 类型 | 适用场景 | 平台 |
|---|
| VS Code | 编辑器 | 程序员写文档、代码注释 | 全平台 |
| Typora | 所见即所得 | 专注写作、博客文章 | Win/Mac/Linux |
| Obsidian | 双链笔记 | 知识管理、第二大脑 | 全平台 |
| Joplin | 笔记+同步 | 本地优先、隐私敏感 | 全平台 |
| Notion | 协作平台 | 团队文档、项目管理 | Web |
| MWeb | 专业写作 | Mac 原生、多文档管理 | Mac/iOS |
💡 我的推荐
VS Code + Markdown All in One 是程序员最佳组合：语法高亮、实时预览、快捷键、目录生成、TOC 全支持。
Obsidian 适合做个人知识库，支持双向链接和图谱视图。
Typora 适合纯写作体验，无干扰界面，导出 PDF/HTML/EPUB 能力强。
四、VS Code Markdown 写作最佳实践
必备插件
- Markdown All in One：自动目录、快捷键、数学公式、目录生成
- Markdown Preview Enhanced：更强的预览，支持 Mermaid、pandoc 导出
- markdownlint：代码风格检查，自动提示格式问题
- Paste Image：截图后直接粘贴，自动保存到本地目录
- Chinese (Simplified) Language Pack：中文界面
推荐设置
{
"[markdown]": {
"editor.formatOnSave": true,
"editor.defaultFormatter": "esbenp.prettier-vscode",
"editor.wordWrap": "on",
"editor.renderWhitespace": "boundary"
},
"pasteImage.path": "${currentFileDir}/assets",
"pasteImage.prefix": "./"
}
五、常用快捷键速查
| 快捷键 | 功能 |
|---|
Ctrl + B | 粗体 |
Ctrl + I | 斜体 |
Ctrl + Shift + K | 插入链接 |
Ctrl + Shift + C | 插入代码块 |
Ctrl + Shift + V | 分屏预览 |
Ctrl + K V | 侧边栏预览 |
Ctrl + Shift + P → toc | 生成目录 |
六、常见问题
Q: Markdown 和 HTML 哪个好？
Markdown 是 HTML 的"语法糖"，两者可以混用。简单排版用 Markdown，复杂交互用 HTML。不要为了用 HTML 而用 HTML，保持简洁是 Markdown 的核心价值。
Q: 不同平台渲染效果不一样怎么办？
这是 Markdown 的最大痛点。不同平台对扩展语法的支持差异很大。建议：基础语法全覆盖，扩展语法按需使用。发布前用目标平台实际预览一遍。
Q: 如何写长文档？
推荐用 VS Code + 多文件引用：用 !include 或 Mume（Markdown Preview Enhanced）等工具，将大文档拆分成多个文件，通过引用组合。
💡 写作流程建议
1. 先写大纲（用标题结构）
2. 用任务列表规划内容块
3. 分块填充内容（先写完再说格式）
4. 最后统一调整格式、添加图片
5. 用 markdownlint 检查格式
6. 在目标平台预览最终效果
Markdown
写作
效率工具
VS Code
技术写作
← 返回工具箱