# The reStructuredText Cheat Sheet: Syntax Reminders

Info: | See <http://docutils.sf.net/rst.html> for introductory docs.
Author: | David Goodger <goodger@python.org>
Date: | 2021-03-05
Revision: | 8631
Description: | This is a "docinfo block", or bibliographic field list

Note

If you are reading this as HTML, please read cheatsheet.txt instead to see the input syntax examples!

# Section Structure

Section titles are underlined or overlined & underlined.

# Body Elements

Grid table:

Paragraphs are flush-left, separated by blank lines. Block quotes are indented. | Literal block, preceded by "::":
    Indented
or:
    > Quoted
    >>> print 'Doctest block'
    Doctest block
Line blocks preserve line breaks & indents. [new in 0.3.6] Useful for addresses, verse, and adornment-free lists; long lines can be wrapped with continuation lines.

Simple tables:

List Type | Examples (syntax in the text source)
--- | ---
Bullet list | items begin with "-", "+", or "*"
Enumerated list | items use any variation of "1.", "A)", and "(i)" also auto-enumerated
Definition list | Term is flush-left : optional classifier Definition is indented, no blank line between
Field list |
field name: | field body
Option list |
`-o` | at least 2 spaces between option & description

Explicit Markup | Examples (visible in the text source)
--- | ---
Footnote |
[1] | Manually numbered or [#] auto-numbered (even [#labelled]) or [*] auto-symbol
Citation |
[CIT2002] | A citation.
Hyperlink Target |
Anonymous Target |
Directive ("::") |
Substitution Def |
Comment |
Empty Comment | (".." on a line by itself, with blank lines before & after, used to separate indentation contexts)

# Inline Markup

emphasis; strong emphasis; interpreted text; interpreted text with role; `inline literal text`; standalone hyperlink, http://docutils.sourceforge.net; named reference, reStructuredText; anonymous reference; footnote reference, [1]; citation reference, [CIT2002]; like an inline directive; inline internal target.

# Directive Quick Reference

See <http://docutils.sf.net/docs/ref/rst/directives.html> for full info.

Directive Name | Description (Docutils version added to, in [brackets])
--- | ---
attention | Specific admonition; also "caution", "danger", "error", "hint", "important", "note", "tip", "warning"
admonition | Generic titled admonition: `.. admonition:: By The Way`
image | `.. image:: picture.png`; many options possible
figure | Like "image", but with optional caption and legend
topic | `.. topic:: Title`; like a mini section
sidebar | `.. sidebar:: Title`; like a mini parallel document
parsed-literal | A literal block with parsed inline markup
rubric | `.. rubric:: Informal Heading`
epigraph | Block quote with class="epigraph"
highlights | Block quote with class="highlights"
pull-quote | Block quote with class="pull-quote"
compound | Compound paragraphs [0.3.6]
container | Generic block-level container element [0.3.10]
table | Create a titled table [0.3.1]
list-table | Create a table from a uniform two-level bullet list [0.3.8]
csv-table | Create a table from CSV data [0.3.4]
contents | Generate a table of contents
sectnum | Automatically number sections, subsections, etc.
header, footer | Create document decorations [0.3.8]
target-notes | Create an explicit footnote for each external target
math | Mathematical notation (input in LaTeX format)
meta | Document metadata
include | Read an external reST file as if it were inline
raw | Non-reST data passed untouched to the Writer
replace | Replacement text for substitution definitions
unicode | Unicode character code conversion for substitution defs
date | Generates today's date; for substitution defs
class | Set a "class" attribute on the next element
role | Create a custom interpreted text role [0.3.2]
default-role | Set the default interpreted text role [0.3.10]
title | Set the metadata document title [0.3.10]

# Interpreted Text Role Quick Reference

See <http://docutils.sf.net/docs/ref/rst/roles.html> for full info.

Role Name | Description
--- | ---
emphasis | Equivalent to emphasis
literal | Equivalent to `literal` but processes backslash escapes
math | Mathematical notation (input in LaTeX format)
PEP | Reference to a numbered Python Enhancement Proposal
RFC | Reference to a numbered Internet Request For Comments
raw | For non-reST data; cannot be used directly (see docs) [0.3.6]
strong | Equivalent to strong
sub | Subscript
sup | Superscript
title | Title reference (book, etc.); standard default role