正心全栈编程

第二章 Markdown 的流行原因 ​

上一章那份 Python 入门说明，现在放进项目仓库，成了团队的 README.md。新同事要能接着写，大家要看得出每次改了什么；有人用 Windows，有人用 macOS，网站还可能换主题。文档要用得久，就得经得起这些变化。

Markdown 为什么能做到？关键在于它是纯文本，常用语法不多；内容结构和显示样式可以分开，文件也方便跨平台使用、交给 Git 管理。这章把这些原因逐个讲清楚。

Markdown 历久弥新的五大核心支柱

2.1 纯文本 ​

团队的 README.md 首先是一份纯文本文件。打开源码，看到的就是这样的内容：

md
# Python 入门

Python 是一种简单易学的编程语言。

## Python 的特点

- 语法简洁
- 生态丰富
- 应用广泛

不用预览，也能认出标题、正文和列表。这种简单的保存方式，给后面的使用留了很大余地。

长期保存

一份 Markdown 文件，内容可能只有：

text
# 标题

这是一段正文。

以后换了电脑、换了软件，只要还能读取文本文件，正文通常就能打开。它不依赖某一个编辑器的版本，所以适合保存这些需要常年维护的内容：

  • 技术文档；
  • 学习笔记；
  • 项目说明；
  • 课程内容；
  • 知识库。

程序读取 ​

程序读取 Markdown，跟读取普通文本差不多。想跟着试，可以把 2.1 开头的示例保存成当前目录下的 article.md，然后运行：

python
with open("article.md", encoding="utf-8") as file:
    content = file.read()

print(content)

屏幕上会打印文件原文，第一行仍是 # Python 入门。此时 content 是普通字符串，可以继续查找、替换，或做统计和分析；需要时还能批量修改文件、转换格式、自动生成内容。

比如，可以从 Markdown 生成网页：

text
Markdown
   ↓
程序读取
   ↓
生成 HTML
   ↓
发布网站

也可以批量读取文件，提取标题做目录：

text
100 个 Markdown 文件
        ↓
程序批量读取
        ↓
提取标题
        ↓
自动生成目录

文件原文容易读取。要准确提取标题，还得按 Markdown 语法解析；好在正文和标记都能直接拿到。

文本比较 ​

再看修改记录。原来的内容是：

md
FastAPI 是一个 Web 框架。

后来改成：

md
FastAPI 是一个现代 Python Web 框架。

比较工具能直接指出变动：

diff
- FastAPI 是一个 Web 框架。
+ FastAPI 是一个现代 Python Web 框架。

课程、软件文档、开源项目和团队规范都要反复修改，看清每次改了什么，比只知道“文件变了”有用得多。

2.2 语法简洁 ​

Markdown 容易上手，还因为常用写法很少。拿标题和列表来说，HTML 是这样写的：

html
<h2>Python 的特点</h2>

<ul>
  <li>简单</li>
  <li>易学</li>
  <li>生态丰富</li>
</ul>

换成 Markdown：

md
## Python 的特点

- 简单
- 易学
- 生态丰富

后一种写法看着更像平时记笔记。

标记语言视觉阻力对比：HTML 标签噪音 vs Markdown 自然可读

Markdown 有意让源码保持可读：

即使不经过渲染，原始文本也应该尽量容易阅读。

比如：

md
**重要内容**

就算没学过语法，也能猜到两个 ** 在强调文字。再看：

md
> 这是一段引用。

行首的 > 提示这是一段引用。列表也差不多：

md
- Python
- Java
- JavaScript

这些符号不多，直接看原文也能读下去。

高频语法

日常写文档，反复用到的无非是这些：

text
标题
段落
列表
链接
图片
粗体
引用
代码

会用它们，就能写出一份完整的普通文档。例如：

md
# Python 入门

Python 是一种非常流行的编程语言。

## 学习内容

- 变量
- 列表
- 字典
- 函数

详细内容可以访问 [Python 官网](https://www.python.org/)。

示例代码：

```python
print("Hello, Python!")
```

没用过 Markdown 的人，大致也能读懂。学的时候先掌握这些常用写法就够了，其余语法用到再查。

2.3 内容与样式分离 ​

Markdown 先把内容的结构写清楚：

重点描述“内容是什么”，而不是“内容具体长什么样”。

例如写下：

md
# Python 入门

意思是：

“Python 入门”是一个一级标题。

至于它显示成什么样，Markdown 没有指定：

  • 32 像素；
  • 黑色；
  • 微软雅黑；
  • 上边距 20 像素；
  • 下边距 16 像素。

这些是显示样式。同一个标题交给不同软件，外观就可能不同：

text
README.md
   │
   ├── GitHub → GitHub 的样式
   ├── Typora → Typora 的主题
   ├── Obsidian → Obsidian 的主题
   └── VitePress → 网站主题

主题更换

假设团队把 Python 课程发布到文档网站，课程文件写着：

md
# Python 基础

## 列表

## 字典

## 函数

以后网站想换个配色，通常改网站样式就行。比如原来是：

text
一级标题 → 黑色
二级标题 → 深灰色

后来改为：

text
一级标题 → 蓝色
二级标题 → 紫色

课程正文不用跟着改。两者的分工可以画成：

text
内容
Markdown
   │
   │
   ↓
表现方式
CSS / Theme

如果课程有几十章，只改一处主题就能统一外观，维护起来省事很多。

多种呈现方式

再看一份 python.md，它可以去往不同地方：

text
python.md
   │
   ├── GitHub
   │     ↓
   │   README 页面
   │
   ├── Typora
   │     ↓
   │   本地文档
   │
   ├── Obsidian
   │     ↓
   │   知识笔记
   │
   ├── VitePress
   │     ↓
   │   文档网站
   │
   └── Pandoc
         ↓
      PDF / Word / HTML

单源多态渲染架构：同一份内容，无限种视觉呈现

写的时候先把文章写好。展示在哪里、用什么字体颜色、要导出什么格式，可以等到发布时再处理。

2.4 跨平台 ​

团队里有人用 Windows，有人用 Linux 或 macOS。同一份 notes.md，放到这些系统上通常都能打开。

只要能读取 UTF-8 文本，通常就能看到文档原文。至于预览后的效果，还要看各自用的工具。

编辑器迁移 ​

今天用 Typora 写文章，过段时间换成 Obsidian，通常打开原来的 .md 文件就能接着写。程序员可能更习惯 VS Code 或 PyCharm；要发布网站，还能把文件交给 VitePress。它们围着同一份文件工作：

text
                Typora
                  ↑
                  │
VS Code ←── Markdown ──→ Obsidian
                  │
                  ↓
               VitePress

数据主权：软件锁定（围墙花园）vs 文件居中（自由插拔）

正文保存在文件里，编辑器只是打开和修改它的工具。换工具的成本通常不高，不过图片路径和工具专属语法仍要检查。

2.5 Git 协作 ​

把 README.md 放进仓库，它就能跟着代码一起修改。GitHub、GitLab 上的项目通常都有这份文件。项目目录可能长这样：

text
project/
├── README.md
├── CONTRIBUTING.md
├── CHANGELOG.md
├── docs/
│   ├── installation.md
│   └── usage.md
└── src/

文档和代码待在同一个项目里，也可以共用一套 Git 流程：

text
代码
+
文档
+
Git

变更比较 ​

Git 擅长记录文本文件的变化。.py、.js、.html、.css 源代码是文本，.md 文件也是。

假设第一次提交的文档是：

md
# Flask 入门

Flask 是一个 Python Web 框架。

后来又补上说明和安装步骤：

md
# Flask 入门

Flask 是一个轻量级 Python Web 框架。

## 安装

```bash
pip install flask
```

Git 可以记录：

text
新增了什么
删除了什么
修改了什么
什么时候修改
谁进行了修改

历史记录 ​

假设一门课程持续维护三年：

text
2026
↓
第 1 版

2027
↓
第 2 版

2028
↓
第 3 版

用 Git 管理课程文件，之后想回头查，可以看到：

text
某一章什么时候创建
某一段什么时候修改
某段内容为什么被删除
历史版本是什么样

“为什么删除”还要结合提交说明来看。如果某次修改出了问题，可以恢复旧版本。长期维护的内容尤其需要留好这些记录，比如：

  • 软件官方文档；
  • 编程教程；
  • 在线课程；
  • 团队知识库；
  • 技术规范。

多人协作 ​

再想象两个人一起改课程：小明改第 1 章，小红改第 3 章，这样的改动通常好合并。即使碰巧改了同一个文件，Git 也能把各自的修改列出来：

diff
- 原来的内容
+ 修改后的内容

改动位置不冲突时通常能合并；两人改了同一处，就得一起决定保留哪一版。文档也能像代码一样走团队协作流程。

2.6 长期维护 ​

Markdown 主要保存文本，文件通常不大。一篇几千字的 article.md，可能只有几十 KB。和包含大量排版信息的文档格式相比，它更轻，带来几个实际好处：

  • Git 仓库体积更小；
  • 上传下载更快；
  • 备份简单；
  • 同步方便；
  • 搜索速度快。

不过，正文文件小不代表整个项目都小。图片多的话，资源文件照样占空间：

text
course/
├── chapter01.md
├── chapter02.md
└── images/
    ├── 01.png
    ├── 02.png
    └── 03.png

这里占空间的主要是图片，不是 .md 文件。

文本搜索

正文是普通文本，几乎任何文本搜索工具都能查。想找项目里哪里提到了 FastAPI，在 Linux 中可以运行：

bash
grep -R "FastAPI" .

文件多了，这种搜索更有用。比如一个知识库：

text
docs/
├── python/
├── flask/
├── fastapi/
├── docker/
├── linux/
└── agent/

哪怕有几百篇文档，也能直接搜正文，不必逐个打开。

内容迁移

假设最初在 Typora 里写文档：

text
Typora
   ↓
Markdown 文件

几年后想改用 Obsidian：

text
Markdown 文件
   ↓
Obsidian

再后来想发布成网站：

text
Markdown 文件
   ↓
VitePress

要交一份 Word 文件，也可以转换：

text
Markdown
   ↓
Pandoc
   ↓
Word

正文一直保存在 Markdown 文件里，不用跟着编辑器搬家。迁移时仍要检查图片路径、附件和工具专属语法，确保新工具能正常处理。这种换工具还能继续使用内容的能力，叫作：

可迁移性。

功能分工

Markdown 主要负责内容结构。要精确控制字体、页面布局、页眉页脚、图文环绕或印刷排版，就得用别的工具。

这些工具可以各管一件事：

text
Markdown
负责：
内容结构

CSS / Theme
负责：
网页样式

Pandoc
负责：
格式转换

Git
负责：
版本管理

VitePress
负责：
生成网站

分工清楚，正文就不必为了换一种发布方式而重新写。

现代技术写作工具链：职责协同流水线

长期使用

最后把这些变化放到一门长期维护的课程上。一组文件可能是：

text
python-course/
├── 01_intro.md
├── 02_variable.md
├── 03_list.md
└── 04_function.md

现在用：

text
VS Code
↓
编写

过阵子用：

text
Typora
↓
修改

需要上线时交给：

text
VitePress
↓
发布

要导出 PDF 时用：

text
Pandoc
↓
导出 PDF

几年后又换了工具：

text
新的 Markdown 工具
↓
继续打开

只要新工具支持文档里用到的语法和资源路径，正文通常就不用跟着编辑器改。这就是：

把内容和具体工具解耦。

2.7 本章小结 ​

回到团队的 README.md：新同事能很快接着写，大家能搜索正文、核对改动，网站也能直接使用这份文件。前面讲的几个特点，其实连在一起：

text
纯文本
   ↓
简单稳定
   ↓
容易读取
   ↓
容易编辑
   ↓
容易搜索
   ↓
容易转换
   ↓
容易版本管理
   ↓
容易被各种工具支持

到了下一章，这些特点还会用在与 AI 协作上：

text
结构清晰
+
文本简单
+
容易解析