唠唠闲话

reStructuredText (reST) 是一种在 Python 社区和文档编写中广泛使用的标记语言。相比 Markdown,reST 更具灵活性和强大功能,提供了更多的语法规则和特性。

下边我们通过对比,学习 reST 和 Markdown 的主要语法规则。

reST 与 Markdown 比较

1. 标题

reST:使用下划线的样式定义标题,支持多种符号

1
2
3
4
5
6
7
8
9
===========
一级标题
===========

二级标题
-----------

三级标题
~~~~~~~~~~~

每种符号类型只要不与其他级别的符号混用,就可以继续定义更多的标题级别。约定上,用 =, -, ~, *, + 代表一到五级标题,且一级标题通常会用上下划线进行强调。

使用 # 符号定义标题,最多支持六级标题。

1
2
3
# 一级标题
## 二级标题
### 三级标题

2. 段落和换行

RST 段落之间使用空行分隔,段内换行需要显式使用反斜杠 \

1
2
3
4
5
这是一个段落。

这是另一个段落。
这一行很长,\
需要换行。

Markdown 段落之间使用空行分隔,段内换行只需在行尾添加两个空格。

1
2
3
4
5
这是一个段落。

这是另一个段落。
这一行很长,
需要换行。

3. 列表

reST 支持有序和无序列表,使用不同符号或数字定义,用法与 Markdown 类似。

1
2
3
4
5
- 无序列表项
- 无序列表项

1. 有序列表项
2. 有序列表项

4. 链接

reST 支持内联和外部链接。

内联链接语法:

1
`链接文本 <URL>`_

示例:

1
访问 `Google <https://www.google.com>`_ 以获取更多信息。

匿名引用语法:

1
2
3
链接文本_

.. _链接文本: URL

示例:

1
2
3
访问 Google_ 以获取更多信息。

.. _Google: https://www.google.com

外部链接语法:

1
2
3
这是一个外部引用 `链接文本 <reference>`_。

.. _reference: https://www.example.com

Markdown 使用方括号和圆括号定义链接。

1
这是一个[链接](https://www.example.com)。

链接和图片这两部分的规则较复杂,我们将在后续详细介绍。

5. 图片

reST 使用 .. image:: 指令来嵌入图片,允许添加多个配置项,如 alt 文本、widthheight 等。

1
2
3
4
.. image:: /path/to/image.jpg
:alt: 备选文字
:width: 200px
:height: 100px

Markdown 则简单使用 ![]() 语法。

1
![备选文字](/path/to/image.jpg)

Markdown 本身不直接支持图片属性配置,但可以通过 HTML 标签实现更复杂的需求。

1
<img src="/path/to/image.jpg" alt="备选文字" width="200" height="100">

6. 引用块

reST 有功能强大的指令体系来创建不同类型的专用块,比如注意事项、警告等。

1
2
3
4
5
.. note::
这是一个注意事项块。

.. warning::
这是一个警告块。

Markdown 通过 > 创建标准的引用块,但不支持类型区分。

1
> 这是一个引用块。

7. 代码块

reST 支持多种方式定义代码块,最常用的是使用 .. code:: 指令,指定编程语言,以实现语法高亮。

使用 :: 指令创建简单的代码块。

1
2
3
4
::

这是一个代码块
可以包含多行代码。

使用 .. code:: language 指令指定代码的语言,启用语法高亮。

1
2
3
4
.. code:: python

def hello():
print("Hello, world!")

还可以在其他指令中嵌入代码块,例如在列表或表格中。

1
2
3
4
- 这是一个包含代码块的列表项::

def hello():
print("Hello, world!")

Markdown 使用三个反引号来创建代码块,并可指定语言。

1
2
3
4
\```python
def hello():
print("Hello, world!")
\```

代码块 plus

RST 支持嵌入其他语言,如 HTML、LaTeX、或者数学公式:

1
2
3
4
5
.. math::

\sum_{i=1}^{n} i = \frac{n(n+1)}{2}

这是行内数学公式 :math:`E = mc^2`。

Html 代码块:

1
2
3
.. raw:: html

<p>这是一个 HTML 段落。</p>

LaTeX 代码块:

1
2
3
4
5
.. raw:: latex

\begin{equation}
E = mc^2
\end{equation}

Markdown 支持直接引用 HTML 和使用 $$ 插入 LaTeX 代码。

8. 表格

reST 提供了灵活的表格定义方式,支持复杂的布局,比如

1
2
3
4
5
6
7
+------------+------------+
| Header 1 | Header 2 |
+============+============+
| Cell 1 | Cell 2 |
+------------+ |
| Cell 3 | |
+------------+------------+

或者 CSV 表格:

1
2
3
4
5
6
.. csv-table:: CSV 表格
:header: "Header 1", "Header 2"
:widths: 20, 20

"Cell 1", "Cell 2"
"Cell 3", "Cell 4"

Markdown 表格较为简洁,通常用于简单布局。

1
2
3
4
| Header 1   | Header 2   |
|------------|------------|
| Cell 1 | Cell 2 |
| Cell 3 | Cell 4 |

9. 定义列表

reST 提供了创建定义列表的功能,通常用于术语和定义的描述,通过简单的缩进和符号定义。

1
2
3
术语
定义内容1
定义内容2

Markdown 最近的版本中也支持了类似的定义列表。

1
2
3
术语
: 定义内容1
定义内容2

注意,如果不加 : 默认不会产生缩进。

10. 强调和内联代码

reST 使用 *** 对文本进行强调,使用反引号 `` 定义内联代码。

1
2
*斜体* **加粗**
``内联代码``

Markdown 用法相同,但内联代码只使用一个反引号。

1
2
*斜体* **加粗**
`内联代码`

11. 脚注

reST 支持复杂的脚注系统,允许在文档中创建和引用详细的注释。脚注在 reST 中通过以下几种方式使用:

  1. 基本脚注

    • 在文档中插入脚注引用,使用方括号和下划线(例如 [1]_)。
    • 在文档的任意位置定义脚注内容,使用 .. [label] 格式。
    1
    2
    3
    这是一个脚注引用 [1]_。

    .. [1] 这是脚注的内容。
  2. 自动编号脚注

    • 通过使用 # 代替脚注编号,reST 会自动进行编号。
    1
    2
    3
    这是一个自动编号脚注 [#]_。

    .. [#] 这是自动编号脚注的内容。
  3. 引用编号脚注

    • 允许在脚注中引用其他脚注,创建复杂的注释层级。
    1
    2
    3
    4
    这是一个脚注引用 [1]_,还有另一个引用 [2]_。

    .. [1] 第一个脚注的内容。
    .. [2] 参见脚注 [1]_ 以获取更多信息。
  4. 匿名脚注

    • 使用 .. [#] 定义匿名脚注,适用于文档中多处引用相同内容的情况。
    1
    2
    3
    这是一个匿名脚注引用 [#]_。

    .. [#] 这是匿名脚注的内容。

12. 注释

reST 使用 .. 开头的行来定义注释,不会在最终渲染的文档中显示。

1
.. 注释内容

Markdown 使用 <!----> 定义注释。

1
<!-- 注释内容 -->

小结

简单来说,reST 提供了更多的功能和灵活性,尤其适合于技术和学术文档的需求,而 Markdown 则因其简洁性更受青睐于博客和简单文档的撰写。