The reStructuredText Cheat Sheet: Syntax Reminders
- Info:
See <https://docutils.sourceforge.io/rst.html> for introductory docs.
- Date:
- 2024-08-15
- Revision:
- 9906
- 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.
|
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 |
|
Enumerated list |
|
Definition list |
|
Field list |
|
Option list |
|
Explicit Markup |
Examples (visible in the text source) |
|---|---|
Footnote |
|
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, 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 |
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 <https://docutils.sourceforge.io/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 |