第八章 Markdown 格式转换

一份 article.md，有时要放到网页上，有时要交给同事用 Word 修改，也可能需要导出 PDF 打印。内容整理成电子书后，还可以再生成 EPUB；反过来，收到别人改过的 Word，也常常需要转回 Markdown。

本章会反复用到下面这个小文件：

# Markdown 转换练习

这是一份用于测试的文档。

- Word
- HTML

[Pandoc 官网](https://pandoc.org/)

文件生成了，只能说明转换跑完了。标题、段落、列表有没有保住，图片路径还能不能用，PDF 的字体和分页是否合适，都得打开结果看一遍。我们要做的，就是从同一份内容生成不同格式，并弄清楚转换时哪些信息会变。

8.1 Markdown 内容源

Markdown 不一定是最终交付物。很多时候，它只是内容的源文件：先把标题、正文和代码写好，再交给其他工具生成网页、PDF、Word 或 EPUB。

写作 → Markdown → HTML → 网站
写作 → Markdown → PDF
写作 → Markdown → Word
Markdown → EPUB → 电子书

比如这段 Markdown 已经标出了标题、正文和代码块：

# Python 入门

Python 是一种编程语言。

## 环境检查

执行：

```bash
python --version
```

转换工具能据此生成 HTML 标题、Word 标题样式、PDF 标题或 EPUB 章节。Markdown 负责说明内容结构，具体怎么呈现，则由目标格式和工具决定。

8.2 常见格式

HTML

Markdown 和 HTML 的结构比较接近。Markdown 的一级标题 # Python 可以写成 <h1>Python</h1>；段落、强调和列表也有对应的 HTML 元素：

# Python
## Python 的特点

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

Python 是一种编程语言。
**重要内容**，*强调内容*。

- Python
- Java

<p>Python 是一种编程语言。</p>
<p><strong>重要内容</strong>，<em>强调内容</em>。</p>
<ul>
  <li>Python</li>
  <li>Java</li>
</ul>

有序列表也能对应到 <ol> 和 <li>：

1. 安装
2. 配置
3. 启动

像 VitePress、MkDocs、Hugo、Docusaurus 这类工具，会读取 Markdown，生成 HTML 页面，再组织成网站。因此写 chapter01.md 时，读者在浏览器里看到的通常是生成后的网页，不是 Markdown 源文。

HTML 也能转回 Markdown。简单的标题和段落通常很好处理：

<h1>Python</h1>
<p>Python 是一种编程语言。</p>

# Python

Python 是一种编程语言。

但网页里的布局可能复杂得多，例如侧栏、网格、浮动元素和各种交互。Markdown 没有对应的布局语法，回转时也就很难得到完全一样的页面。

PDF

PDF 的版面比较固定，适合发送资料、课程讲义、报告、打印和归档。Markdown 本身不规定 PDF 页面长什么样，所以通常要通过编辑器、浏览器或转换工具生成。

用编辑器导出

很多 Markdown 编辑器都有“导出 PDF”功能。比如在 Typora 里打开 article.md，从“文件 → 导出”选择 PDF，保存为 article.pdf。生成后打开文件，看看中文字体、列表和分页。导出成功只说明文件生成了，打印效果还得自己确认。

从浏览器打印

如果 Markdown 已经通过 VitePress 等工具变成网页，可以在浏览器里选择“打印”，再另存为 PDF：

Markdown → VitePress → 网页 → 浏览器打印 → PDF

打印前先看网页上的标题、图片和代码块，导出后再检查页边距和分页。浏览器采用网页样式，结果可能和编辑器直接导出的 PDF 不一样。

DOCX

报告、作业、方案、课程材料常常要求交付 .docx。Markdown 转 Word 时，标题、段落和列表通常能对应到 Word 的标题样式、正文和列表：

# 项目报告

## 项目目标

完成系统开发。

## 技术方案

- FastAPI
- Vue
- PostgreSQL

这里的 #、## 和列表标记提供了结构，转换工具据此安排 Word 样式。简单内容一般转换得比较自然。

Word 也可以转成 Markdown。例如，Word 里有“Python”标题、“安装”小标题和一段正文，转回来可能是：

# Python

## 安装

下载 Python。

麻烦在于 Word 能表达很多 Markdown 没有对应语法的东西：字体颜色和字号、文本框、页眉页脚、分栏、图文环绕、复杂表格、精确分页等。一个蓝色、居中、20 号的标题，转成 Markdown 后可能只剩 # 标题。内容结构还在，视觉样式却未必能留下。

EPUB

EPUB 常用于小说、技术书、教程和课程手册。书的内容通常由章节、段落、图片、链接和目录组成，这些都可以在 Markdown 中组织：

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

转换工具可以根据标题整理章节、目录和导航：

# 第一章

正文。

## 第一节

正文。

因此，Markdown 很适合作为电子书的内容源。生成 EPUB 后仍要用阅读器打开检查，尤其是中文、目录和图片。

8.3 Pandoc 命令

Markdown 可以转成 HTML、PDF、DOCX、EPUB、LaTeX、RTF 等格式，能转哪些、效果怎么样，要看所用工具。Pandoc 是常见的文档转换工具之一，可以把它理解成格式之间的转换器：

输入格式 → 解析 → 内部文档结构 → 输出格式

它不只支持 Markdown。例如可以从 Markdown 生成 DOCX，也能把 DOCX 转回 Markdown。不同格式表达能力有差别，所以支持转换不代表每种内容都能原样保留。

转成 Word

先按 Pandoc 官方安装说明完成安装，再在终端运行：

pandoc --version

确认能看到版本信息后，进入本章开头 article.md 所在目录，执行：

pandoc article.md -o article.docx

这里 article.md 是输入文件，article.docx 是输出文件。打开生成的 Word，核对标题、段落和列表。

转成 HTML

pandoc article.md -s -o article.html

-s 会生成带页面头部和正文的完整 HTML 文件。省略它时，Pandoc 默认输出适合嵌入其他页面的 HTML 片段。生成后打开 article.html，看看标题、段落和列表是否正常。

转成 EPUB

EPUB 可以在 Markdown 文件开头写书名、作者和语言等信息。新建 book.md：

---
title: Python 入门
author: 正心
lang: zh-CN
---

# 第一章 环境准备

检查 Python 版本。

# 第二章 第一个程序

输出 Hello, Python!。

然后运行：

pandoc book.md -o book.epub

用 EPUB 阅读器打开 book.epub，检查书名、中文、章节目录和正文。之后若在书里加入图片，也要确认图片随文件一起显示。

从 DOCX 转回 Markdown

先把前面生成的 article.docx 转回来：

pandoc article.docx -o article_roundtrip.md

打开 article_roundtrip.md，和原文件对照标题、列表和链接。若 Word 文档里有图片，可以用 --extract-media 把媒体文件提取出来：

pandoc report.docx --extract-media=media -o report.md

图片等文件会放进 media 目录，Markdown 中的引用也会相应调整。打开 report.md，再检查图片文件和路径是否可用。复杂 Word 排版仍可能无法完整保留。

8.4 转换质量

把 Word 转成 Markdown，再转回 Word，通常得不到一份完全一样的文件。可以把格式转换想成翻译：目标格式没有对应的表达方式时，只能近似处理、简化，或者丢掉那部分信息。

从 Markdown 转到 Word 或 HTML，往往比较顺利。标题、正文和列表都能对应到目标格式里的结构；反过来，如果 Word 里有文字环绕图片、复杂表格、页眉页脚、艺术字、分栏、脚注布局、文本框和精确分页，Markdown 就没有一一对应的语法。

Markdown → 标题、正文、列表等结构
Word → 结构 + 字体、布局、分页等排版信息

这也是 Markdown 更适合作为内容源，而不是万能排版交换格式的原因。

图片和资源路径

Markdown 的图片语法只保存说明文字和文件路径，图片本身仍是单独的文件：

![示例](./images/demo.png)
![远程示例](https://example.com/demo.png)

从 Word 转换时，使用媒体提取选项后可能得到这样的目录：

report.md
media/
├── image1.png
├── image2.jpg
└── image3.png

Markdown 再通过相对路径引用图片，例如 ![示例](./media/image1.png)。这里的文件名只是示意，实际路径以转换结果为准。长期保存的文档，核心图片最好和 Markdown 一起放在自己的项目里；远程图片可能被删除、改地址，或者无法访问。

内容结构和视觉样式

转换时可以分别检查两件事：内容结构是否保留，视觉样式是否符合要求。比如下面这段 Markdown 转到 Word 后，通常能保留“Python”是一级标题、下一句是正文；但具体字体是微软雅黑还是宋体、标题是黑色还是蓝色，要看 Word 模板和转换设置。

# Python

Python 是一种编程语言。

结果验收

交付前先看结构和资源是否齐全，再根据用途检查版面。逐像素一致通常不是 Markdown 转换的目标；更重要的是标题、段落、列表、代码、图片、链接和表格都能正常使用。

结果	至少检查
HTML	能否独立打开；标题、列表和链接是否正确
PDF	中文字体、图片、页边距和分页
DOCX	标题样式、列表与图片；回转时检查媒体文件和路径
EPUB	书名、章节目录、中文和图片

发现问题后，先分清是内容结构、资源路径还是目标格式的样式，再决定要改 Markdown、转换参数还是交付模板。

Markdown 的适用范围

Markdown 适合很多以内容为主的文档，但复杂合同排版、杂志和宣传册、大量合并单元格的报表、严格分页的公文或复杂论文版式，可能更适合 Word、LaTeX、InDesign 等专业工具。这些场景需要精确控制页面布局，光有清楚的内容结构不够。

有些工具会通过 LaTeX 把 Markdown 转成 PDF：

Markdown → Pandoc → LaTeX → PDF

这不代表 Markdown 和 LaTeX 是一回事。Markdown 更方便写作和表达基本结构；LaTeX 更擅长专业排版、数学公式、论文和出版。它们可以配合使用，各自负责擅长的部分。

简单说，Markdown 保存标题、正文、列表、代码、图片和链接；转换工具再把这些内容交给网页、打印、办公编辑或电子书阅读器使用。内容和最终呈现分开处理，正是 Markdown 适合维护多种交付格式的地方。

8.5 多格式交付

如果同一份内容要发布成网页、PDF、Word 和 EPUB，分别维护四份文件很容易改漏。改一句话，就得在每个版本里改一次，时间久了内容也会对不上。

把 Markdown 当作唯一的内容源，可以按需生成不同版本：

             ┌─ HTML
Markdown ────┼─ PDF
             ├─ Word
             └─ EPUB

也就是常说的 Single Source of Truth（单一内容源）。一门有 100 章的课程，如果 Markdown、Word、PDF 和网页都各自维护，修改成本很快就会堆起来；统一维护源文件，再生成各类交付物，日常更新会省心不少。

技术文档发布

例如，项目文档可以按主题拆成多个 Markdown 文件：

docs/
├── introduction.md
├── installation.md
├── usage.md
└── api.md

平时修改 Markdown，用 Git 保存版本；需要在线阅读时，通过 VitePress 生成网站；需要 PDF 时用相应转换工具，需要 Word 时用 Pandoc 生成 DOCX。这样正文只维护一份，各种格式从它生成。

AI 辅助转换

AI 可以帮忙整理 Word 正文、修正标题层级、清理格式、调整表格，或者把 Markdown 改成适合 Word 报告的结构。它能理解内容并重新组织表达；Pandoc 则按规则解析格式、转换文档结构。两者用途不太一样，可以配合使用。

比如 Word 的标题格式乱了，AI 可以根据上下文判断哪些内容更像一级或二级标题，再整理成 Markdown。不过，复杂分页、精确字体、专业排版和复杂表格仍需要专门的文档工具，也要人工检查转换结果。

课程交付

以一本 Python 教程为例，源文件可以按章节存放：

book/
├── 01_intro.md
├── 02_variable.md
├── 03_list.md
└── 04_function.md

日常用 VS Code 或 Typora 编写，Git 管理修改；在线阅读时交给 VitePress 生成网站，打印讲义时导出 PDF，交付给学校或公司时用 Pandoc 生成 Word，需要电子书时再生成 EPUB。同一份内容就能进入几种不同的交付流程。

8.6 小结

Markdown 可以生成 HTML、PDF、Word 和 EPUB。Markdown 到 HTML 的结构映射比较直接；PDF 通常需要经过编辑器、浏览器或其他转换工具；Markdown 转 Word 适合以 Markdown 写作、以 DOCX 交付；Word 转 Markdown 则要留意复杂排版和图片资源。Pandoc 可以完成不少常见格式之间的转换，例如：

pandoc article.md -o article.docx

转换并不保证无损。简单结构从 Markdown 转到复杂格式通常比较顺利，复杂排版回到简单格式时更容易丢失字体、分页、表格和布局信息。把 Markdown 当作结构化内容源，再按场景生成网页、PDF、Word 或 EPUB，通常更容易维护。