第七章 Markdown 工具选型

第 04 章完成了一份 README.md 学习笔记。现在有三个后续任务：一边修改 Python 代码一边维护笔记，请同伴审阅修改，最后把内容发布成文档网站。该用一个工具完成全部工作，还是让不同工具负责不同环节？

能处理 .md 文件的工具包括：

代码编辑器
Markdown 编辑器
知识管理软件
代码托管平台
文档网站工具
AI 工具

它们承担的任务并不相同：编辑器负责写和预览，GitHub 负责仓库协作，VitePress 负责生成网站；知识管理工具和 AI 工具还可以参与整理、审查内容。一个工具能打开 .md 文件，只说明它能读取文本，还不能说明它能完成预览、协作或发布。

本章要解决的问题是：根据任务选择工具，并确认每一步需要的 Markdown 能力。 后文始终以这份 README.md 为线索。

接下来会依次看开发 IDE、写作和知识管理工具、GitHub、VitePress 与 AI 工具，最后再比较它们各自适合承担什么任务。

7.1 支持层级

先看最简单的情况。假设有个文件：

article.md

内容是：

# Markdown 入门

Markdown 是一种轻量级标记方式。

## 特点

- 简单
- 纯文本
- 易于迁移

它本质上只是文本，所以记事本、Vim、VS Code、PyCharm、Typora、Obsidian 都能打开：

记事本
Vim
VS Code
PyCharm
Typora
Obsidian

即使软件不认识 Markdown，也能把它当普通文本编辑。最基础的支持就是：

能够编辑纯文本
↓
就能够编辑 Markdown

真正拉开差距的，是软件能不能识别 Markdown 语法，并在此基础上提供预览、扩展或完整工作流。

能力层级

后面比较工具时，可以用这五层来描述它们支持 Markdown 的程度：

第一层：

纯文本编辑

只要能编辑文本即可。

第二层：

Markdown 语法识别

例如：

• 标题高亮；
• 粗体高亮；
• 链接识别；
• 代码块高亮。

第三层：

Markdown 预览

能够把：

# 标题

显示成真正的标题效果。

第四层：

扩展 Markdown

例如：

• 表格；
• 任务列表；
• Mermaid；
• 数学公式；
• Frontmatter。

第五层：

围绕 Markdown 建立完整工作流

例如：

Obsidian
↓
知识管理

VitePress
↓
文档网站

GitHub
↓
项目协作

这只是能力划分，不是工具排名。VitePress 主要负责发布网站，不必承担日常编辑；编辑器能预览，也不代表目标网站支持相同扩展。

回到 README.md：先确定本次要做的是编辑、检查显示、请人审阅，还是发布网站，再看哪个工具负责这一步。

7.2 开发工具

VS Code

VS Code 是常见的代码编辑器，用它写 Markdown 不需要另开软件。

例如打开：

README.md

以后，可以直接编写：

# 项目名称

## 安装

```bash
pip install fastapi
```

编辑时，VS Code 会识别：

• 标题；
• 链接；
• 粗体；
• 代码块。

项目文档

它的优势不在于写长文有多舒服，而在于 Markdown 能和代码放在同一个项目里管理：

例如：

fastapi-project/
├── app/
│   └── main.py
├── docs/
│   ├── installation.md
│   └── routing.md
├── README.md
└── pyproject.toml

我们可以同时编辑：

Python
Markdown
JSON
YAML
HTML
CSS
JavaScript

代码、配置和文档都在一个工作区里，开发者不用来回切换。

本地预览

VS Code 也能把源码渲染成预览页，过程大致是：

Markdown 源码
      ↓
VS Code Preview
      ↓
渲染结果

打开第 04 章的 README.md，在 VS Code 中打开 Markdown 预览。修改一个标题并保存，核对源码和预览是否同时更新；再检查链接、图片与代码块的显示。

因此它很适合维护这些项目文档：

• README；
• 技术文档；
• 项目说明；
• GitHub 文档；
• 开发笔记。

插件扩展

插件也能补上不少 Markdown 功能，例如：

Markdown lint
目录生成
Mermaid
数学公式
粘贴图片
格式化
文档检查

它的组合优势是：

基础 Markdown
+
开发工具
+
插件生态
+
Git

所以对程序员尤其顺手。

适用边界

如果只是想安静地写篇长文，VS Code 未必最舒服，毕竟它首先是代码编辑器。

你通常会直接看到 Markdown 源码：

## 标题

**重点内容**

它会一直让你看到这些标记；如果不想看到标记、只想专注写作，可以考虑 Typora。

简单说：

程序员
技术文档
项目 README

非常适合 VS Code。

而：

纯写作
长文章
不想看到标记符号

可能更适合 Typora。

JetBrains IDE

PyCharm、WebStorm 和 IntelliJ IDEA 也都能直接编辑 Markdown。

例如一个 Python 项目：

project/
├── README.md
├── docs/
│   └── guide.md
└── app/
    └── main.py

在 PyCharm 里就能：

写 Python
+
写 Markdown
+
管理 Git

工程文档

项目文档通常和源代码放在同一个 Git 仓库里，常见的有：

README.md
CHANGELOG.md
CONTRIBUTING.md
docs/*.md

所以对 IDE 来说，Markdown 不只是写文章的格式，也是项目文档的一部分。

代码旁的文档

比如写 FastAPI 时，你可能一边改：

app/main.py

一边补充 docs/routing.md。这时留在 IDE 里改最省事，可以这样理解：

VS Code / JetBrains
↓
Markdown 是开发项目的一部分

而不是：

Markdown 是整个软件的中心

Typora 和 Obsidian 则把重心放在文档本身。

7.3 写作与知识库

Typora

Typora 把重点放在写作体验上，和 VS Code 这类代码编辑器不太一样。

传统 Markdown 编辑器经常是：

左边：源码
右边：预览

用传统的左右分栏预览时，你会看到：

# Markdown 入门

一侧是源码，另一侧是排版结果。Typora 更接近所见即所得：

编辑
≈
最终显示效果

实时排版

比如输入：

# Python 入门

在代码编辑器里，标题标记 # 往往会一直显示；Typora 则会弱化标记，让你更专注于标题本身：

#

输入 Markdown 标记后，它会直接呈现对应的视觉效果。

想写这些内容时，这种排版方式比较轻松：

• 写文章；
• 写教程；
• 写课程；
• 写学习笔记。

适用场景

不想折腾插件、打开就写，或希望边写边看排版的人，通常会觉得 Typora 顺手。它不像 VS Code 那样侧重：

代码
调试
Git
项目工程

重心更多放在文档本身。

扩展支持

Typora 除了基础 Markdown，通常也会支持很多现代写作中常见的能力，例如：

表格
任务列表
代码块
数学公式
Mermaid 等图表

Typora 的图表功能需要先在“偏好设置 → Markdown”中启用 Diagrams；检查数学公式和 Mermaid 时，应以当前设置下的预览为准。

Typora 支持这些语法，不代表其他 Markdown 平台也支持。含数学公式或 Mermaid 的文档，换到简单渲染器里可能会显示成原始文本。

导出

Typora 也能把 Markdown 导出成其他文档格式：

Markdown
↓
其他文档格式

Markdown
↓
PDF

写完就要导出、发给别人时，它通常比代码编辑器更顺手：

Markdown 写作
↓
导出
↓
发送给别人

Obsidian

Obsidian 也用 Markdown，但更像是建在 Markdown 文件上的知识管理系统。它适合管理几百、几千篇笔记，并把它们连起来；Typora 则更像一款文档编辑器。

本地文件

例如一个知识库：

notes/
├── Python.md
├── FastAPI.md
├── Flask.md
└── Docker.md

库里的笔记仍是普通的 .md 文件；即使以后不用 Obsidian，通常也能用其他工具继续打开：

VS Code
Typora
Vim
其他 Markdown 工具

笔记关联

普通 Markdown 可以写：

[FastAPI](./FastAPI.md)

Obsidian 还提供了非常方便的内部链接方式，例如：

[[FastAPI]]

于是可以形成：

Python
  ↓
FastAPI
  ↓
Pydantic

再配合：

反向链接
知识图谱
标签
属性
嵌入

这些链接、标签和嵌入能帮你把笔记组织成个人知识网络。

插件扩展

插件还能继续补充功能，例如：

日记
任务管理
数据库式视图
图表
日历
模板
自动化
AI

但用得越多，跨工具迁移时越要检查专属语法和插件内容：

[[FastAPI]]

Obsidian 能识别这个链接，其他工具却可能只把它当普通文本。

Typora 与 Obsidian

可以这样区分：

Typora
↓
重点：写好一篇文档

而：

Obsidian
↓
重点：管理很多文档之间的关系

只写一篇教程，Typora 往往更直接。

要把这些主题和项目记录连成长期知识库时：

Python
FastAPI
Docker
Linux
AI
课程笔记
项目记录

Obsidian 会更合适。

7.4 GitHub

很多人第一次看到渲染后的 Markdown，就是在 GitHub。开源项目里的 README.md 通常会直接显示在项目首页。

例如：

# My Project

## Installation

```bash
pip install my-project
```

GitHub 会把这段源码显示成结构清晰的网页内容。

使用场景

GitHub 的核心是代码和开发协作，Markdown 的纯文本特性正好适合这个场景：

• 是纯文本；
• 适合 Git；
• 方便比较改动；
• 可以直接和代码一起保存。

所以它很适合用来写：

README
Issue
Pull Request
讨论
项目说明
贡献指南

README.md

典型的项目目录可能长这样：

my-project/
├── README.md
├── LICENSE
├── src/
└── tests/

其中的 README.md 通常会介绍：

• 项目是什么；
• 有什么功能；
• 如何安装；
• 如何运行；
• 如何贡献。

Markdown 因此成了开源项目说明中非常常见的格式。

GFM

GitHub 在基础 Markdown 上使用 GFM（GitHub Flavored Markdown），并增加了不少适合协作的写法：

表格
任务列表
删除线
自动链接

GitHub 网页中的 Markdown 文件还支持数学公式和 Mermaid 图表。它们属于 GitHub 平台提供的渲染能力，不能仅凭 GFM 规范推断其他工具也会显示相同效果。

因此，GitHub 页面上的效果来自几层能力叠加：

CommonMark 基础规则
       ↓
GFM 扩展
       ↓
GitHub 平台能力

协作审阅

GitHub 不太适合替代 Typora 来写长文章；它更擅长把 Markdown、Git 和协作流程放在一起：

Markdown
+
Git
+
Issue
+
Pull Request
+
Code Review

同伴修改 docs/install.md 时，Git 会把差异标出来：

docs/install.md

- 旧内容
+ 新内容

在 Review 里就能逐条审阅。沿用开头的 README.md 时，可以分别检查仓库页面的渲染效果和修改差异：前者方便读者核对页面，后者方便同伴审阅。

7.5 VitePress

VitePress 的角色不太一样：它把 Markdown 文档构建成可发布的网站。

例如：

docs/
├── index.md
├── python.md
└── fastapi.md

经过 VitePress 构建以后，可以变成：

文档网站

大致流程是：

Markdown
↓
VitePress
↓
HTML / 网站

文档网站

技术文档经常包含：

标题
目录
代码
链接
导航
搜索（配置后）
上一页 / 下一页

这些都是文档网站常见的组成部分。搜索需要另配搜索提供方；把 .md 文件交给 VitePress，并不会自动出现搜索入口。

例如：

# FastAPI

## 安装

```bash
pip install fastapi
```

## 第一个应用

Markdown 写正文，VitePress 负责页面和网站功能：

页面布局
导航
侧边栏
代码高亮
搜索（配置后）
主题
网站构建

扩展机制

VitePress 建在 Vue 和 Vite 之上，因此 Markdown 中还能使用：

Vue 组件
Frontmatter
自定义容器
主题
插件

可以把它理解成：

Markdown
+
Vue
+
Vite
=
VitePress

适用场景

它适合用来做：

技术文档
框架文档
课程网站
开发手册
产品文档
个人技术站

已有的 .md 课程文件也能直接作为网站内容来源，同一份文件可以继续编辑，也可以发布。

沿用 README.md 时，先确认它已作为站点页面纳入导航，再检查网页上的标题、代码块、图片和链接。若站点配置了搜索，还要确认该页面能被检索到。这里核对的是发布结果，与编辑器中的本地预览是两个检查点。

7.6 AI 工具

AI 工具也经常用 Markdown 组织回答。比如 ChatGPT、Claude、Gemini、DeepSeek 等服务可能会输出：

## 原因

1. 原因一
2. 原因二

```python
print("Hello")
```

界面可能把这些内容显示成排版后的文本，但具体保存格式取决于所用服务。需要继续在编辑器中维护时，应检查复制或导出的内容是否仍是可编辑的 Markdown。

结构化内容

Markdown 的层次清楚，模型容易分辨标题、列表和代码：

结构清晰
符号简单
代码容易区分
方便生成
方便继续处理

所以可以把任务和格式要求直接写清楚，例如：

# 任务

生成 Python 教程。

## 要求

- 使用 Python 3.12；
- 不使用第三方库；
- 包含代码示例。

## 输出格式

使用 Markdown。

这样的 Prompt 通常很容易理解。

处理方式

AI 工具不一定是传统的 Markdown 编辑器，更像是一个能读写 Markdown 的助手：

Markdown 输入
+
Markdown 理解
+
Markdown 生成

例如：

你提供 Markdown
↓
AI 理解结构
↓
AI 修改
↓
再次输出 Markdown

它可以帮忙：

• 生成；
• 改写；
• 总结；
• 审查；
• 重组；
• 转换。

文件协作

例如课程项目：

course/
├── chapter01.md
├── chapter02.md
└── chapter03.md

AI 可以按这个顺序参与：

读取 chapter01.md
↓
审查
↓
修改
↓
重新生成 Markdown

处理结果仍是 Markdown，方便检查差异，再保存回项目文件。

7.7 工具对照

这些工具做的事差别很大，却都能围绕同一份 .md 文件工作：

VS Code
Typora
Obsidian
GitHub
VitePress
AI

Markdown 刚好兼顾了三件事：

足够简单
↓
人容易写

足够结构化
↓
程序容易处理

足够开放
↓
工具容易集成

文件流转

比如有一份：

python.md

它可以这样使用：

VS Code
↓
程序员修改

也可以：

Typora
↓
写作者修改

还可以：

Obsidian
↓
作为知识笔记

然后：

GitHub
↓
版本管理

最终：

VitePress
↓
发布成网站

甚至：

AI
↓
审查和改写

于是同一个文件可以贯穿：

写作
↓
知识管理
↓
版本管理
↓
AI 处理
↓
网站发布

能力对照

先按任务比较，再检查功能需要什么条件：

工具	主要任务	可直接承担	另需确认
VS Code	代码旁的文档编辑	编辑 Markdown、内置预览	扩展语法的插件与预览配置；最终发布平台的显示效果
JetBrains IDE	项目内的文档编辑	启用 Markdown 插件后编辑与预览	IDE、插件与预览设置
Typora	专注写作与导出	编辑、预览，导出 PDF / HTML	图表功能开关；其他导出格式所需工具
Obsidian	笔记关联与管理	编辑笔记、内部链接与预览	专属链接和插件内容迁移后的显示效果
GitHub	仓库协作与网页展示	README、GFM、公式、Mermaid 的网页渲染及改动审阅	文件所在页面与实际渲染结果
VitePress	文档网站生成	将 Markdown 组织成网站页面	网站配置与部署；搜索提供方及扩展插件
AI 工具	内容生成与审查	理解、生成或修改 Markdown 文本	导出格式、原文件保存方式与目标平台预览

这里的“直接承担”指工具本身在相应使用环境中的职责，并不保证同一段扩展语法跨工具显示一致。软件版本、插件、配置和目标平台仍需逐项核对。

以开头的 README.md 为例，可以得到一条明确的选用路径：

1. 在 VS Code 或正在使用的 JetBrains IDE 中修改文件，同时检查本地预览。
2. 文件进入 GitHub 仓库后，检查仓库页面的显示结果和改动差异，再请同伴审阅。
3. 需要独立文档网站时，用 VitePress 组织并发布页面，核对导航、链接，以及已配置的搜索功能。

如果主要任务是写长文或管理互相关联的笔记，再考虑 Typora 或 Obsidian。AI 可以帮忙起草和审查，最终内容记得保存回可维护的 .md 文件。

场景选型

开发文档

如果日常主要写：

Python
FastAPI
JavaScript
Vue
Docker
Linux

而且文档要和代码放在一起维护，VS Code 或 JetBrains IDE 会更顺手：

VS Code
JetBrains IDE

你可以在同一工作区里处理代码、Markdown 和 Git：

代码
+
Markdown
+
Git

一起处理。

长文写作

如果主要需求是：

写文章
写教程
写课程
尽量不看 Markdown 符号

Typora 更适合，它会让你把注意力放在内容和排版效果上。

个人知识库

如果需要管理：

几百篇笔记
知识关系
学习资料
项目记录
日常笔记

Obsidian 更擅长：

Markdown
+
链接
+
知识管理

开源项目

如果重点是：

README
Issue
Pull Request
协作
版本管理

GitHub 是典型的 Markdown 协作环境，这时要熟悉 GFM。

文档网站

手头有不少 Markdown 文件，准备把它们做成：

技术文档网站
课程网站
产品说明网站

VitePress 这类工具就很合适，核心流程很简单：

Markdown
↓
网站

AI 协作

AI 可以和上面的工具搭配使用：

Typora / VS Code / Obsidian
            +
            AI

例如：

VS Code
↓
编写 Markdown
↓
AI 审查
↓
Git
↓
VitePress

或者：

Obsidian
↓
记录笔记
↓
AI 总结
↓
继续形成知识库

把 AI 当作 Markdown 工作流里的助手就好。

7.8 工具组合

如果你既要：

• 写编程课程；
• 写技术文章；
• 管理知识；
• 使用 AI；
• 发布文档网站；

可以按这个方式组合：

                Markdown
                   │
      ┌────────────┼────────────┐
      ↓            ↓            ↓
 VS Code       Obsidian       Typora
 开发文档       知识管理         长文写作
      │            │            │
      └────────────┼────────────┘
                   ↓
                  Git
                   ↓
                  AI
                   ↓
               VitePress
                   ↓
                文档网站

不用每个人都装齐这些工具。关键是 Markdown 不属于某一款软件，它是不同工具共用的内容格式。

选择标准

两个软件都标着“支持 Markdown”，定位也可能完全不同：

Typora
↓
重点是写作

Obsidian
↓
重点是知识管理

VitePress
↓
重点是发布网站

GitHub
↓
重点是开发协作

VS Code
↓
重点是代码与项目

挑工具时，先想自己主要要做什么，再看它支不支持 Markdown。

组合使用

Typora 和 Obsidian 哪个更好？VS Code 和 Typora 又该选哪个？很多时候不用二选一：它们处理的底层文件都是 .md。

例如：

docs/
├── markdown.md
├── python.md
└── fastapi.md

今天用 Typora 写：

markdown.md

明天用 VS Code 修改：

fastapi.md

最后把整个目录交给 Git 管理即可。

语法依赖

功能越专门的工具，往往越会加入自己的扩展：

Obsidian
→ 双向链接

VitePress
→ Vue 组件

某些文档工具
→ 自定义容器

某些数学工具
→ 特殊公式语法

这些扩展很好用，只是会影响跨平台兼容性，需要在功能和可迁移性之间取舍：

功能丰富
↕
可迁移性

长期内容

如果内容准备长期保存，例如：

课程
技术文档
博客原稿
公开教程
知识资料

核心正文尽量使用这些通用结构：

标题
段落
列表
链接
图片
代码
引用
表格（目标平台支持时）

双向链接、组件、特殊容器等：

双向链接
组件
特殊容器
专属语法

留给确实需要它们的地方，之后迁移时就少一些返工。

7.9 小结

选工具先看要做什么，可以先记住这组对应关系：

写代码
↓
VS Code / JetBrains

写文章
↓
Typora

管理知识
↓
Obsidian

开发协作
↓
GitHub

发布网站
↓
VitePress

智能处理
↓
AI

这些工具不必互相替代：一份 Markdown 内容可以在编辑、写作、知识管理、协作和发布环节之间流转。下一章会讲格式转换，看看 Markdown 怎样变成 HTML、PDF、Word、EPUB，以及 Pandoc 在其中能做什么。