唠唠闲话
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]_
)。 - 在文档的任意位置定义脚注内容,使用
.. [label]
格式。
这是一个脚注引用 [1]_。 .. [1] 这是脚注的内容。
- 在文档中插入脚注引用,使用方括号和下划线(例如
-
自动编号脚注:
- 通过使用
#
代替脚注编号,reST 会自动进行编号。
这是一个自动编号脚注 [#]_。 .. [#] 这是自动编号脚注的内容。
- 通过使用
-
引用编号脚注:
- 允许在脚注中引用其他脚注,创建复杂的注释层级。
这是一个脚注引用 [1]_,还有另一个引用 [2]_。 .. [1] 第一个脚注的内容。 .. [2] 参见脚注 [1]_ 以获取更多信息。
-
匿名脚注:
- 使用
.. [#]
定义匿名脚注,适用于文档中多处引用相同内容的情况。
这是一个匿名脚注引用 [#]_。 .. [#] 这是匿名脚注的内容。
- 使用
12. 注释
reST 使用 ..
开头的行来定义注释,不会在最终渲染的文档中显示。
.. 注释内容
Markdown 使用 <!--
和 -->
定义注释。
<!-- 注释内容 -->
小结
简单来说,reST 提供了更多的功能和灵活性,尤其适合于技术和学术文档的需求,而 Markdown 则因其简洁性更受青睐于博客和简单文档的撰写。