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

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.

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 will result in more complex structures. The least indented line of a block sets the reference indentation:

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.

Every block has its own reference indentation::

        This paragraph belongs to a first-level block quote
        because there is no less indented line in the block.

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 first line of text may start below the marker:

1.
 This is the first line of an enumeration
 item's paragraph.

  This indented paragraph is interpreted
  as a block quote.

 This paragraph still belongs to the list
 item

This paragraph ends 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.
:Long field name: It would be inconvenient to align the
    field body with the left edge of the first line.
:Number of African swallows required to carry a coconut:
    Sometimes, it is preferable to begin the body
    on the next line.

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. [7] Specifically, an underline/overline character may be any non-alphanumeric printable 7-bit ASCII character [8]. 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. [9]

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 and start value. 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.[10] 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)+                  |
        +-----------------------------------+