========
基础语法
========
简要说明 reStructuredText 的基础语法

标题/章节
----------
标题是用于划分文档的依据。在reST中，你可以使用 ``#=-~:'"^_*+<>`` 来构建标题，将单行文本缀以下划符号则构成标题，如下所示。

标题的大小与符号无关，与符号的出现顺序有关。在本文档库（toad-rdc）中，习惯以 ``=`` 作为一级标题， ``-`` 和 ``~`` 作为二级和三级标题。同时也可以被隐式超链接引用，详细转至 `超链接`_

你也可以使用双划线来构建标题。

.. code-block:: rst

    ==========
    一级标题（双划线风格）
    ==========
    
    二级标题
    -----------
    
    三级标题
    ~~~~~~~

.. warning:: 虽然你可以继续使用四、五、六级标题，但在写文档时应避免出现四级更深的标题！

段落
--
reST 最基础被识别到的结构那肯定是段落了，一个简单的段落用于和空行与其他结构进行分隔的文字区域。

你可以通过使用换行来划分出不同的部分，只要它们中间没有空行时便会被解析为一个段落。这些文本行需要有相同的缩进，即左边缘一定要对齐。如果有缩进的段落，则在语义上表示一段引言。如下：

.. code-block:: rst

    一个简单的段落。
    这一行和上一行之间没有空行且相同缩进，所以这两是同一段。
    
        如果加上缩进，那么渲染时这一段也会缩进，通常表示引言。
    
            -- 马克•吐温
    
    缩进完成后又变成了正常的段落

一个简单的段落。
这一行和上一行之间没有空行且相同缩进，所以这两是同一段。

    如果加上缩进，那么渲染时这一段也会缩进，通常表示引言。

        -- 马克•吐温
   
缩进完成后又变成了正常的段落

一般情况下下应使用 4 个空格来表达缩进。如果需要保留段落的换行情况时，可以使用管道符 `|` 创建 line block：

.. code-block:: rst

    | 我是段落
    | 没有空行
    | 但也有换行效果，也在同一段落中

| 我是段落
| 没有空行
| 但也有换行效果，也在同一段落中

内联标记
-----------
在段落和其他结构内可以使用内联标记来为某个片段的文本标记语义。这和 Markdown 语法差不多。但它们实际上是 reST 角色简写，详细请看本文档组的 角色

1. 斜体（着重）
    .. code-block:: rst

        *着重*

    *着重*
#. 粗体（强调）
    .. code-block:: rst

        *强调*

    *强调*
#. 字面量
    .. code-block:: rst

        ``字面量``

    ``字面量``

列表
----------
这里提供两种风格用于表示列表的方法。

一种为无序列表，使用``*``、``-``或``+``作为项目符号：
.. code-block:: rst

    -  无序列表 1
    
    +  无序列表 2
    
    *  无序列表 3

-  无序列表 1

+  无序列表 2

*  无序列表 3

一种为有序列表，允许使用 数字、字母和罗马字符 + 点/英文右括号 或用英文括号全部括住 作为项目符号，这些可以根据你的偏好选择。

.. code-block:: rst

    1.  数字有序
    
    2)  有序带右括号
    
    (3)  有序全括住
    
    i.  有序 一
    
    II.  有序 贰
    
    c.  字母有序

1.  数字有序

2)  有序带右括号
    
(3)  有序全括住

i.  有序 一
    
II.  有序 贰

c.  字母有序

.. tip:: 无序符号的项目符号可以混用，只要保持缩进即可。

    但有序符号的项目符号不可以混用，并且需要保持编号连续。不过可以通过使用 ``#`` 来自动推导序号：

    .. code-block:: rst

        1. good
        #. 666
        #. 入室桂

    1. good
    #. 666
    #. 入室桂
    
可以通过增减缩进关系来表达嵌套关系

.. code-block:: rst

    1. 嵌套
        a. 列表
            -  再嵌个无序列表
        #. 1
        #. ✓8
    #. 非嵌套列表
    #. 上同

1. 嵌套
    a. 列表
        -  再嵌个无序列表
    #. 1
    #. ✓8
#. 嵌套回来
#. 无敌了

超链接
----------
一个超链接分为两部分，引用和靶标：

.. code-block:: rst

    引用部分要在名称后面加下划线：链接_
    如名称包含空格，则需要使用反引号扩住：`链 接`_
    
    靶标部分的下划线在名称前面：
    
    .. _链接: https://www.baidu.com
    
    如果留空，则会将靶标引至下一个块元素

允许将引用和靶标写在同一处

.. code-block:: rst

    `名称 <https://www.baidu.com>`_
    即 `name <target>`_，前者显示名称、后者则作为靶标

靶标也有内联形式

.. code-block:: rst

    _`我是靶标`，而引用会引至前面的 `我是靶标`_

隐式超链接可以引至标题

.. code-block:: rst

    转至 `标题/章节`_

转至 `标题/章节`_

只要其满足Url的正常形式，那么都会在渲染的最后流程中被渲染成超链接：

.. code-block:: rst

    -  https://cn.bing.com
    -  http://www.bilibili.com

-  https://cn.bing.com
-  http://www.bilibili.com

分割线
---
任何四个以上的重复横线将会渲染为分割线：

.. code-block:: rst

    ----

----

接下来就是一些常用命令了