.RST File Format – Sections and body elements

reStructuredText

A reStructuredText document is plain text, normally UTF-8, read line by line. Blank lines separate elements, and indentation shows what belongs to what: an indented block belongs to the element above it. Tabs are expanded to stops every 8 columns. This page follows the Docutils reStructuredText Markup Specification, which defines the language; Sphinx adds its own directives and roles on top.

Section titles

A title is a single line of text with an underline, and optionally an overline, made of one repeated punctuation character. The underline must be at least as long as the title; an overline must use the same character and length as the underline.

=========
 Overview
=========

Getting started
---------------

Installing
~~~~~~~~~~
  • Any non-alphanumeric printable ASCII character may be used. The recommended set is = - ` : . ' " ~ ^ _ * + #.
  • Levels are not fixed: the first style met is level 1, the next new style level 2, and so on. An underline-only style and an overlined style with the same character are different styles. A style must be used consistently.
  • If the document starts with a uniquely adorned title, it becomes the document title; a second unique title directly after it becomes the subtitle.
  • Titles also become link targets, by their text.

Transitions

A line of four or more repeated punctuation characters, with blank lines before and after, marks a break in the text (like hr in HTML). A transition may not begin or end a section or document, and two may not be adjacent.

Body elements

ElementSyntaxNotes
ParagraphLines of text, left-aligned, ended by a blank line.The default element.
Bullet list*, +, -, •, ‣ or ⁃ then a space.Item text is indented to line up after the bullet; a different bullet starts a new list.
Enumerated listAn enumerator: Arabic numbers (1), letters (a, A), Roman numerals (i, I) or # for automatic numbering; in the form 1., 1) or (1).A new list starts when the sequence or form changes or numbers are out of order. A list starting i or I is Roman; a list starting with another single Roman letter (v, x, l, c, d, m) is read as letters.
Definition listA term on one line; optional classifiers after : ; the definition indented on the next lines.No blank line between term and definition.
Field list:name: bodyLike e-mail headers; the body may continue on indented lines.
Option listCommand-line options, then two or more spaces, then the description: -a, --all, /V (DOS style), +a (deprecated); arguments as -o FILE or --out=FILE.Groups of options are separated by , .
Literal blockA paragraph ending in ::, then an indented block.Shown exactly, in a fixed-width font. Text:: keeps one colon in the output; Text :: keeps none; a paragraph of just :: disappears.
Quoted literal blockAfter ::, an unindented block whose lines all start with the same punctuation character, such as >.For e-mail quotes.
Line blockLines starting with | .Line breaks and leading spaces are kept; for verse and addresses. A continuation line starts with a space.
Block quoteAn indented block not introduced by anything else.An attribution line starting with --, --- or an em dash may end it.
Doctest blockA block starting with >>> .An interactive Python session, kept as typed; ends at a blank line.
Grid tableA drawing with +, -, |, and = under the header row.Cells may span rows and columns and hold any body elements.
Simple tableColumns separated by spaces between lines of =; - underlines join columns.Column spans only; the first column must not be empty in a row unless the row continues the one above.
Explicit markupA line starting with .. Footnotes, citations, targets, directives, substitutions and comments: see below.

Bibliographic fields

A field list that is the first element of the document (after the title) gives the document’s metadata when its field names are among these: Author, Authors, Organization, Address, Contact, Version, Revision, Status, Date, Copyright, Dedication, Abstract. Names are matched without regard to case and are translated for other document languages. Other fields in that list are kept as generic fields. RCS keywords such as $Date: 2026-11-12 $ are reduced to their value.

:Author: Ada Lovelace
:Version: 1.2
:Date: 2026-11-12
:Abstract: Notes on the analytical engine.

Explicit markup

Everything after .. up to the end of the indented block belongs to one construct.

ConstructSyntaxMeaning
Footnote, numbered.. [1] textReferred to as [1]_.
Footnote, auto-numbered.. [#] text or .. [#label] textNumbered in order; a label lets references ([#label]_) find it.
Footnote, auto-symbol.. [*] textMarked with symbols in order: * † ‡ § ¶ # ♠ ♥ ♦ ♣, then doubled (**, ††…), then tripled.
Citation.. [CIT2002] textLike a footnote but with a text label, referred to as [CIT2002]_.
Hyperlink target, external.. _Python: https://www.python.org/Makes Python_ a link.
Hyperlink target, internal.. _intro:Names the element that follows.
Hyperlink target, indirect.. _home: Python_An alias for another target.
Hyperlink target, anonymous.. __: https://example.org/ or __ https://example.org/Matched in order with anonymous references (`text`__).
Directive.. name:: arguments, then options as a field list, then content, all indentedAn extension point: see directives.
Substitution definition.. |name| directive:: …Defines what |name| stands for, usually with replace, image or unicode.
Comment.. followed by anything that is not one of the aboveNot shown. A .. alone on a line, with nothing indented after it, is an empty comment, used to end a list or block quote.

Reference names

Targets, footnotes and citations share one name space. Names are matched without regard to case, and runs of whitespace count as one space. A simple name is letters and numbers with single -, _, ., : or + inside; other names must be written in backquotes (`Phrase name`_). Substitution names are a separate, case-sensitive space that falls back to case-insensitive matching.