Markdown 转 RST:把现有文档接进 Sphinx 与 Read the Docs

写 Python 项目文档的人,迟早会撞上同一道墙:你的 README、笔记、wiki 全是 Markdown,但文档站用 Sphinx 构建,它读的是 .rst 文件。直接把 Markdown 粘进去,标题不显示,行内代码失了义,链接变成一行看得见的字面文字。问题不在于 RST 难,而在于它和 Markdown 在几个关键点上写法完全不同。把这几处差异理清楚,迁移就只是机械活。

为什么 Python 生态偏爱 RST

Sphinx 是官方 Python 文档和绝大多数 Read the Docs 站点背后的工具。它读 .rst,渲染出 HTML、PDF 和 ePub。RST 比 Markdown 多了一整套东西:.. code-block:: 和 .. image:: 这类指令、交叉引用、角色系统。一个几百页的文档树需要在章节之间互相跳转、自动生成目录、按语言高亮代码,这些 Markdown 原生都给不了。所以大型项目宁可接受 RST 略陡的语法,换来这套表达能力。

标题:RST 用符号下划线,不用井号

这是最直观的差异。Markdown 用 # 数量定层级,RST 完全没有前导符号。你把标题文字写在一行,下一行写一排同一个标点字符当下划线,这排下划线至少要和标题一样宽。

一个具体的对照。Markdown 这样写:

# Setup

转成 RST 是:

Setup
=====

注意下面那五个等号,正好对齐「Setup」五个字母。# 通常映射成等号下划线,## 映射成连字符,### 映射成波浪号。哪个符号代表哪一级,按它在文档里首次出现的顺序决定。新手最容易栽的坑是下划线写短了:只要短一个字符,Sphinx 就报警告,甚至直接丢掉这个标题。

行内代码、链接、代码块的三处差异

第二处是行内代码。Markdown 用单反引号包,` value ;RST 用双反引号, `value 。这不是风格问题:RST 里单反引号是解释型文本角色,不是字面代码,粘进去含义会被悄悄改掉。

第三处是链接。Markdown 写 [文字](网址),RST 写成短语引用:一个反引号、链接文字、一个空格、尖括号里的网址、一个收尾反引号,最后加一个结尾下划线,得到 ` 文字 <网址>_ `。那个结尾下划线手写时极容易漏。

第四处是代码块。三个反引号加 python 的围栏,在 RST 里是 .. code-block:: python 指令,下面空一行,正文统一缩进三个空格。单独一行的图片 ![alt](网址) 则变成 .. image:: 网址 加一行 :alt: 选项。

把现成 Markdown 文档接进 Sphinx

我自己迁过一个项目的 README。它原本两百多行 Markdown,十几处行内代码、五六个链接、三个代码块。手动改第一遍我就放弃了:每个反引号要翻倍,每个链接要补尖括号和下划线,标题下划线还得数着字母对齐,改到一半必漏。后来我把整段 Markdown 丢进 Markdown 转 RST 转换器,一次粘贴拿到对齐好的 RST,直接落进 docs/intro.rst,Sphinx 构建零警告。

实际工作流我会这样安排:

用 Markdown 起草,因为编辑器预览的是它,想得更快。
定稿后整页过一遍转换,拿到 RST。
把 RST 提交进 Sphinx 仓库,本地跑一次 sphinx-build 确认无警告。
推到 Read the Docs,它会自动渲染这些 .rst 文件。

如果你的方向反过来,手上是 RST 想转回更轻的格式,或者在两种标记之间来回搬运,可以配合 Markdown 转 HTML 之类的工具一起用,把同一份内容输出成不同目标。

小结

Markdown 转 RST 的难点集中在四处:标题改成符号下划线、行内码改双反引号、链接补尖括号和结尾下划线、代码块改 .. code-block:: 指令。把这四条记牢,迁移就不再是逐字符的折磨。剩下的列表、有序编号、引用块、粗体斜体,两种格式写法一致或接近,基本原样带过去。文档该用 Markdown 写就用 Markdown 写,交付前转成 Sphinx 要的 RST 即可,两边的好处都不丢。

Made by Toolora · Updated 2026-06-13