reStructuredText语法笔记¶
章节等级编号符号¶
一般来说，reST语法不规定什么符号作为几级标题，不过可以参考python文档的约定俗成的习惯顺序字符进行使用。
推荐的标题字符使用：¶
#, with overline, for parts（部分/篇章）*, with overline, for chapters（章节）=, for sections（节）-, for subsections（小节）^, for subsubsections（再小节/小小节）", for paragraphs（段落）备注
引文和代码块¶
使用缩进一段或几段文本来实现类似 markdown 文档中 > 的效果。
可以选择这两种实现方式：
+使用 :: 将文本块转换为代码块，保留源文本格式¶
This is a normal text paragraph. The next paragraph is a code sample::
It is not processed in any way, except
that the indentation is preserved.
It can span multiple lines.
This is a normal text paragraph again.
其渲染结果为:
This is a normal text paragraph. The next paragraph is a code sample:
It is not processed in any way, except
that the indentation is preserved.
It can span multiple lines.
This is a normal text paragraph again.
+不使用 :: 将文本块作为普通段落处理¶
This is a normal text paragraph. The next paragraph is a code sample
It is not processed in any way, except
that the indentation is removed.
It can span multiple lines.
This is a normal text paragraph again.
其渲染结果为:
This is a normal text paragraph. The next paragraph is a code sample
It is not processed in any way, except that the indentation is removed.
It can span multiple lines.
This is a normal text paragraph again.
插入图片¶
行间图片：¶
使用 image 指令插入行间图片，其格式如下（仅列举常用参数）：
.. image:: [相对路径/]icon.png
:alt: [图标描述]
:width: [强制指定宽度](24px/50%/...)
:height: [强制指定高度](24px/50%/...)
:align: [文中对齐方式]("left", "center", "right"...)
:target: [图片的点击链接](_blank / https://example.com)
示例：
代码示例：
这是第一段文字，将在后面插入一个居中的图片，仅限制高度等比例缩放：
.. image:: 语法笔记-img/B站图标示例.png
:alt: 测试图片-链接到B站
:height: 100px
:align: center
:target: https://www.bilibili.com/
以上是示例图片，到本行本示例结束。
渲染效果：
这是第一段文字，将在后面插入一个居中的图片，仅限制高度等比例缩放：
以上是示例图片，到本行本示例结束。
行内图片：¶
若要在段落文本内行内插入图片（而非独占一行），可以通过 || 符号定义 「替换引用」 实现。具体步骤如下：
1. 定义行内图片占位符所使用的图片:¶
在文档中任一位置（通常放在文档开头或专门的替换引用区），使用如下格式定义图片替换引用：
.. |占位符标识符| image:: [相对路径/]img.png
:alt: [图片描述]
:width: [强制指定宽度](24px/50%/...)
:height: [强制指定高度](24px/50%/1em...)
:align: [行内对齐方式]("top", "middle", "bottom", "baseline"...(仅测试了"middle"))
:target: [图片的点击链接](_blank / https://example.com)
1. 在段落文本中通过占位符 |[占位符标识符]| 插入图片:¶
这是包含行内图片的文本示例： |占位符标识符|，图片将与文字在同一行显示。
示例：
代码示例：
这是第一段文字，将在本句结尾插入一个垂直居中的图片:|占位符标识符1|;
图片高度被限制为一倍行高，图片将在本行后定义。
.. |占位符标识符1| image:: 语法笔记-img/GitHub_icon.png
:alt: 测试图片-链接到 "https://github.com/"
:height: 1em
:align: middle
:target: https://github.com/
以上示例到本行本示例结束。
渲染效果：
这是第一段文字，将在本句结尾插入一个垂直居中的图片:
;
图片高度被限制为一倍行高，图片将在本行后定义。
以上示例到本行本示例结束。
Admonition 指令¶
reStructuredText 提供多种预定义的警告指令（Admonitions），用于突出显示特定类型的内容。
各指令的功能和适用场景¶
指令名称 |
功能说明 |
典型使用场景 |
|---|---|---|
|
中性补充信息，不强调重要性或风险 |
附加说明、背景知识、扩展解释 |
|
建议或优化实践，强调实用性 |
推荐技巧、效率提升方法 |
|
提示可能被忽略的细节 |
隐藏功能、快速操作、便捷选项 |
|
强调关键信息，需特别注意 |
必须遵循的规则、核心概念 |
|
警示潜在风险（中等严重性） |
功能异常风险、兼容性问题 |
|
比 warning 更严重，可能导致数据丢失 |
数据修改操作、临时性限制 |
|
最高级别危险警告 |
硬件损坏、不可逆数据损失 |
|
指出错误场景或常见误区 |
错误示例、调试建议、反模式 |
|
需要主动关注的内容 |
易混淆点、需人工确认的步骤 |
示例用法¶
基础语法示例¶
.. note::
This is a **note** admonition.
- 支持多行内容
- 可包含 **强调** 等格式
.. warning:: 直接使用简写语法
内容从第二行开始缩进
渲染效果：
备注
This is a note admonition. - 支持多行内容 - 可包含 强调 等格式
警告
直接使用简写语法 内容从第二行开始缩进
带标题的高级用法¶
.. admonition:: 自定义标题（扩展用法）
:class: attention
通过组合 ``admonition`` 指令和 CSS 类，
可以模拟标准警告样式
.. danger:: 格式化硬盘！
**操作不可逆**，请确认：
1. 已备份重要数据
2. 已关闭所有应用程序
渲染效果：
自定义标题（扩展用法）
通过组合 admonition 指令和 CSS 类，
可以模拟标准警告样式
危险
格式化硬盘！ 操作不可逆，请确认：
已备份重要数据
已关闭所有应用程序
Admonition 指令支持嵌套其他 reST 元素（列表、代码块等）,支持使用 :class: 选项可自定义样式。
不同 Admonition指令 渲染样式参考：¶
1. note
示例程序：
.. note::
这是一个 "note" 指令。
渲染效果：
备注
这是一个 "note" 指令。
2. tip
示例程序：
.. tip::
这是一个 "tip" 指令。
渲染效果：
小技巧
这是一个 "tip" 指令。
3. hint
示例程序：
.. hint::
这是一个 "hint" 指令。
渲染效果：
提示
这是一个 "hint" 指令。
4. important
示例程序：
.. important::
这是一个 "important" 指令。
渲染效果：
重要
这是一个 "important" 指令。
5. warning
示例程序：
.. warning::
这是一个 "warning" 指令。
渲染效果：
警告
这是一个 "warning" 指令。
6. caution
示例程序：
.. caution::
这是一个 "caution" 指令。
渲染效果：
小心
这是一个 "caution" 指令。
7. danger
示例程序：
.. danger::
这是一个 "danger" 指令。
渲染效果：
危险
这是一个 "danger" 指令。
8. error
示例程序：
.. error::
这是一个 "error" 指令。
渲染效果：
错误
这是一个 "error" 指令。
9. attention
示例程序：
.. attention::
这是一个 "attention" 指令。
渲染效果：
注意
这是一个 "attention" 指令。