为什么用 Markdown 写作
Markdown 是轻量标记语言，用简单符号表示格式。写作者不用碰鼠标，专注内容，格式自动生成。
优势：
- 纯文本，任何编辑器能打开
- 版本控制友好（Git 能 diff）
- 可转 HTML、PDF、Word 等格式
- 学习成本低，10 分钟入门
基础语法
标题
# 一级标题
## 二级标题
### 三级标题
#### 四级标题
建议一篇文章只有一个一级标题。
段落
空行分隔段落。不留空行的内容算同一段。
强调
**粗体**
*斜体*
~~删除线~~
列表
无序：
- 项目
- 项目
- 子项目（缩进）
有序：
1. 第一项
2. 第二项
链接与图片
[链接文字](https://example.com)
代码
行内：code
代码块：
```javascript
const x = 1;
### 引用
引用内容 第二行
### 分割线
## 扩展语法
### 表格
| 姓名 | 年龄 |
|---|---|
| Tom | 25 |
### 任务列表
- 已完成
- 未完成
### 脚注
正文内容^1
### 删除线
删除
### 自动链接
URL 自动转链接。
## 写作技巧
### 标题层级清晰
- 一级标题：文章标题
- 二级标题：主要章节
- 三级标题：小节
- 不要跳级（一级直接跳三级）
### 段落简洁
- 一段一个观点
- 段落不要太长（3-5 行最佳）
- 用列表代替长段落
### 善用列表
并列内容用列表，比段落清晰：
- 步骤用有序列表
- 并列项用无序列表
- 对比项用表格
### 代码要标注语言
代码块标注语言，触发语法高亮：
图片加描述
 里的描述很重要：
- 图片加载失败时显示描述
- 屏幕阅读器读描述给视障用户
- 利于 SEO
链接清晰
- 链接文字描述目标内容，别用"点击这里"
- 外链用完整 URL
- 内链用相对路径
文档组织
开头放目录
长文档开头放目录，链接到各章节。方便跳转。
章节用标题分隔
用标题分隔章节，不用分割线。标题有层级，分割线没有。
代码与文字分开
代码块前后留空行，和正文分开。阅读更清晰。
图片放合适位置
图片紧跟相关文字，别集中放末尾。读者按顺序阅读时能及时看到图。
编辑器选择
VS Code
- 免费、强大
- 装Markdown 插件（如 Markdown All in One）
- 实时预览
- 适合开发者
Typora
- 所见即所得
- 无预览窗，直接编辑渲染后效果
- 付费但便宜
- 适合专注写作
Obsidian
- 本地知识库
- 双向链接
- 插件丰富
- 适合笔记和知识管理
在线编辑器
- StackEdit：在线 Markdown 编辑器
- 简书：中文写作平台
- 适合临时写作
Markdown 转 HTML
写完 Markdown 要展示到网页，转成 HTML。用 Markdown 转 HTML 工具 一键转换。
常见错误
标题后没空格
#标题 不识别，要 # 标题（# 后空格）。
列表缩进不对
子列表要缩进 2 或 4 空格（看解析器）。缩进不对子列表不显示。
代码块没闭合
### 特殊字符没转义
想显示 * # 等符号，前面加 \ 转义：\* 显示 *。
### 表格语法错误
表格要有表头分隔行（| --- |）。漏了不识别为表格。
### 链接括号不匹配
`[链接](url` 漏了右括号，链接不识别。
## 最佳实践
### 一份文档一份主题
一篇文章讲一个主题。多个主题拆成多篇，用链接关联。
### 先写内容后调格式
先写纯文字内容，再加 Markdown 标记。避免边写边调打断思路。
### 统一风格
团队写作统一风格：
- 标题用几级
- 列表用 - 还是 *
- 代码块语言标注
- 最多嵌套几层列表
### 保留源文件
Markdown 是源文件，HTML/PDF 是生成物。保留 Markdown 方便修改，每次重新生成输出格式。
## 小结
Markdown 写作核心：标题层级清晰、段落简洁、善用列表、代码标语言、图片加描述。选合适编辑器，统一风格，保留源文件。展示用 [DocsAll Markdown 转 HTML 工具](/convert-tools/markdown-to-html)，浏览器端运行。