The reStructuredText Cheat Sheet: Syntax Reminders

Info:

See <https://docutils.sourceforge.io/rst.html> for introductory docs.

Author:

David Goodger <goodger@python.org>

Date:
2025-07-31
Revision:
10193
Description:

This is a "docinfo block", or bibliographic field list

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

  1. items use any variation of "1.", "A)", and "(i)"

  2. also auto-enumerated

Definition list
Term is flush-leftoptional 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

Citation
[CIT2002]

A citation.

Hyperlink Target

Anonymous Target

Directive ("::")

 images/biohazard.png

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, https://docutils.sourceforge.io; named reference, reStructuredText; anonymous reference; footnote reference, [1]; citation reference, [CIT2002]; like an inline directive; inline internal target.

Directive Quick Reference

See <https://docutils.sourceforge.io/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

code

Literal block for code with optional syntax highlighting

math

Mathematical notation (input in LaTeX format)

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

container

Generic block-level container element

table

Create a titled table

list-table

Create a table from a uniform two-level bullet list

csv-table

Create a table from CSV data

contents

Generate a table of contents

sectnum

Automatically number sections, subsections, etc.

header, footer

Create document decorations

target-notes

Create an explicit footnote for each external target

replace

Replacement text for substitution definitions

unicode

Unicode character code conversion for substitution defs

date

Generates today's date; for substitution defs

include

Read an external reST file as if it were inline

raw

Non-reST data passed untouched to the Writer

class

Set a "class" attribute on the next element

role

Create a custom interpreted text role

default-role

Set the default interpreted text role

meta

Document metadata

title

Set the metadata document title

Interpreted Text Role Quick Reference

See <https://docutils.sourceforge.io/docs/ref/rst/roles.html> for full info.

Role Name

Description

code

code in a formal language (see docs for syntax highlighting)

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)

strong

Equivalent to strong

sub

Subscript

sup

Superscript

title

Title reference (book, etc.); standard default role