2026年2月27日

Markdown 写作技巧 - 高效文档编写指南

by ATNClock

Markdown 是一种轻量级标记语言，以简洁的语法实现格式化文本，是技术写作的首选。

Markdown 简介

什么是 Markdown

Markdown 由 John Gruber 于 2004 年创建，特点：

简洁：语法简单易学
可读：源码即文档
通用：广泛支持
扩展：支持多种扩展

应用场景

技术文档
博客文章
README 文件
笔记记录
电子书编写

基础语法

标题

# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题

段落与换行

段落之间用空行分隔。

这是第二段。

行末两个空格  
实现换行。

强调

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

列表

无序列表

- 项目 1
- 项目 2
  - 子项目 2.1
  - 子项目 2.2
- 项目 3

* 或使用星号
+ 或使用加号

有序列表

1. 第一项
2. 第二项
3. 第三项
   1. 子项 3.1
   2. 子项 3.2

任务列表

- [x] 已完成任务
- [ ] 未完成任务
- [ ] 待办事项

链接与图片

[链接文本](https://example.com)

[带标题的链接](https://example.com "链接标题")

![图片替代文本](image.png)

![带标题的图片](image.png "图片标题")

[引用式链接][ref]

[ref]: https://example.com

引用

> 这是一段引用
> 可以多行

> 嵌套引用
>> 第二层
>>> 第三层

代码

行内代码

使用 `code` 表示行内代码

代码块

```javascript
function hello() {
  console.log('Hello, World!');
}
```

支持的语言：

javascript / js
python / py
java
cpp / c++
css
html
bash / shell
json
yaml
sql

分割线

---

***

___

表格

| 列1 | 列2 | 列3 |
|-----|:---:|----:|
| 左对齐 | 居中 | 右对齐 |
| 内容 | 内容 | 内容 |

效果：

列1	列2	列3
左对齐	居中	右对齐
内容	内容	内容

扩展语法

脚注

这是一个脚注[^1]

[^1]: 这是脚注的内容

定义列表

术语 1
: 定义 1

术语 2
: 定义 2a
: 定义 2b

缩写

*[HTML]: Hyper Text Markup Language
*[CSS]: Cascading Style Sheets

HTML 和 CSS 是前端基础。

数学公式

行内公式

$E = mc^2$

块级公式

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

Mermaid 图表

```mermaid
graph LR
    A[开始] --> B{判断}
    B -->|是| C[处理]
    B -->|否| D[结束]
    C --> D
```

支持的图表：

flowchart / graph
sequenceDiagram
classDiagram
stateDiagram
erDiagram
gantt
pie

任务列表扩展

- [ ] 未开始
- [x] 已完成
- [/] 进行中
- [-] 已取消

写作技巧

文档结构

# 文档标题

简短描述文档内容。

## 目录

- [章节1](#章节1)
- [章节2](#章节2)

## 章节1

内容...

### 子章节

内容...

## 章节2

内容...

## 总结

总结内容...

## 参考资料

- [参考1](link)
- [参考2](link)

标题层级

一级标题：文档标题（仅一个）
二级标题：主要章节
三级标题：子章节
四级标题：细分内容

建议不超过四级。

段落写作

每段 3-5 句为宜
段落间空一行
重要内容加粗
代码使用代码块

列表使用

并列内容用无序列表
步骤流程用有序列表
待办事项用任务列表
数据对比用表格

链接管理

使用引用式链接保持正文简洁：

这是一个[示例链接][example]。

[example]: https://example.com

工具推荐

编辑器

工具	平台	特点
VS Code	全平台	插件丰富
Typora	全平台	所见即所得
Obsidian	全平台	双链笔记
MarkText	全平台	开源免费
Notion	Web/App	协作功能

VS Code 插件

Markdown All in One
Markdown Preview Enhanced
Paste Image
Code Spell Checker
markdownlint

在线工具

StackEdit：https://stackedit.io/
Dillinger：https://dillinger.io/
Markdown Tables Generator：https://www.tablesgenerator.com/

转换工具

Pandoc：格式转换
markdown-pdf：转 PDF
mermaid-cli：图表转图片

最佳实践

代码块规范

```language
// 添加注释说明
code here
```

图片规范

![描述性文本](path/to/image.png)

*图片说明（可选）*

链接规范

[描述性文本](https://example.com)

避免：[点击这里](url)
推荐：[查看完整文档](url)

表格规范

| 功能 | 说明 | 示例 |
|------|------|------|
| 内容 | 简洁 | 示例 |

表格不宜过于复杂

文件命名

推荐：
- getting-started.md
- api-reference.md
- user-guide.md

避免：
- 文档1.md
- 新建文档.md

常见问题

Q: 如何转义特殊字符？

使用反斜杠：

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

Q: 如何在表格中使用代码？

| 命令 | 说明 |
|------|------|
| `npm install` | 安装依赖 |

Q: 如何添加目录？

大多数 Markdown 渲染器支持：

[toc]

或手动创建：

- [标题1](#标题1)
- [标题2](#标题2)

Q: 如何处理长链接？

[链接文本][ref]

[ref]: https://very-long-url.com/path/to/page?param=value

Markdown 变体

变体	说明
CommonMark	标准规范
GitHub Flavored	GitHub 扩展
Markdown Extra	PHP 扩展
MultiMarkdown	功能丰富

总结

Markdown 写作要点：

简洁明了：保持语法简洁
结构清晰：合理使用标题层级
格式统一：保持风格一致
可读性强：源码也要易读