Paragraph

Paragraphs consist of blocks of left-aligned text with no markup indicating any other body element. Blank lines separate paragraphs from each other and from other body elements. Paragraphs may contain inline markup. The reST:

Paragraphs consist of blocks of left-aligned text with no markup indicating any other body element. Blank lines separate paragraphs from each other and from other body elements. Paragraphs may contain inline markup.

Bullet Lists

• This is the first bullet list item. The blank line above the first list item is required; blank lines between list items (such as below this paragraph) are optional.
• This is the first paragraph in the second item in the list.This is the second paragraph in the second item in the list. The blank line above this paragraph is required. The left edge of this paragraph lines up with the paragraph above, both indented relative to the bullet.
  • This is a sublist. The bullet lines up with the left edge of the text blocks above. A sublist is a new list so requires a blank line above and below.

• This is the third item of the main list.

This paragraph is not part of the list.

The reST:

- This is the first bullet list item.  The blank line above the
first list item is required; blank lines between list items
(such as below this paragraph) are optional.

- This is the first paragraph in the second item in the list.

  This is the second paragraph in the second item in the list.
  The blank line above this paragraph is required.  The left edge
  of this paragraph lines up with the paragraph above, both
  indented relative to the bullet.

  - This is a sublist.  The bullet lines up with the left edge of
    the text blocks above.  A sublist is a new list so requires a
    blank line above and below.

- This is the third item of the main list.

  This paragraph is not part of the list.

Enumerated Lists

• Item 1 initial text.
  • Item 1a.
  • Item 1b.

• • Item 2a.
  • Item 2b.

The reST:

1. Item 1 initial text.

   a) Item 1a.
   b) Item 1b.

2. a) Item 2a.
   b) Item 2b.

Definition Lists

Each definition list item contains a term, optional classifiers, and a definition.

term 1

Definition 1.

term 2

Definition 2, paragraph 1.

Definition 2, paragraph 2.

term 3

Definition 3.

term 4

Definition 4.

The reST:

term 1
  Definition 1.

term 2
    Definition 2, paragraph 1.

    Definition 2, paragraph 2.

term 3
    Definition 3.

term 4
    Definition 4.

Field Lists

Field lists are mappings from field names to field bodies

The reST:

:Date: 2001-08-16
:Version: 1
:Authors: - Me
          - Myself
            - I
:Indentation: Since the field marker may be quite long, the second
   and subsequent lines of the field body do not have to line up
   with the first line, but they must be indented relative to the
   field name marker, and they must line up with each other.
:Parameter i: integer

Option Lists

TODO

Literal Block

No markup processing is done within a literal block. It is left as-is, and is typically rendered in a monospaced typeface:

This is a typical paragraph. An indented literal block follows.

for a in [5,4,3,2,1]:   # this is program code, shown as-is
    print a
print "it's..."
# a literal block continues until the indentation ends

The reST:

::

  for a in [5,4,3,2,1]:   # this is program code, shown as-is
      print a
  print "it's..."
  # a literal block continues until the indentation ends

Quoted literal blocks are unindented contiguous blocks of text where each line begins with the same non-alphanumeric printable 7-bit ASCII character. For example

John Doe wrote:

>> Great idea!
>
> Why didn't I think of that?

The reST:

John Doe wrote::

>> Great idea!
>
> Why didn't I think of that?

Line Blocks

Line blocks are useful for address blocks, verse (poetry, song lyrics), and unadorned lists, where the structure of lines is significant. Line blocks are groups of lines beginning with vertical bar (|) prefixes. This example illustrates the nesting of line blocks, indicated by the initial indentation of new lines:

Take it away, Eric the Orchestra Leader!

A one, two, a one two three four
Half a bee, philosophically,
must, ipso facto, half not be.
But half the bee has got to be,
vis a vis its entity.  D'you see?
But can a bee be said to be
or not to be an entire bee,
when half the bee is not a bee,
due to some ancient injury?
Singing...

The reST:

| A one, two, a one two three four
|
| Half a bee, philosophically,
|     must, *ipso facto*, half not be.
| But half the bee has got to be,
|     *vis a vis* its entity.  D'you see?
|
| But can a bee be said to be
|     or not to be an entire bee,
|         when half the bee is not a bee,
|             due to some ancient injury?
|
| Singing...

Block Quotes

A text block that is indented relative to the preceding text, without preceding markup indicating it to be a literal block or other content, is a block quote. All markup processing (for body elements and inline markup) continues within the block quote.

This is an ordinary paragraph, introducing a block quote.

"It is my business to know things.  That is my trade."

The reST:

This is an ordinary paragraph, introducing a block quote.

  "It is my business to know things.  That is my trade."

  -- Sherlock Holmes

Footnotes

The footnote above can be referred to with 1_ or [1]_.

Footnotes may be auto-numbered, as in  [#]_.

manually numbered : [2]_, anonymous auto-numbered: [#]_, and labeled auto-numbered: [#label]_.

Here is a symbolic footnote reference: [*]_.

Citations

Here is a citation reference: [CIT2002]. The reST:

Here is a citation reference: [CIT2002]_.

Hyperlink Targets

Named hyperlink targets are expressed:

.. _hyperlink-name: link-block

Anonymous hyperlink targets consist of an explicit markup start (.. ), two underscores, a colon, whitespace, and a link block; there is no reference name. Example:

.. __: anonymous-hyperlink-target-link-block
or
__ anonymous-hyperlink-target-link-block

There are three types of hyperlink targets: internal, external, and indirect.

Internal hyperlink targets have empty link blocks, example:

.. _target:

External hyperlink targets have a URI-reference or email address in their link blocks:

.. _Python: https://www.python.org
.. _Write to me: jdoe@example.com

Indirect hyperlink targets have a hyperlink reference in their link blocks:

.. _one: two_
.. _two: three_
.. _three:

Directives

Directives are a way of adding support for new constructs.

Image Directive

Below an image rendered using image directive

The reST:

.. image:: /static/images/svelte.png
   :height: 50px
   :width: 100 px
   :scale: 100
   :loading: embed
   :alt: alternate text
   :align: right

Figure Directive

A graphic with a caption may be included with the "figure" directive.

The legend consists of all elements after the caption. In this case, the legend consists of this paragraph.

The reST:

.. figure:: /static/images/svelte.png
   :alt: map to buried treasure

   This is the caption of the figure (a simple paragraph).

   The legend consists of all elements after the caption.  In this
   case, the legend consists of this paragraph.

.. ERROR::

 Connection to the primary database failed. The application cannot retrieve required data and must shut down. Check the network configuration and database status.

Substitution

A substitution definition block contains an embedded inline-compatible directive (such as "image" or "replace") without the leading dots.

Image substitution example: The symbol must be used on containers used to dispose of medical waste.

The reST:

Image substitution example: The |biohazard| symbol must be used on containers used to dispose of medical waste.

.. |biohazard| image:: /static/images/Biohazard_symbol.svg
   :height: 6
   :width: 6
   :scale: 100

Replace substitution example: This example is not so clever

The reST:

Replace substitution example:         This example is |stupid|
.. |stupid| replace:: not so clever

Other supported substitutions include "unicode", "date", etc.

Emphasis

This is emphasis, which is normally rendered as italics. The reST:

This is *emphasis*, which is normally rendered as italics.

Strong Emphasis

This is strong emphasis, normally rendered as boldface. The reST:

This is **strong emphasis**, normally rendered as boldface.

Interpreted Text

This is interpreted text. The rendering is application-dependent. It can be used for things like program identifiers or index entries. The reST:

This is `interpreted text`. The rendering is application-dependent. It can be used for things like program identifiers or index entries.

Inline Literal

This is inline literal text, normally rendered as monospaced. Spaces and punctuation are preserved. The reST:

This is ``inline literal`` text, normally rendered as monospaced. ``Spaces      and punctuation are preserved``.

Substitution Reference

This text includes a inserted text via substitution. The content is defined elsewhere and inserted here. The reST:

This text includes a |substitution reference|. The content is defined elsewhere and inserted here.
.. |substitution reference| replace:: **inserted text via substitution**

Hyperlink References

This is a simple reference. It's a one-word hyperlink. The reST:

This is a simple reference_. It's a one-word hyperlink.

This is a phrase reference which requires backticks because it contains spaces. The reST:

This is a `phrase reference`_ which requires backticks because it contains spaces.

This is an anonymous reference. This is another anonymous one. They link to targets in the order they are defined. The reST:

This is an anonymous__ reference. This is another anonymous__ one. They link to targets in the order they are defined.

The reST for reference targets:

.. _reference: https://docutils.sourceforge.io/
.. _phrase reference: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html

.. __: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#anonymous-hyperlinks
.. __: https://www.python.org

Hyperlink reference may directly embed a target URI as in  `Python home page `_.

This `link `_ is an alias to the link above.

Standalone hyperlinks `__init__ <http:example.py.html#__init__>`__

Inline Internal Targets

Oh yes, the Norwegian Blue. What's, um, what's wrong with it? The reST:

Oh yes, the _`Norwegian Blue`.  What's, um, what's wrong with it?

Footnote References

This is a footnote reference ¹. The reST:

Please RTFM [1]_.

The footnote target reST:

.. [1] Read The Fine Manual

Citation References

This text includes a citation reference [CIT2002]. Citations are similar to footnotes but are labeled with text. The reST:

This text includes a citation reference [CIT2002]_. Citations are similar to footnotes but are labeled with text.

Standalone Hyperlinks

Two forms of standalone hyperlinks are recognized:

One, URIs with known schemes such as

tel:+48-816-555-1212

urn:isbn:0-486-27557-4

news:comp.infosystems.www.servers.unix

https://john.doe@www.example.com:123/forum/questions/?tag=networking&order=newest#top

Second, Standalone email addresses, such as

someone@somewhere.com

The reST:

Two forms of standalone hyperlinks are recognized:

One, URIs with known schemes such as

tel:+48-816-555-1212

urn:isbn:0-486-27557-4

news:comp.infosystems.www.servers.unix

https://john.doe@www.example.com:123/forum/questions/?tag=networking&order=newest#top

Second, standalone email addresses, such as

someone@somewhere.com