从 Markdown 到 reStructuredText

宗旨

reStructuredText 是一种易于阅读、所见即所得的纯文本标记语言，常被用于编写行内文档（譬如 Python 1 ），快速创建简单网页，或者作为独立文档存在。——David Goodger 2

1

Python 官方文档生成器 Sphinx 基于 reStructuredText 。

2

reStructuredText 标记语言主要贡献者之一。

reStructuredText 的最初目标是定义一种可被 Python 文档和其它格式使用的标记语法，这种语法应该做到既简单易读，同时又功能强大可满足其它专业需要。 reStructuredText 的预期目标是：

• 建立一套通用标准，使得纯文本发挥强大的表达能力

• 如有必要，纯文本可被转换为其它格式的结构化文档

兼容 HTML 语法

reStructuredText 开箱支持转换为其它多种格式，其被设计为“Output-format-neutral（输出格式中性）”，即：并不会明确“偏袒”于哪种输出格式。

rst 转换为其它格式

理所当然地，reStructuredText 提供了混合书写 HTML 语言的能力：

.. raw:: html

    <div class="ui steps">
        <div class="step">撰写 markup 文件</div>
        <div class="active step">添加 meta 信息</div>
        <div class="disabled step">提交 GitHub</div>
    </div>

输出结果为：

特殊字符转换

和 Markdown 一样，对于特殊字符 reStructuredText 会自动处理。你只需像正常字符那样书写就行。比如 4 < 5，版权所有 ©，Bill & Jobs……

段落和换行

和 Markdown 一样，reStructuredText 段落是由一个或多个连续的文本行组成。它的前后应该有一个以上的空行。

如果你有首行缩进、强行断行、段落空行等需求，可以查看 reStructuredText 的 “Line Blocks” 部分。

标题

reStructuredText 中的“标题”被称为“Sections”，一般在文字下方加特殊字符 3 以示区别：

Section Title H1
================

Section Title H2
----------------

Section Title H3
````````````````

3

推荐使用的字符：= - ` : . ' " ~ ^ _ * + #

特殊字符的重复长度应该大于等于标题（Sections）的长度。需要说明的是： reStructuredText 并不像 Markdown 那样，限定某一字符只表示特定的标题层级（比如 = 固定表示 H1 )。而是解析器将遇到的第一个特殊字符渲染为 H1 ，第二个其它特殊字符渲染为 H2 ……以此类推。

当然，在 reStructuredText 的日常使用中，仍然建议养成习惯使用固定的特殊符号，方便别人一看到 = 就知道这是一级标题。 除了 “Sections”外， reStructuredText 还支持“Title”和“SubTitle”，它们可以被配置为不在文档中出现。其实际作用更类似于“书名”，如《钢铁是怎样炼成的——保尔柯察金自传》。语法如下：

==================
 钢铁是怎样炼成的
==================

----------------
 保尔柯察金自传
----------------

区块引用

reStructuredText 的区块引用使用空格或制表符的方式，一般是 4 个空格。

Amet omnis animi doloribus.
Consectetur culpa veniam earum provident tempora saepe adipisci!
Ipsum quidem adipisci ab officia sed blanditiis, eum non. Eos dignissimos odit.

    当然嵌套也是可以的（中间加空行）：
    Consectetur assumenda eveniet nihil nemo recusandae, voluptas id, voluptates voluptatibus, quod harum recusandae cumque labore non?

渲染效果：

Amet omnis animi doloribus. Consectetur culpa veniam earum provident tempora saepe adipisci! Ipsum quidem adipisci ab officia sed blanditiis, eum non. Eos dignissimos odit.

当然嵌套也是可以的（中间加空行）： Consectetur assumenda eveniet nihil nemo recusandae, voluptas id, voluptates voluptatibus, quod harum recusandae cumque labore non?

列表

reStructuredText 支持有序列表和无序列表，语法与 Markdown 基本一致：

2. Consectetur est iure.
3. Adipisicing velit ad laborum libero.
   第二行
4. Sit atque atque aliquid assumenda voluptates.

   试着分段
   Libero provident quia temporibus deleniti quam.

- Amet sit magnam!
- Consectetur cum hic deserunt laudantium.
- Adipisicing impedit nulla aspernatur nam illo eos.

代码区块

与 Markdown 的 "Fenced Code Blocks" 非常相似，reStructuredText 将调用 pygments 进行语法高亮：

.. code:: python

   import sys
   print(sys.version)

渲染结果：

import sys
print(sys.version)

分割线

与 Markdown 语法基本一致：

-----------------

渲染结果：

链接

reStructuredText 的链接语法大体上也可以分为两类： 行内式 和 参考式 。一般推荐做法是：为了增强可读性尽量使用参考式，如果在一篇文档中多次引用该链接，则更是推荐使用参考式。

欢迎访问 reStructuredText_ 官方主页。

.. _reStructuredText: http://docutils.sf.net/

欢迎访问 `reStructuredText 结构化文本`_ 官方主页。

.. _`reStructuredText 结构化文本`: http://docutils.sf.net/

Python_ 是 `我最喜欢的编程语言`_ 。用英语来说，就是 `my favorite programming language`_ 。

.. _Python:
.. _`最喜欢的编程语言`:
.. _`my favorite programming language`: http://www.python.org/

<http://docutils.sf.net/>

`Python 编程语言 <http://www.python.org/>`_ 其实也有一些缺陷。

本小节内容应该与 `行内标记`_ 结合学习。

强调

与 Markdown 语法基本相同。参看 行内标记 。

图片

reStructuredText 使用指令（Directives)的方式来插入图片。指令（Directives）作为 reStructuredText 语言的一种扩展机制，允许快速添加新的文档结构而无需对底层语法进行更改。reStructuredText 开箱已经内置了一批常用指令，上文中使用的 raw 和 code 其实就是指令。指令的重要功能之一是可以添加选项以控制解析器对该元素的渲染方式，譬如让图片以两倍高宽居中进行展示：

.. image:: /images/nikola.png
   :align: center
   :width: 236px
   :height: 100px

渲染结果：

插入图片的另一种方法是使用 figure 指令。该指令与 image 基本一样，不过可以为图片添加标题和说明文字。两个指令共有的一个选项为 target ，可以为图片添加可点击的链接，甚至链接到另一张图片。那么结合 Nikola 博客的特定主题，就可以实现点击缩略图查看原图的效果：

.. figure:: /images/icarus.thumbnail.jpg
   :align: center
   :target: /images/icarus.jpg

   *飞向太阳*

渲染结果：

飞向太阳

行内标记

4

这是一个脚注，但是不一定要放到文章结尾。

CIT2002

这是一个引文，当然你也可以添加 链接 。

交叉参考

就像这样创建一个脚注 [#]_ 。

.. [#] 这里是 **脚注** 的 *文本* 。

请参阅我们去年发表在《自然》期刊上的文章 [NT202329]_

.. [NT202329] `用流体力学来研究猫究竟是固态的还是液态的 <https://www.invalid.org/somelink/>`_

Tables of Contents(TOC)

文档目录生成则使用了 reStructuredText 的指令（Directives） contents 。

.. contents:: 文档目录

渲染结果具体查看文档开头。 :: 后面的 文档目录 被用来指定目录块的标题，为空的话则默认为 Contents 。另外该指令可使用 depth 选项指定目录生成层级， local 指定仅生成本节及下层的目录列表。

表格（table）

+------------------------+------------+----------+----------+
| Header row, column 1   | Header 2   | Header 3 | Header 4 |
| (header rows optional) |            |          |          |
+========================+============+==========+==========+
| body row 1, column 1   | column 2   | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2             | Cells may span columns.          |
+------------------------+------------+---------------------+
| body row 3             | Cells may  | - Table cells       |
+------------------------+ span rows. | - contain           |
| body row 4             |            | - body elements.    |
+------------------------+------------+---------------------+

渲染结果：

这种表格语法被称为 Grid Tables 。如上所见， Grid Tables 支持跨行跨列。如果你使用的编辑器创建该表格有困难，reStructuredText 还提供 Simple Tables 表格语法：

=====  =====  ======
   Inputs     Output
------------  ------
  A      B    A or B
=====  =====  ======
False  False  False
True   True   True
=====  =====  ======

渲染结果：

此外，reStructuredText 还有两种表格指令（Directives）： list-table 和 csv-table 。分别以无序列表和 csv 数据（一般逗号分割）的方式创建表格，这里就不继续展开了。总体上来说，4 种表格的“纯手工”书写难度逐次降低。

数学公式

reStructuredText 的数学公式书写通过指令（Directives）： math 完成。如需网页上显示的话，则和其它所有标记语言一样需要引入 MathJax 或 KaTex js 库。

.. math::

   \alpha _t(i) = P(O_1, O_2, \ldots  O_t, q_t = S_i \lambda )

行内数学公式 则是通过 math role 实现的：

该圆的面积为 :math:`A_\text{c} = (\pi/4) d^2`.

渲染结果：

该圆的面积为 \(A_\text{c} = (\pi/4) d^2\).