reStructuredText Markup Specification

Blank Lines

Blank lines are used to separate paragraphs and other elements. Multiple successive blank lines are equivalent to a single blank line, except within literal blocks (where all whitespace is preserved). Blank lines may be omitted when the markup makes element separation unambiguous, in conjunction with indentation. The first line of a document is treated as if it is preceded by a blank line, and the last line of a document is treated as if it is followed by a blank line.

Indentation

Indentation is used to indicate -- and is only significant in indicating -- block quotes, definitions (in definition lists), and local nested content:

• list item content (multi-line contents of list items, and multiple body elements within a list item, including nested lists),

• the content of literal blocks, and

• the content of explicit markup blocks (directives, footnotes, ...).

Any text whose indentation is less than that of the current level (i.e., unindented text or "dedents") ends the current level of indentation.

Since all indentation is significant, the level of indentation must be consistent. For example, indentation is the sole markup indicator for block quotes:

This is a top-level paragraph.

    This paragraph belongs to a first-level block quote.

    Paragraph 2 of the first-level block quote.

Multiple levels of indentation within a block quote will result in more complex structures:

This is a top-level paragraph.

    This paragraph belongs to a first-level block quote.

        This paragraph belongs to a second-level block quote.

Another top-level paragraph.

        This paragraph belongs to a second-level block quote.

    This paragraph belongs to a first-level block quote.  The
    second-level block quote above is inside this first-level
    block quote.

When a paragraph or other construct consists of more than one line of text, the lines must be left-aligned:

This is a paragraph.  The lines of
this paragraph are aligned at the left.

    This paragraph has problems.  The
lines are not left-aligned.  In addition
  to potential misinterpretation, warning
    and/or error messages will be generated
  by the parser.

Several constructs begin with a marker, and the body of the construct must be indented relative to the marker. For constructs using simple markers (bullet lists, enumerated lists), the level of indentation of the body is determined by the position of the first line of text. For example:

- This is the first line of a bullet list
  item's paragraph.  All lines must align
  relative to the first line.

      This indented paragraph is interpreted
      as a block quote.

  Another paragraph belonging to the first list item.

 Because it is not sufficiently indented,
 this paragraph does not belong to the list
 item (it's a block quote following the list).

The body of explicit markup blocks, field lists, and option lists ends above the first line with the same or less indentation than the marker. For example, field lists may have very long markers (containing the field names):

:Hello: This field has a short field name, so aligning the field
        body with the first line is feasible.

:Number-of-African-swallows-required-to-carry-a-coconut: It would
    be very difficult to align the field body with the left edge
    of the first line.  It may even be preferable not to begin the
    body on the same line as the marker.

Document

Doctree element:

<document>

The top-level element of a parsed reStructuredText document is the "document" element. After initial parsing, the document element is a simple container for a document fragment, consisting of body elements, transitions, and sections, but lacking a document title or other bibliographic elements. The code that calls the parser may choose to run one or more optional post-parse transforms, rearranging the document fragment into a complete document with a title and possibly other metadata elements (author, date, etc.; see Bibliographic Fields).

Sections

Doctree elements:

<section>, <title>

Sections are identified through their titles, which are marked up with adornment: "underlines" below the title text, or underlines and matching "overlines" above the title. An underline/overline is a single repeated punctuation character that begins in column 1 and forms a line extending at least as far as the right edge of the title text. [6] Specifically, an underline/overline character may be any non-alphanumeric printable 7-bit ASCII character [7]. When an overline is used, the length and character used must match the underline. Underline-only adornment styles are distinct from overline-and-underline styles that use the same character. There may be any number of levels of section titles, although some output formats may have limits (HTML has 6 levels).

Rather than imposing a fixed number and order of section title adornment styles, the order enforced will be the order as encountered. The first style encountered will be an outermost title (like HTML <H1>), the second style will be a subtitle, the third will be a subsubtitle, and so on.

Below are examples of section title styles:

===============
 Section Title
===============

---------------
 Section Title
---------------

Section Title
=============

Section Title
-------------

Section Title
`````````````

Section Title
'''''''''''''

Section Title
.............

Section Title
~~~~~~~~~~~~~

Section Title
*************

Section Title
+++++++++++++

Section Title
^^^^^^^^^^^^^

When a title has both an underline and an overline, the title text may be inset, as in the first two examples above. This is merely aesthetic and not significant. Underline-only title text may not be inset.

A blank line after a title is optional. All text blocks up to the next title of the same or higher level are included in a section (or subsection, etc.).

All section title styles need not be used, nor need any specific section title style be used. However, a document must be consistent in its use of section titles: once a hierarchy of title styles is established, sections must use that hierarchy.

Each section title automatically generates a hyperlink target pointing to the section. The text of the hyperlink target (the "reference name") is the same as that of the section title. See Implicit Hyperlink Targets for a complete description.

Sections may contain body elements, transitions, and nested sections.

Transitions

Doctree element:

<transition>

Instead of subheads, extra space or a type ornament between paragraphs may be used to mark text divisions or to signal changes in subject or emphasis.

(The Chicago Manual of Style, 14th edition, section 1.80)

Transitions are commonly seen in novels and short fiction, as a gap spanning one or more lines, with or without a type ornament such as a row of asterisks. Transitions separate other body elements. A transition should not begin or end a section or document, nor should two transitions be immediately adjacent.

The syntax for a transition marker is a horizontal line of 4 or more repeated punctuation characters. The syntax is the same as section title underlines without title text. Transition markers require blank lines before and after:

Para.

----------

Para.

Unlike section title underlines, no hierarchy of transition markers is enforced, nor do differences in transition markers accomplish anything. It is recommended that a single consistent style be used.

The processing system is free to render transitions in output in any way it likes. For example, horizontal rules (<hr>) in HTML output would be an obvious choice.

Paragraphs

Doctree element:

<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.

Syntax diagram:

+------------------------------+
| paragraph                    |
|                              |
+------------------------------+

+------------------------------+
| paragraph                    |
|                              |
+------------------------------+

Bullet Lists

Doctree elements:

<bullet_list>, <list_item>

A text block which begins with a *, +, -, •, ‣, or ⁃, followed by whitespace, is a bullet list item (a.k.a. "unordered" list item). List item bodies must be left-aligned and indented relative to the bullet; the text immediately after the bullet determines the indentation. For example:

- 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.

Here are examples of incorrectly formatted bullet lists:

- This first line is fine.
A blank line is required between list items and paragraphs.
(Warning)

- The following line appears to be a new sublist, but it is not:
  - This is a paragraph continuation, not a sublist (since there's
    no blank line).  This line is also incorrectly indented.
  - Warnings may be issued by the implementation.

Syntax diagram:

+------+-----------------------+
| "- " | list item             |
+------| (body elements)+      |
       +-----------------------+

Enumerated Lists

Doctree elements:

<enumerated_list>, <list_item>

Enumerated lists (a.k.a. "ordered" lists) are similar to bullet lists, but use enumerators instead of bullets. An enumerator consists of an enumeration sequence member and formatting, followed by whitespace. The following enumeration sequences are recognized:

• arabic numerals: 1, 2, 3, ... (no upper limit).

• uppercase alphabet characters: A, B, C, ..., Z.

• lower-case alphabet characters: a, b, c, ..., z.

• uppercase Roman numerals: I, II, III, IV, ..., MMMMCMXCIX (4999).

• lowercase Roman numerals: i, ii, iii, iv, ..., mmmmcmxcix (4999).

In addition, the auto-enumerator, #, may be used to automatically enumerate a list. Auto-enumerated lists may begin with explicit enumeration, which sets the sequence. Fully auto-enumerated lists use arabic numerals and begin with 1.

The following formatting types are recognized:

• suffixed with a period: 1., A., a., I., i..

• surrounded by parentheses: (1), (A), (a), (I), (i).

• suffixed with a right-parenthesis: 1), A), a), I), i).

While parsing an enumerated list, a new list will be started whenever:

• An enumerator is encountered which does not have the same format and sequence type as the current list (e.g. 1., (a) produces two separate lists).

• The enumerators are not in sequence (e.g., 1., 3. produces two separate lists).

It is recommended that the enumerator of the first list item be ordinal-1 (1, A, a, I, or i). Although other start-values will be recognized, they may not be supported by the output format. A level-1 [info] system message will be generated for any list beginning with a non-ordinal-1 enumerator.

Lists using Roman numerals must begin with I/i or a multi-character value, such as II or XV. Any other single-character Roman numeral (V, X, L, C, D, M) will be interpreted as a letter of the alphabet, not as a Roman numeral. Likewise, lists using letters of the alphabet may not begin with I/i, since these are recognized as Roman numeral 1.

The second line of each enumerated list item is checked for validity. This is to prevent ordinary paragraphs from being mistakenly interpreted as list items, when they happen to begin with text identical to enumerators. For example, this text is parsed as an ordinary paragraph:

A. Einstein was a really
smart dude.

However, ambiguity cannot be avoided if the paragraph consists of only one line. This text is parsed as an enumerated list item:

A. Einstein was a really smart dude.

Examples of nested enumerated lists:

1. Item 1 initial text.

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

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

Example syntax diagram:

+-------+----------------------+
| "1. " | list item            |
+-------| (body elements)+     |
        +----------------------+

Definition Lists

Doctree elements:

<definition_list>, <definition_list_item>, <term>, <classifier>, <definition>

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

• A term is a simple one-line word or phrase. Escape a leading hyphen to prevent recognition as an option list item.

• Optional classifiers may follow the term on the same line, each after an inline : (space, colon, space). Inline markup is parsed in the term line before the classifier delimiters are recognized. A delimiter will only be recognized if it appears outside of any inline markup.

• A definition is a block indented relative to the term, and may contain multiple paragraphs and other body elements. There may be no blank line between a term line and a definition block (this distinguishes definition lists from block quotes). Blank lines are required before the first and after the last definition list item, but are optional in-between.

Example:

term 1
    Definition 1.

term 2
    Definition 2, paragraph 1.

    Definition 2, paragraph 2.

term 3 : classifier
    Definition 3.

term 4 : classifier one : classifier two
    Definition 4.

\-term 5
    Without escaping, this would be an option list item.

A definition list may be used in various ways, including:

• As a dictionary or glossary. The term is the word itself, a classifier may be used to indicate the usage of the term (noun, verb, etc.), and the definition follows.

• To describe program variables. The term is the variable name, a classifier may be used to indicate the type of the variable (string, integer, etc.), and the definition describes the variable's use in the program. This usage of definition lists supports the classifier syntax of Grouch, a system for describing and enforcing a Python object schema.

Syntax diagram:

+----------------------------+
| term [ " : " classifier ]* |
+--+-------------------------+--+
   | definition                 |
   | (body elements)+           |
   +----------------------------+

Field Lists

Doctree elements:

<field_list>, <field>, <field_name>, <field_body>

Field lists are used as part of an extension syntax, such as options for directives, or database-like records meant for further processing. They may also be used for two-column table-like structures resembling database records (label & data pairs). Applications of reStructuredText may recognize field names and transform fields or field bodies in certain contexts. For examples, see Bibliographic Fields or directive options below or the "meta" directive.

Field lists are mappings from field names to field bodies, modeled on RFC822 headers. A field name may consist of any characters, but colons (:) inside of field names must be backslash-escaped when followed by whitespace.[8] Inline markup is parsed in field names, but care must be taken when using interpreted text with explicit roles in field names: the role must be a suffix to the interpreted text. Field names are case-insensitive when further processed or transformed. The field name, along with a single colon prefix and suffix, together form the field marker. The field marker is followed by whitespace and the field body. The field body may contain multiple body elements, indented relative to the field marker. The first line after the field name marker determines the indentation of the field body. For example:

: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

The interpretation of individual words in a multi-word field name is up to the application. The application may specify a syntax for the field name. For example, second and subsequent words may be treated as "arguments", quoted phrases may be treated as a single argument, and direct support for the "name=value" syntax may be added.

Standard RFC822 headers cannot be used for this construct because they are ambiguous. A word followed by a colon at the beginning of a line is common in written text. However, in well-defined contexts such as when a field list invariably occurs at the beginning of a document (PEPs and email messages), standard RFC822 headers could be used.

Syntax diagram (simplified):

+--------------------+----------------------+
| ":" field name ":" | field body           |
+-------+------------+                      |
        | (body elements)+                  |
        +-----------------------------------+

:Status: $keyword: expansion text $

Option Lists

Doctree elements:

<option_list>, <option_list_item>, <option_group>, <option>, <option_string>, <option_argument>, <description>

Option lists map a program's command-line options to descriptions documenting them. For example:

-a         Output all.
-c arg     Output just arg.
--long     Output all day long.
/V         A VMS/DOS-style option.

-p         This option has two paragraphs in the description.
           This is the first.

           This is the second.
           Blank lines may be omitted between options
           (as above) or left in (as here and below).

--very-long-option  A VMS-style option.  Note the adjustment
                    for the required two spaces.

--an-even-longer-option
           The description can also start on the next line.

-2, --two  This option has two variants.

-f FILE, --file=FILE  These two options are synonyms; both have
                      arguments.

-f <[path]file>  Option argument placeholders must start with
                 a letter or be wrapped in angle brackets.

-d <src dest>    Angle brackets are also required if an option
                 expects more than one argument.

There are several types of options recognized by reStructuredText:

• Short POSIX options consist of one dash and an option letter.

• Long POSIX options consist of two dashes and an option word; some systems use a single dash.

• Old GNU-style "plus" options consist of one plus and an option letter ("plus" options are deprecated now, their use discouraged).

• DOS/VMS options consist of a slash and an option letter or word.

Please note that both POSIX-style and DOS/VMS-style options may be used by DOS or Windows software. These and other variations are sometimes used mixed together. The names above have been chosen for convenience only.

The syntax for short and long POSIX options is based on the syntax supported by Python's getopt.py module, which implements an option parser similar to the GNU libc getopt_long() function but with some restrictions. There are many variant option systems, and reStructuredText option lists do not support all of them.

Although long POSIX and DOS/VMS option words may be allowed to be truncated by the operating system or the application when used on the command line, reStructuredText option lists do not show or support this with any special syntax. The complete option word should be given, supported by notes about truncation if and when applicable.

Options may be followed by an argument placeholder, whose role and syntax should be explained in the description text. Either a space or an equals sign may be used as a delimiter between long options and option argument placeholders; short options (- or + prefix only) use a space or omit the delimiter. Option arguments may take one of two forms:

• Begins with a letter ([a-zA-Z]) and subsequently consists of letters, numbers, underscores and hyphens ([a-zA-Z0-9_-]).

• Begins with an open-angle-bracket (<) and ends with a close-angle-bracket (>); any characters except angle brackets are allowed internally.

Multiple option "synonyms" may be listed, sharing a single description. They must be separated by comma-space.

There must be at least two spaces between the option(s) and the description (which can also start on the next line). The description may contain multiple body elements. The first line after the option marker determines the indentation of the description. As with other types of lists, blank lines are required before the first option list item and after the last, but are optional between option entries.

Syntax diagram (simplified):

+----------------------------+-------------+
| option [" " argument] "  " | description |
+-------+--------------------+             |
        | (body elements)+                 |
        +----------------------------------+

Literal Blocks

Doctree element:

<literal_block>

A paragraph consisting of two colons (::) signifies that the following text block(s) comprise a literal block. The literal block must either be indented or quoted (see below). 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

This text has returned to the indentation of the first paragraph,
is outside of the literal block, and is therefore treated as an
ordinary paragraph.

The paragraph containing only :: will be completely removed from the output; no empty paragraph will remain.

As a convenience, the :: is also recognized at the end of any paragraph. If immediately preceded by whitespace, both colons will be removed from the output (this is the "partially minimized" form). When text immediately precedes the ::, one colon will be removed from the output, leaving only one colon visible (i.e., :: will be replaced by :; this is the "fully minimized" form).

In other words, these are all equivalent (please pay attention to the colons after "Paragraph"):

1. Expanded form:

   Paragraph:
   
   ::
   
       Literal block

2. Partially minimized form:

   Paragraph: ::
   
       Literal block

3. Fully minimized form:

   Paragraph::
   
       Literal block

All whitespace (including line breaks, but excluding minimum indentation for indented literal blocks) is preserved. Blank lines are required before and after a literal block, but these blank lines are not included as part of the literal block.

+------------------------------+
| paragraph                    |
| (ends with "::")             |
+------------------------------+
   +---------------------------+
   | indented literal block    |
   +---------------------------+

John Doe wrote::

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

You just did!  ;-)

+------------------------------+
| paragraph                    |
| (ends with "::")             |
+------------------------------+
+------------------------------+
| ">" per-line-quoted          |
| ">" contiguous literal block |
+------------------------------+

Line Blocks

Doctree elements:

<line_block>, <line>

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. Each vertical bar prefix indicates a new line, so line breaks are preserved. Initial indents are also significant, resulting in a nested structure. Inline markup is supported. Continuation lines are wrapped portions of long lines; they begin with a space in place of the vertical bar. The left edge of a continuation line must be indented, but need not be aligned with the left edge of the text above it. A line block ends with a blank line.

This example illustrates continuation lines:

| Lend us a couple of bob till Thursday.
| I'm absolutely skint.
| But I'm expecting a postal order and I can pay you back
  as soon as it comes.
| Love, Ewan.

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...

Syntax diagram:

+------+-----------------------+
| "| " | line                  |
+------| continuation line     |
       +-----------------------+

Block Quotes

Doctree elements:

<block_quote>, <attribution>

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."

    -- Sherlock Holmes

A block quote may end with an attribution: a text block beginning with --, ---, or a true em-dash, flush left within the block quote. If the attribution consists of multiple lines, the left edges of the second and subsequent lines must align.

Multiple block quotes may occur consecutively if terminated with attributions.

Unindented paragraph.

Block quote 1.

—Attribution 1

Block quote 2.

Empty comments may be used to explicitly terminate preceding constructs that would otherwise consume a block quote:

* List item.

..

    Block quote 3.

Empty comments may also be used to separate block quotes:

    Block quote 4.

..

    Block quote 5.

Blank lines are required before and after a block quote, but these blank lines are not included as part of the block quote.

Syntax diagram:

+------------------------------+
| (current level of            |
| indentation)                 |
+------------------------------+
   +---------------------------+
   | block quote               |
   | (body elements)+          |
   |                           |
   | -- attribution text       |
   |    (optional)             |
   +---------------------------+

Doctest Blocks

Doctree element:

<doctest_block>

Doctest blocks are interactive Python sessions cut-and-pasted into docstrings. They are meant to illustrate usage by example, and provide an elegant and powerful testing environment via the doctest module in the Python standard library.

Doctest blocks are text blocks which begin with the Python interactive interpreter main prompt (>>> followed by a space) and end with a blank line. Doctest blocks are treated as a special case of literal blocks, without requiring the literal block syntax. If both are present, the literal block syntax takes priority over Doctest block syntax:

This is an ordinary paragraph.

>>> print 'this is a Doctest block'
this is a Doctest block

The following is a literal block::

    >>> This is not recognized as a doctest block by
    reStructuredText.  It *will* be recognized by the doctest
    module, though!

Indentation is not required for doctest blocks.

Tables

Doctree elements:

<table>, <tgroup>, <colspec>, <thead>, <tbody>, <row>, <entry>

ReStructuredText provides two syntax variants for delineating table cells: Grid Tables and Simple Tables. Tables are also generated by the "csv-table" and "list-table" directives. The "table" directive is used to add a table title, caption, or specify options.

As with other body elements, blank lines are required before and after tables. Tables' left edges should align with the left edge of preceding text blocks; if indented, the table is considered to be part of a block quote.

Once isolated, each table cell is treated as a miniature document; the top and bottom cell boundaries act as delimiting blank lines. Each cell contains zero or more body elements. Cell contents may include left and/or right margins, which are removed before processing.

+------------------------+------------+----------+----------+
| Header row, column 1   | Header 2   | Header 3 | Header 4 |
| (header rows optional) |            |          |          |
+========================+============+==========+==========+
| body row 1, column 1   | column 2   | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2             | Cells may span columns.          |
+------------------------+------------+---------------------+
| body row 3             | Cells may  | - Table cells       |
+------------------------+ span rows. | - contain           |
| body row 4             |            | - body elements.    |
+------------------------+------------+---------------------+

+--------------+----------+-----------+-----------+
| row 1, col 1 | column 2 | column 3  | column 4  |
+--------------+----------+-----------+-----------+
| row 2        |                                  |
+--------------+----------+-----------+-----------+
| row 3        |          |           |           |
+--------------+----------+-----------+-----------+

+--------------+----------+-----------+-----------+
| row 1, col 1 | column 2 | column 3  | column 4  |
+--------------+----------+-----------+-----------+
| row 2        | Use the command ``ls | more``.   |
+--------------+----------+-----------+-----------+
| row 3        |          |           |           |
+--------------+----------+-----------+-----------+

+--------------+----------+-----------+-----------+
| row 1, col 1 | column 2 | column 3  | column 4  |
+--------------+----------+-----------+-----------+
| row 2        |  Use the command ``ls | more``.  |
+--------------+----------+-----------+-----------+
| row 3        |          |           |           |
+--------------+----------+-----------+-----------+

+--------------+----------+-----------+-----------+
| row 1, col 1 | column 2 | column 3  | column 4  |
+--------------+----------+-----------+-----------+
| row 2        | Use the command ``ls | more``.   |
|              |                                  |
+--------------+----------+-----------+-----------+
| row 3        |          |           |           |
+--------------+----------+-----------+-----------+

=====  =====  =======
  A      B    A and B
=====  =====  =======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  =======

=====  =====  ======
   Inputs     Output
------------  ------
  A      B    A or B
=====  =====  ======
False  False  False
True   False  True
False  True   True
True   True   True
=====  =====  ======

=====  =====
col 1  col 2
=====  =====
1      Second column of row 1.
2      Second column of row 2.
       Second line of paragraph.
3      - Second column of row 3.

       - Second item in bullet
         list (row 3, column 2).
\      Row 4; column 1 will be empty.
=====  =====

Explicit Markup Blocks

The explicit markup syntax is used for footnotes, citations, hyperlink targets, directives, substitution definitions, and comments.

An explicit markup block is a text block:

• whose first line begins with .. followed by whitespace (the explicit markup start),

• whose second and subsequent lines (if any) are indented relative to the first, and

• which ends before an unindented line.

Explicit markup blocks are analogous to field list items. The maximum common indentation is always removed from the second and subsequent lines of the block body. Therefore, if the first construct fits in one line and the indentation of the first and second constructs should differ, the first construct should not begin on the same line as the explicit markup start.

Blank lines are required between explicit markup blocks and other elements, but are optional between explicit markup blocks where unambiguous.

.. [1] Body elements go here.

+-------+-------------------------+
| ".. " | "[" label "]" footnote  |
+-------+                         |
        | (body elements)+        |
        +-------------------------+

[#]_ is a reference to footnote 1,
and [#]_ is a reference to footnote 2.

.. [#] This is footnote 1.
.. [#] This is footnote 2.
.. [#] This is footnote 3.

[#]_ is a reference to footnote 3.

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

.. [*] This is the footnote.

[2]_ will be "2" (manually numbered),
[#]_ will be "3" (anonymous auto-numbered), and
[#label]_ will be "1" (labeled auto-numbered).

.. [2] This footnote is labeled manually, so its number is fixed.

.. [#label] This autonumber-labeled footnote will be labeled "1".
   It is the first auto-numbered footnote and no other footnote
   with label "1" exists.  The order of the footnotes is used to
   determine numbering, not the order of the footnote references.

.. [#] This footnote will be labeled "3".  It is the second
   auto-numbered footnote, but footnote label "2" is already used.

Here is a citation reference: [CIT2002]_.

.. [CIT2002] This is the citation.  It's just like a footnote,
   except the label is textual.

.. _hyperlink-name: link-block

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

__ anonymous-hyperlink-target-link-block

+-------+----------------------+
| ".. " | "_" name ":" link    |
+-------+ block                |
        |                      |
        +----------------------+

See `the web site of my favorite programming language`__.

.. __: https://www.python.org

__ https://www.python.org

.. image:: mylogo.jpeg

.. figure:: larch.png

   The larch.

.. note:: This is a paragraph

   - Here is a bullet list.

.. figure:: larch.png
   :scale: 50

   The larch.

+-------+-------------------------------+
| ".. " | directive type "::" directive |
+-------+ block                         |
        |                               |
        +-------------------------------+

The |biohazard| symbol must be used on containers used to
dispose of medical waste.

.. |biohazard| image:: biohazard.png

+-------+-----------------------------------------------------+
| ".. " | "|" substitution text "| " directive type "::" data |
+-------+ directive block                                     |
        |                                                     |
        +-----------------------------------------------------+

.. This is a comment
..
   _so: is this!
..
   [and] this!
..
   this:: too!
..
   |even| this:: !

.. [this] however, is a citation.

+-------+----------------------+
| ".. " | comment              |
+-------+ block                |
        |                      |
        +----------------------+

This is
  a definition list.

..

  This is a block quote.

Inline markup recognition rules

Config setting:

character_level_inline_markup

Inline markup start-strings and end-strings are only recognized if the following conditions are met:

1. Inline markup start-strings must be immediately followed by non-whitespace.

2. Inline markup end-strings must be immediately preceded by non-whitespace.

3. The inline markup end-string must be separated by at least one character from the start-string.

4. Both, inline markup start-string and end-string must not be preceded by an unescaped backslash (except for the end-string of inline literals). See Escaping Mechanism above for details.

5. If an inline markup start-string is immediately preceded by one of the ASCII characters ' " < ( [ { or a similar non-ASCII character [18], it must not be followed by the corresponding closing character from ' " > ) ] } or a similar non-ASCII character [19]. (For quotes, matching characters can be any of the quotation marks in international usage.)

If the configuration setting character_level_inline_markup is False (default), additional conditions apply to the characters "around" the inline markup:

6. Inline markup start-strings must start a text block or be immediately preceded by

   • whitespace,

   • one of the ASCII characters - : / ' " < ( [ {

   • or a similar non-ASCII punctuation character. [20]

7. Inline markup end-strings must end a text block or be immediately followed by

   • whitespace,

   • one of the ASCII characters - . , : ; ! ? \ / ' " ) ] } >

   • or a similar non-ASCII punctuation character. [21]

The inline markup recognition rules were devised to allow 90% of non-markup uses of *, `, _, and | without escaping. For example, none of the following terms are recognized as containing inline markup strings:

• 2 * x a ** b (* BOM32_* ` `` _ __ | (breaks rule 1)

• || (breaks rule 3)

• "*" '|' (*) [*] {*} <*> ‘*’ ‚*‘ ‘*‚ ’*’ ‚*’ “*” „*“ “*„ ”*” „*” »*« ›*‹ «*» »*» ›*› (breaks rule 5)

• 2*x a**b O(N**2) e**(x*y) f(x)*f(y) a|b file*.* __init__ __init__() (breaks rule 6)

No escaping is required inside the following inline markup examples:

• *2 * x *a **b *.rst* (breaks rule 2; renders as "2 * x *a **b *.rst")

• *2*x a**b O(N**2) e**(x*y) f(x)*f(y) a*(1+2)* (breaks rule 7; renders as "2*x a**b O(N**2) e**(x*y) f(x)*f(y) a*(1+2)")

It may be desirable to use inline literals for some of these anyhow, especially if they represent code snippets. It's a judgment call.

The following terms do require either literal-quoting or escaping to avoid misinterpretation:

*4, class_, *args, **kwargs, `TeX-quoted', *ML, *.rst

In most use cases, inline literals or literal blocks are the best choice (by default, this also selects a monospaced font). Alternatively, the inline markup characters can be escaped:

\*4, class\_, \*args, \**kwargs, \`TeX-quoted', \*ML, \*.rst

For languages that don't use whitespace between words (e.g. Japanese or Chinese) it is recommended to set character_level_inline_markup to True and escape inline markup characters in case of non-markup use. The examples breaking rules 6 and 7 above show which constructs may need special attention.

Recognition order

Inline markup delimiter characters are used for multiple constructs, so to avoid ambiguity there must be a specific recognition order for each character. The inline markup recognition order is as follows:

• Asterisks: Strong emphasis (**) is recognized before emphasis (*).

• Backquotes: Inline literals (``), inline internal targets (leading _`, trailing `), are mutually independent, and are recognized before phrase hyperlink references (leading `, trailing \`_) and interpreted text (`).

• Trailing underscores: Footnote references ([ + label + ]_) and simple hyperlink references (name + trailing _) are mutually independent.

• Vertical bars: Substitution references (|) are independently recognized.

• Standalone hyperlinks are the last to be recognized.

Character-Level Inline Markup

Config setting:

character_level_inline_markup

It is possible to mark up individual characters within a word with backslash escapes (see Escaping Mechanism above). Backslash escapes can be used to allow arbitrary text to immediately follow inline markup:

Python ``list``\s use square bracket syntax.

The backslash will disappear from the processed document. The word "list" will appear as inline literal text, and the letter "s" will immediately follow it as normal text, with no space in-between.

Arbitrary text may immediately precede inline markup using backslash-escaped whitespace:

Possible in *re*\ ``Structured``\ *Text*, though not encouraged.

The backslashes and spaces separating "re", "Structured", and "Text" above will disappear from the processed document.

In Docutils, you may relax the inline markup recognition rules with the character_level_inline_markup setting, however this may in turn lead to false positives.

Emphasis

Doctree element:

<emphasis>

Start/End string:

*

Standard role:

:emphasis:

Text enclosed by single asterisk characters is emphasized:

This is *emphasized text*.

Emphasized text is typically displayed in italics.

Strong Emphasis

Doctree element:

<strong>

Start/End string:

**

Standard role:

:strong:

Text enclosed by double-asterisks is emphasized strongly:

This is **strong text**.

Strongly emphasized text is typically displayed in boldface.

Interpreted Text

Doctree element:

depends on the explicit or implicit role and processing

Start/End string:

`

Configuration:

"default-role" directive

See also:

reStructuredText Interpreted Text Roles

Interpreted text is text that is meant to be related, indexed, linked, summarized, or otherwise processed, but the text itself is typically left alone. Interpreted text is enclosed by single backquote characters:

This is `interpreted text`.

The role of the interpreted text determines how the text is interpreted. The role may be inferred implicitly (as above; the default role is used) or indicated explicitly, using a role marker. A role marker consists of a colon, the role name, and another colon. A role name is a single word consisting of alphanumerics plus isolated internal hyphens, underscores, plus signs, colons, and periods; no whitespace or other characters are allowed. A role marker is either a prefix or a suffix to the interpreted text, whichever reads better; it's up to the author:

:role:`interpreted text`

`interpreted text`:role:

Interpreted text allows extensions to the available inline descriptive markup constructs. To emphasis, strong emphasis, inline literals, and hyperlink references, we can add "title-reference", "index-entry", "acronym", "class", "red", "blinking" or anything else we want (as long as it is a simple reference name). Only pre-determined roles are recognized; unknown roles will generate errors.

A core set of standard roles is implemented in the reference parser; see reStructuredText Interpreted Text Roles for individual descriptions. The "role" directive can be used to define custom interpreted text roles. In addition, applications may support specialized roles. The default role (used for interpreted text without role marker) can be set with the "default-role" directive.

In field lists, care must be taken when using interpreted text with explicit roles in field names: the role must be a suffix to the interpreted text. The following are recognized as field list items:

:`field name`:code:: interpreted text with explicit role as suffix

:a `complex`:code:\  field name: a backslash-escaped space
                                 is necessary

The following are not recognized as field list items:

::code:`not a field name`: paragraph with interpreted text

:\ :code:`not a field name`: paragraph with interpreted text

Edge cases:

:field\:`name`: interpreted text (standard role) requires
                escaping the leading colon in a field name

:field:\`name`: not interpreted text

Inline Literals

Doctree element:

<literal>

Start/End string:

``

Standard role:

:literal:

See also:

:code:

Text enclosed by double-backquotes is treated as inline literals:

This text is an example of ``inline literals``.

Inline literals may contain any characters except two adjacent backquotes in an end-string context (according to the recognition rules above). No markup interpretation (including backslash-escape interpretation) is done within inline literals.

Line breaks and sequences of whitespace characters are not protected in inline literals. Although a reStructuredText parser will preserve them in its output, the final representation of the processed document depends on the output formatter, thus the preservation of whitespace cannot be guaranteed. If the preservation of line breaks and/or other whitespace is important, literal blocks should be used.

Inline literals or the :code: role are useful for short code snippets. For example:

The regular expression ``[+-]?(\d+(\.\d*)?|\.\d+)`` matches
floating-point numbers (without exponents).

Hyperlink References

Doctree element:

<reference>

Start/End strings:

reference type	name	start	end
named	simple	none	_
	phrase	`	\`_
anonymous	simple	none	__
	phrase	`	\`__

See also:

hyperlink targets

Hyperlink references are indicated by a trailing underscore (_) except for standalone hyperlinks which are recognized independently. The underscore can be thought of as a right-pointing arrow. The trailing underscores point away from hyperlink references, and the leading underscores point toward hyperlink targets.

Hyperlinks consist of two parts:

1. In the text body, there is a source link, a reference name with a trailing underscore (or two underscores for anonymous hyperlinks):

   See the Python_ home page for info.

2. A matching target link must exist in the document. It may be embedded (see below) or exist somewhere else in the document (see Hyperlink Targets).

Anonymous hyperlinks do not use reference names to match references to targets, but otherwise behave similarly to named hyperlinks.

See the `Python home page <https://www.python.org>`_ for info.

This `link <Python home page_>`_ is an alias to the link above.

See the `Python home page`_ for info.

This link_ is an alias to the link above.

.. _Python home page: https://www.python.org
.. _link: `Python home page`_

`RFC 2396 <https://www.rfc-editor.org/rfc/rfc2396.txt>`__ and `RFC
2732 <https://www.rfc-editor.org/rfc/rfc2732.txt>`__ together
define the syntax of URIs.

`RFC 2396`__ and `RFC 2732`__ together define the syntax of URIs.

__ https://www.rfc-editor.org/rfc/rfc2396.txt
__ https://www.rfc-editor.org/rfc/rfc2732.txt

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

Use the `source <parrots.rst\_>`__.

See `HTML Element: \<a>`_, `HTML Element: <b\> `_, and
`HTML Element: <c>\ `_.

See `<a_named_relative_link>`_ or
`<an_anonymous_relative_link>`__ for details.

Inline Internal Targets

Doctree element:

<target>

Start/End strings:

_`   `

See also:

hyperlink targets

Inline internal targets are the equivalent of explicit internal hyperlink targets, but may appear within running text. The syntax begins with an underscore and a backquote, is followed by a hyperlink name or phrase, and ends with a backquote. Inline internal targets may not be anonymous.

For example, the following paragraph contains a hyperlink target named "Norwegian Blue":

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

See Implicit Hyperlink Targets for the resolution of duplicate reference names.

Footnote References

Doctree element:

<footnote_reference>

Start/End string:

[   ]_

Config settings:

footnote_references, trim_footnote_reference_space

See also:

footnotes

Each footnote reference consists of a square-bracketed label followed by a trailing underscore. Footnote labels are one of:

• one or more digits (i.e., a number),

• a single # (denoting auto-numbered footnotes),

• a # followed by a simple reference name (an autonumber label), or

• a single * (denoting auto-symbol footnotes).

For example:

Please RTFM [1]_.

.. [1] Read The Fine Manual

Inline markup recognition rules may require whitespace in front of the footnote reference. To remove the whitespace from the output, use an escaped whitespace character (see Escaping Mechanism) or set the trim_footnote_reference_space configuration setting. Leading whitespace is removed by default, if the footnote_references setting is "superscript".

Citation References

Doctree element:

<citation_reference>

Start/End string:

[   ]_

See also:

citations

Each citation reference consists of a square-bracketed label followed by a trailing underscore. Citation labels are simple reference names.

For example:

Here is a citation reference: [CIT2002]_.

Substitution References

Doctree elements:

<substitution_reference>, <reference>

Start/End string:

| (optionally followed by _ or __).

See also:

substitution definitions

Vertical bars are used to bracket the substitution reference text. A substitution reference may also be a hyperlink reference by appending a _ (named) or __ (anonymous) suffix; the substitution text is used for the reference text in the named case.

The processing system replaces substitution references with the processed contents of the corresponding substitution definitions (which see for the definition of "correspond"). Substitution definitions produce inline-compatible elements.

Examples:

This is a simple |substitution reference|.  It will be
replaced by the processing system.

This is a combination |substitution and hyperlink reference|_.
In addition to being replaced, the replacement text or element
will refer to the "substitution and hyperlink reference" target.

Standalone Hyperlinks

Doctree element:

<reference>

Start/End string:

none

A URI [23] or standalone email address within a text block is treated as a general external hyperlink with the URI rsp. address itself as the link's text. For example:

See https://www.python.org.

would be marked up in HTML as:

See <a href="https://www.python.org">https://www.python.org</a>.

Two forms of standalone hyperlinks are recognized:

1. URIs with known schemes (per the Official IANA Registry of URI Schemes and the W3C's Retired Index of WWW Addressing Schemes). Examples:

   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

   With queries, fragments, and %-escape sequences, URIs can become quite complicated. A reStructuredText parser must be able to recognize any URI, as defined in RFC3936.

2. Standalone email addresses, which are treated as if they were URIs with a "mailto:" scheme. Example:

   someone@somewhere.com

Punctuation at the end of a URI is not considered part of the URI, unless the URI is terminated by a closing angle bracket (>). Backslashes may be used in URIs to escape markup characters, specifically asterisks (*) and underscores (_) which are valid URI characters (see Escaping Mechanism above).

Length Units

The reStructuredText parser supports the length units in CSS3. [24] Unit identifiers are case-sensitive (in contrast to CSS):

The following are all valid length values: 1.5em, 20 mm, .5 in, 42.

Percentage Unit

Percentage values have a percent sign (%) as unit. Percentage values are relative to other values, depending on the context in which they occur.