The reStructuredText Cheat Sheet: Syntax Reminders

Info:

See <http://docutils.sf.net/rst.html> for introductory docs.

Author:

David Goodger <goodger@python.org>

Date:

$Date: 2021-03-05 22:14:40 +0100 (Fr, 05. Mär 2021) $

Revision:

$Revision: 8631 $

Description:

This is a “docinfo block”, or bibliographic field list

Note

If you are reading this as HTML, please read index.rst 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

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