一文搞懂 reST 和 Markdown 语法

唠唠闲话

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

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

reST 与 Markdown 比较

1. 标题

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

===========
一级标题
===========

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

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

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

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

# 一级标题
## 二级标题
### 三级标题

2. 段落和换行

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

这是一个段落。

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

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

这是一个段落。

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

3. 列表

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

- 无序列表项
- 无序列表项

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

4. 链接

reST 支持内联和外部链接。

内联链接语法：

`链接文本 <URL>`_

示例：

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

匿名引用语法：

链接文本_

.. _链接文本: URL

示例：

访问 Google_ 以获取更多信息。

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

外部链接语法：

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

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

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

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

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

5. 图片

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

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

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

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

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

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

6. 引用块

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

.. note::
    这是一个注意事项块。

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

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

> 这是一个引用块。

7. 代码块

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

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

::

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

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

.. code:: python

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

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

- 这是一个包含代码块的列表项::
    
    def hello():
        print("Hello, world!")

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

\```python
def hello():
    print("Hello, world!")
\```

代码块 plus

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

.. math::

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

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

Html 代码块：

.. raw:: html

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

LaTeX 代码块：

.. raw:: latex

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

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

8. 表格

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

+------------+------------+
| Header 1   | Header 2   |
+============+============+
| Cell 1     | Cell 2     |
+------------+            |
| Cell 3     |            |
+------------+------------+

或者 CSV 表格：

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

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

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

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

9. 定义列表

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

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

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

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

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

10. 强调和内联代码

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

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

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

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

11. 脚注

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

1. 基本脚注：

   • 在文档中插入脚注引用，使用方括号和下划线（例如 [1]_）。
   • 在文档的任意位置定义脚注内容，使用 .. [label] 格式。

   这是一个脚注引用 [1]_。
   
   .. [1] 这是脚注的内容。
   

2. 自动编号脚注：

   • 通过使用 # 代替脚注编号，reST 会自动进行编号。

   这是一个自动编号脚注 [#]_。
   
   .. [#] 这是自动编号脚注的内容。
   

3. 引用编号脚注：

   • 允许在脚注中引用其他脚注，创建复杂的注释层级。

   这是一个脚注引用 [1]_，还有另一个引用 [2]_。
   
   .. [1] 第一个脚注的内容。
   .. [2] 参见脚注 [1]_ 以获取更多信息。
   

4. 匿名脚注：

   • 使用 .. [#] 定义匿名脚注，适用于文档中多处引用相同内容的情况。

   这是一个匿名脚注引用 [#]_。
   
   .. [#] 这是匿名脚注的内容。
   

12. 注释

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

.. 注释内容

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

<!-- 注释内容 -->

---

小结

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