为什么程序员都在用 Markdown？

我第一次用 Markdown 的时候

2018 年，我刚开始写代码。那时候写项目文档还是用 Word，结果每次提交到 GitLab，代码评审的同事就吐槽：

"你这 Word 文档 diff 看不了啊，改成 Markdown 行不行？"

我当时还觉得无所谓，不就是个文档吗？后来确实经历了几次“到底改了什么场”的惨痛会议后，我终于明白为什么程序员都在用 Markdown。

现在我已经用了六年，每天都在用。这篇文章说说我的真实体会。

原因一：Git 友好，版本控制没烦恼

这是程序员用 Markdown 的最大原因，没有之一。

先看一个场景：三个人同时改同一个文档。

用 Word：

三个不同版本，文件名叫“文档-小明修改”“文档-小红修改”“文档-最终版”
最后合并？请手动对比三个文件
写死我算了

用 Markdown + Git：

三个人各开一个 branch
合并时 Git 自动显示冲突
解决冲突后，历史记录清清楚楚

看个实际例子，同事改了一个 API 参数：

- "max_retries": 3
+ "max_retries": 5

一眼就能看出改了什么。而 Word 的修订模式？我已经不想回忆了。

原因二：纯文本，永不过时

我电脑里还有 2005 年的 .doc 文件，新版 Word 打开经常乱码。

但 Markdown？它就是个 .md 纯文本文件。记事本能打开，VS Code 能打开，vim 能打开，电脑的“cat”命令都能看。

二十年后，你的 Markdown 文件还是能正常打开。这个确定性，对程序员来说很重要。

而且文件体积极小。我写过一个 5000 字的技术文档，Markdown 文件才 8KB。如果是 Word，至少得 200KB+。

原因三：代码高亮的原生支持

程序员写文档，内容一大半是代码。

Markdown 原生支持代码块，而且能指定语言做语法高亮：

```python
def hello():
    print("Hello, World!")
```

渲染出来就是带颜色高亮的代码，跟 IDE 里一样。

Word 里怎么写代码？调 Consolas 字体，手动加灰色背景，注释手动改绿色……算了，想想都累。

而且 Markdown 支持行内代码，写文档的时候提到函数名或变量：getUserById() 或 MAX_RETRIES，一目了然。

原因四：跨平台兼容

我在 Mac 上写，同事在 Windows 上看，服务器是 Linux——Markdown 都能正常显示。

Word？我见过太多“在我电脑上好好的”的惨剧了。字体缺失、版本不兼容、分页符跳掉……

Markdown 不存在这些问题。它就是文本加符号，没有“渲染引擎不兼容”这种事。

原因五：工具链成熟

程序员整天都在用的工具，早就原生支持 Markdown 了：

GitHub / GitLab

README.md —— 每个项目的门面
Issue 和 PR 描述
Wiki 文档

编辑器

VS Code 内置 Markdown 预览
JetBrains 全家桶支持
vim 配合插件也能预览

文档工具

Notion、Obsidian、Typora
MkDocs、Docusaurus、GitBook
Confluence 也支持 Markdown 导入

这意味着，你写的 Markdown 内容可以无缝在各种工具之间流转。写在 Obsidian 里的笔记，直接贴到 GitHub README，格式同样正常。

真实案例：我们团队怎么用

README 写作

每个项目必须有 README.md，包含：

# 项目名称

简要描述

## 快速开始

\`\`\`bash
npm install
npm run dev
\`\`\`

## 配置说明

| 参数 | 说明 | 默认值 |
|------|------|--------|
| PORT | 端口 | 3000 |

## API 文档

详见 [docs/api.md](docs/api.md)

新人入职，看 README 就能跑起项目。不用说“去问小明”。

技术博客

我们公司技术博客用 Hugo，文章全是 Markdown：

本地写文章
git push 推到 main 分支
CI/CD 自动构建部署

不需要登录后台、不需要富文本编辑器，写完 push 就完事。

API 文档

之前试过 Word 写 API 文档，结果：

文件越来越大，打开越来越慢
代码样式全靠手动调
更新了不知道改了哪里

后来换成 Markdown + Docusaurus：

文件按 API 模块拆分，每个文件几十 KB
代码块原生支持，写完就能看
git log 一看就知道谁改了什么

工作效率差了一个数量级。

说说局限性

当然，Markdown 不是万能的。

不适合的场景：

要打印给客户的正式商务文档
需要复杂排版（多栏、文字环绕）
非技术人员合作（他们可能不认 .md）

我的做法：

技术内容加内部单据：Markdown
客户合同、商务方案：Word
需要转换的时候：doc2markdown.com

给刚入行同学的建议

如果你刚开始写代码，我强烈建议学 Markdown。

理由：

一小时入门，受益整个职业生涯
GitHub 、GitLab 到处都要用
写 README 、Issue、PR、Wiki 全靠它
技术博客、90% 是 Markdown

入门路径：

看一遍基础语法（半小时）
填一个 GitHub 项目的 README
写一篏 Issue 或 PR 描述
慢慢就熟练了

别匝谨。现在多数技术团队都默认程序员会 Markdown，不会的话够抽屹的。

总结

回顾一下程序员用 Markdown 的核心原因：

Git 友好：版本控制清晰，团队协作无压力
纯文本：永不过时，文件轻便
代码高亮：写技术内容的天然优势
跨平台：任何设备都能正常显示
工具链成熟：和程序员日常工具无缝集成

这不是赶时髦，是实打实的效率工具。如果你还没学过，现在就可以开始。