正心全栈编程

第一章 Markdown 的学习价值 ​

Word、WPS、在线文档已经很好用了，为什么还要学 Markdown？

假设我们写了一份 Python 入门说明，起初只是发给同学看。后来它要放进项目仓库，跟着代码一起修改，还要发布到文档网站。同一份内容换了好几个地方，维护起来就没那么简单了。

Markdown 适合处理这样的内容。它的思路是：

用尽可能简单的文本，表达一篇文档最重要的结构。

我们就从这份说明出发，看看 Markdown 解决了什么问题、适合写什么，以及什么时候该用别的工具。

Markdown 学习价值与文档范式跃迁

1.1 富文本与文档结构 ​

我们熟悉的 Word、WPS 和在线文档，基本都是富文本编辑器。选中一句话，点一下“标题 1”，马上就能看到标题的样子；加粗、改字体、插图、做表格也一样直观。

这类编辑器的特点是：

你编辑时看到的效果，就是最终文档的效果。

这就是常说的“所见即所得”。如果那份 Python 入门说明只需要发给同学阅读，用富文本编辑器就很方便。可一旦要反复修改、比较版本，再放到网站上，我们就得多考虑一步：文档的内容和排版是不是绑得太紧了？

手工排版 ​

比如在 Word 里写这份说明，我们可能逐段设置：

  • 一级标题：18 号黑体；
  • 二级标题：16 号黑体；
  • 正文：12 号宋体；
  • 代码：Consolas；
  • 提示内容：灰色背景。

排出来当然没问题。这里说的是逐段手工设置格式；Word 的“标题 1”等样式，本身也能表示文档结构。不过在手工排版时，我们很容易把两件事混在一起：

第一类是 内容结构：

  • 这是一级标题；
  • 这是二级标题；
  • 这是正文；
  • 这是代码。

第二类是 显示样式：

  • 18 号；
  • 黑体；
  • 蓝色；
  • 灰色背景；
  • 上下间距 12 像素。

Markdown 更关注前一类。把同样的内容写成 Markdown，是这样：

md
# Python 入门

## 第一个 Python 程序

下面编写第一个 Python 程序：

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

这段文本没有规定标题的字号和颜色，也没有指定代码背景。它告诉软件的是：

text
Python 入门
→ 一级标题

第一个 Python 程序
→ 二级标题

print("Hello, Python!")
→ Python 代码

最终显示成什么样，交给使用这份文档的软件决定。这就是 Markdown 的一个核心思路：

内容负责表达结构，样式负责决定外观。

内容与表现分离：富文本强耦合 vs Markdown 架构解耦

结构写在内容里，换个工具显示时，就不用把每一段的外观重新写一遍。

1.2 文档复用与处理 ​

以前，一份文档的使用过程往往很简单：

text
人编写
   ↓
人阅读

拿 Word 文件举例：

text
Word
↓
保存
↓
发送给别人
↓
别人打开阅读

我们的 Python 入门说明则可能要同时交给好几种工具：

text
                   ┌→ Git：记录和比较修改
Python 入门说明.md ├→ AI：辅助检查与修改
                   ├→ 网站生成器：发布网页
                   └→ 程序：提取内容、建立搜索索引

Markdown 作为研发内容中枢与生态流转

有人直接读它，Git 要比较改动，AI 可以帮忙检查，程序还可能提取标题、生成搜索索引。需要发布时，再把它转成 HTML、PDF 或 Word。保留一份结构清晰的 Markdown 源文件，通常就不用为每个去处重新整理正文。

纯文本 ​

Markdown 文件通常以：

text
.md

作为扩展名。你可能已经见过这些文件名：

text
README.md
python.md
fastapi.md
notes.md

扩展名看着特别，文件本身却是普通文本。下面这些内容就可以直接保存成一份 Markdown 文件：

md
# Python

Python 是一种编程语言。

## Python 的特点

- 简单
- 易学
- 生态丰富

不用专门安装 Markdown 软件，记事本、Vim、VS Code 都能打开它。即使只看原文，看到：

text
# Python

也能猜到这是标题；看到：

text
- 简单
- 易学
- 生态丰富

也能认出列表。.docx 文件当然也能由程序解析，但直接打开文件原文，人没法像读 Markdown 一样读正文。Markdown 的好处正在这里：

人能够直接阅读，程序也能够方便处理。

工具迁移 ​

再想想个人笔记。一个软件用了五年，里面攒了很多内容。哪天它停止更新、改了收费方式，或者你只是想换个工具，首先会担心：

我的内容还能不能方便地拿出来？

很多 Markdown 软件最终保存的是：

text
xxx.md

文件可以像这样放在文件夹里：

text
notes/
├── python.md
├── fastapi.md
├── docker.md
└── linux.md

不用原来的软件了，文件还在。你可以换成：

  • VS Code；
  • Typora；
  • Obsidian；
  • Vim；
  • JetBrains IDE；
  • 其他 Markdown 编辑器。

也可以自己写程序来读取。那份 Python 入门说明也是如此：编辑器可以换，正文仍留在文件里。

内容通常属于文件，而不是属于某一个编辑器。

工具迁移与数据主权：软件锁定 vs 文件居中

版本管理 ​

那份 Python 入门说明后来加上了 FastAPI 安装步骤。放进仓库后，我们会想知道每次究竟改了哪几行。Git 很擅长做这件事。先看一段 Python 代码，原来是：

python
price = 100

后来改成：

python
price = 120

Git 会把变化显示出来：

diff
- price = 100
+ price = 120

Markdown 也是纯文本，比较起来同样直接。假设文档原本写的是：

md
## 安装 FastAPI

执行下面的命令：

```bash
pip install fastapi
```

后来补充了虚拟环境的提示：

md
## 安装 FastAPI

推荐在虚拟环境中安装 FastAPI：

```bash
pip install fastapi
```

两版一对比，改动一眼就能找到：

diff
- 执行下面的命令：
+ 推荐在虚拟环境中安装 FastAPI：

Git 会记录这些差异，日后想查哪一行是什么时候改的，也能找得到。

版本管理实战：.docx vs .md 的 Git 视角对比

技术文档、开源项目和课程内容常常要改很多轮：

text
课程第 1 版
↓
修改
↓
课程第 2 版
↓
修改
↓
课程第 3 版

每一轮变化都可以留在 Git 里。GitHub 项目中常见的这些文档，也经常写成 Markdown：

text
README.md
CONTRIBUTING.md
CHANGELOG.md

AI 协作 ​

把 Python 入门说明交给 AI 检查时，清楚的标题、列表和代码块能帮它辨认内容。很多 AI 工具给出的回答，本身也带有 Markdown 结构。例如：

md
## FastAPI 的优势

FastAPI 主要具有以下特点：

1. 性能较高；
2. 支持类型提示；
3. 自动生成 API 文档。

示例：

```python
from fastapi import FastAPI

app = FastAPI()
```

这里的：

text
##

是标题标记；

text
1.
2.
3.

是有序列表；

text
```python

则标出一段 Python 代码。这些符号让结构写在了文字里。再看一份 Python 学习资料：

md
# Python

## 基础语法

### 变量

### 列表

## 面向对象

### 类

### 继承

光看标题层级，就能理出这样的关系：

text
Python
├── 基础语法
│   ├── 变量
│   └── 列表
└── 面向对象
    ├── 类
    └── 继承

AI 可以据此定位内容，人也更容易核对它改了哪个部分。第三章还会具体看 AI 怎样使用、修改和输出 Markdown。

Markdown 与 AI 协作：双向结构化握手与人机协同

1.3 应用场景 ​

开头那份 Python 入门说明，可以放在项目里，也可以用作课程和文档网站的正文。Markdown 还常见于下面这些地方。

技术文档

项目中的技术文档经常写成 Markdown，比如：

text
README.md
API 文档
安装教程
开发指南

编程课程

课程需要把解释和代码放在一起，Markdown 写起来很顺手。例如：

md
## 创建列表

可以使用 `[]` 创建列表：

```python
names = ["Tom", "Jerry"]
```

文字和代码放在一起，读的时候也容易对照。像下面这些技术课程，都能这样写：

  • Python；
  • JavaScript；
  • FastAPI；
  • Flask；
  • Docker；
  • Linux；

博客写作

很多博客系统可以直接接收 Markdown，常见流程是：

text
Markdown
   ↓
博客生成器
   ↓
HTML
   ↓
网站

写文章时就不用手动编写 HTML。

个人笔记

Obsidian 等知识管理工具也大量使用 Markdown。一个笔记库里，可能放着：

text
学习笔记
工作记录
知识库
读书笔记
项目记录

项目仓库文档

打开一个 GitHub 项目，常常先看到：

text
README.md

它通常告诉读者：

  • 项目是什么；
  • 如何安装；
  • 如何运行；
  • 如何贡献代码。

写代码时总会碰到这类文件，熟悉 Markdown 很有用。

AI 提示词与输出

提示词里如果有多个要求，用 Markdown 分开写会更清楚：

md
# 任务

检查下面的 Python 代码。

## 检查要求

1. 检查语法问题；
2. 检查异常处理；
3. 检查代码结构。

## 输出格式

请按照以下结构输出：

### 问题

### 修改建议

人读着清楚，AI 也更容易分辨任务、要求和输出格式。

文档网站

Markdown 文件还能直接作为文档网站的正文来源。例如：

text
Markdown
   ↓
VitePress
   ↓
HTML
   ↓
技术文档网站

开头那份 Python 入门说明，就可以按这条路径发布出去。

1.4 适用边界 ​

回到那份 Python 入门说明：要放进仓库、持续修改，再发布成网站，用 Markdown 比较顺手。但如果交付的是一份版式固定、需要严格分页的文件，Word 或专业排版工具通常更合适。

比如下面这些材料：

  • 正式公文；
  • 合同；
  • 复杂论文排版；
  • 精确页眉页脚；
  • 图文混排宣传册；
  • 需要严格分页的材料；

它们对页面细节要求高。Markdown 擅长处理的则是：

text
结构化内容
+
纯文本
+
跨平台
+
程序处理
+
版本管理

选工具时，可以这样判断：

text
复杂版式
   ↓
Word / WPS / LaTeX

内容与结构
   ↓
Markdown

Markdown 适用边界与工具选型决策指南

1.5 结构优先 ​

开始学 Markdown，不用急着背这些符号：

text
# 表示标题
** 表示粗体
- 表示列表

先想清楚自己在写什么。比如，原先排版时我们想的是：

这句话应该显示成 18 号黑体。

写 Markdown 时，想的是：

这句话是一级标题。

原先可能还会想：

这里需要缩进 20 像素。

现在改成：

这里是一段引用。

遇到代码也是一样。与其先想：

这里需要换成等宽字体并设置灰色背景。

不如先说明：

这里是一段代码。

一句话概括：

先描述内容是什么，再由工具决定内容如何显示。

1.6 本章小结 ​

如果一份内容要长期修改，还要交给 Git、程序、AI 或网站使用，Markdown 是个方便的选择。它用纯文本写出文档结构，正文也容易迁移。需要精确控制版面时，再用 Word、WPS 或专业排版工具。

下一章继续看：这种简单的写法为什么能流行这么久。