Notes On RestructuredText

Abstract:Brief notes and comments on RestructuredText Markup language.
Author:Thava Alagu
Date:25 Jan 2013


RestructuredText and Markdown are the 2 most popular markup languages, that are useful for taking notes. You can easily convert them to HTML (or other) format later.

The RestructuredText was originally designed to document python code (similar to Javadoc for Java). as part of docutils project. See RestructuredText Specification for more information.

This is not a comprehensive specification. See original specification pages for comprehensive information. This provides some brief notes and summary of important features.

Section Headers

The headers are underlined and must be at least as long as the title text. The first under-and-over lined header is document title and excluded from TOC:

This Document Title should have both under and over line

Section title1

Section Subtitle1

Note that the order of headers defines subsections;  Since --- header appeared
after the === header, it becomes a subsection.
Recommended choices for section title characters are ``" = - : ' ' ~ ^ _ * + # < > "``

Bullet Lists

* First bullet
* Second bullet
* Third bullet

#. any number
#. For numeric list
#. This will be 3rd bullet number

Rendered like below:

  • First bullet
  • Second bullet
  • Third bullet
  1. any number
  2. For numeric list
  3. This will be 3rd bullet number

Note that a blank line is required before the first item and after the last, but is optional between items.


Paragraph is text surrounded by whitespace. Paragraphs can be on one line or can span many lines.

Inline Image

Image can be inserted using image directive. Example:

.. image:: picture.jpeg
   :height: 100px
   :width: 200 px
   :scale: 50 %
   :alt: alternate text
   :align: right

Typically it is used with substitution syntax like below:

Here is a |cat|

.. |cat| image:: cat.png

Inline Markups

Basic inline markup examples

This is _italics_, *emphasised*,  **bold**, and `code()`.

Rendered like below:

This is _italics_, emphasised,  bold, and code().


*emphasis*           Maps to html em tag and italicised.
**strong emphasis**  Maps to html strong tab and bold faced.
`code()`             Typically maps to monospaced (using cite tag for example)
``literal``          Maps to html tt tag, teletype text ie. monospaced text.
                     (tt tag is deprecated and not in HTML5)

The `interpreted text` is domain specific -- implementation is free to choose.
``inline literal``  literal  rendered as monospaced text with spaces preserved.

Definition lists

It is a list of (term, definition) tuples. A term can have multiple defintions. Multiple terms (synonyms) can have single definition.


  Definition lists associate a term with
  a definition.

  Definition2 goes here.

Rendered as:


Definition lists associate a term with a definition.

Definition2 goes here.

Field Lists


:Author: All contributors
         for this
:version: 1.0
:Date: 2013/01/20

Rendered as

Author:All contributors for this project

Literal Blocks (Escape from RST syntax)

Literal blocks is defined using following syntax:

Example block ::

Whitespace, newlines, blanklines, and all kinds of markups preserved in literal block. Blank line after :: is required.

Literal blocks end when text returns to the preceding paragraph’s indentation.

Line Blocks

Line blocks are like literal block, but they are non-monospaced, using regular font. It is also useful when you want to preserve some initial indents:

| Line blocks are useful for addresses,
| verse, and adornment-free lists.
| Each new line begins with a
| vertical bar
|     Line breaks and initial indents
|     are preserved.
| Continuation lines are wrapped
  portions of long lines; they begin
  with spaces in place of vertical bars.


Use following format to define comment. Start the line with .. followed by any text which is not any predefined directive

.. This text is a comment,
   this may be rendered as an HTML comment, for example.

An empty comment is a line containing ”..” with blank lines before and after:


Transition Marker

Often you would like to explicitly terminate a bullet list or a field list, etc. Then you need a transition marker. An empty comment is perfect for this purpose:


You can also use the following for explicit transition marker:

Any 4 or more punctuation marks like those used for section titles:

Some implementations may convert this to horizontal rule to mark transition.


There are predefined set of directives. Examples include image, figure (which is image plus more custom attributes), table (to associate title with table), csv-table (to turn csv lines to table), contents (to generate TOC), header, footer (to add a para at the bottom of the page), replace (to use abbreviated forms), unicode (to specify char using unicode), etc. A directive can accept a set of attributes.


To inline an image:
  .. image:: images/ball1.gif

Following directives are supported for HTML only

.. meta::
   :description: The reStructuredText plaintext markup language
   :keywords: plaintext, markup language

.. contents:: My TOC Title
    :depth: 2    .. Max depth for listing. This is inline comment.

You can write your own directive if you like. See RST directive to embed Youtube video for an example.

Specifying class directive

Use the class directive using following syntax:

.. class:: class1 class2

The classes apply to the next immediate element, be it paragraph or header, table, etc.

Admonition Directives

There is a special types of directives called admonition directives. They are: “attention”, “caution”, “danger”, “error”, “hint”, “important”, “note”, “tip”, and “warning”. Example

.. warning::
   This feature is deprecated (example warning)!

.. tip::
   Use admonition directives to nicely format your text with tips and notes and warnings.

Rendered as:


This feature is deprecated (example warning)! This can be multi-line warning.


Use admonition directives to nicely format your text with tips and notes and warnings.


Encountered some Error! (example error)!

See RestructuredText Demo for more information.


Substitutions can be used to use an abbreviation for text or image like below:

The |cat| is out.
.. |cat| image:: cat.png

Look at |html|
.. |html| replace:: Hypertext Markup Language

Footnote Reference

Footnote reference is exactly like any other internal hyperlink mechanism. Only difference is that the target is automatically moved to the bottom, and may be autonumbered.


Footnote references, like [5]_.
Note that footnotes may get rearranged, e.g., to the bottom of the "page".

.. [5] A numerical footnote. (this is footnote definition at the bottom)

Autonumbered footnotes are possible, like using [#]_ and [#]_.

.. [#] This is the first one. (The numbers assigned during rendering.)
.. [#] This is the second one.

Citation Reference

Citation reference is like footnote reference, only difference is that a word is used to refer to the note instead of a number.


Example citation reference is [CIT2002]_.
Note that citations may get rearranged, e.g., to the bottom of the "page".
Citations auto generates the references backlinks also.
.. [CIT2002] A citation
   (as often used in journals).


Grid table

Grid table is powerful but verbose:

| Header 1   | Header 2   | Header 3  |
| body row 1 | column 2   | column 3  |
| body row 2 | Cells may span columns.|
| body row 3 | Cells may  | - Cells   |
+------------+ span rows. | - contain |
| body row 4 |            | - blocks. |

Rendered as:

Header 1 Header 2 Header 3
body row 1 column 2 column 3
body row 2 Cells may span columns.
body row 3 Cells may span rows.
  • Cells
  • contain
  • blocks.
body row 4

Simple table

Simple table is less powerful (can not span rows), but simpler to use

=====  =====  ======
   Inputs     Output
------------  ------
  A      B    A or B
=====  =====  ======
False  False  False
True   False  True
False  True   True
True   True   True
=====  =====  ======

Rendered as

Inputs Output
A B A or B
False False False
False True True
True False True
False False False

Embed HTML in RST

Use raw directive

.. raw:: html
   <hr width=50 size=10>

Including Files

You can include one file from other

.. include:: anotherfile.rst

Block Quotes

Indented paragraphs are generated as <blokquote> ... </blockquote> elements

This is first level blockquote

  This is second level blockquote. Leave blank line between paragraphs.

Another supported block type is doctest block. No indentation required:

>>> print 'this is Doctest block example'
this is Doctest block example

Note that the general > and >> email type blocks are not recognized by RestructuredText.

Syntax Highlighting

To trigger syntax highlighting on a block, use code directive

.. code:: python

def my_function():
    "exmple function"
    a = 10
    print a/2

Rendered as:

def my_function():
     "exmple function"
     a = 10
     print a/2

Using Common Syntax Between RST and Markdown

See for an article about using common markup language of Markdown and RST. This is useful if you ever bother to quickly port between RST and Markdown.

Some interesting points to note are:

For literal blocks always indent with min 4 spaces.
This is required by markdown. RST is OK with any amount of indentation.

For ``mono spaced text`` use double backquotes.
This is required by RST. Markdown is OK with single backquote.

For code (literal) blocks use :: at end of preceding para
and leave empty line after that. (Required by RST)

For hard line breaks with non-monospaced literal block:
End line with 2 spaces (for markdown) and start the line with "| ".

For inline urls, always enclose them with angle brackets (required by Markdown).

Note that there is no straight forward way of writing portable comments
between RST and markdown. Markdown requires HTML comment <!--  --> syntax.

Source Document

This document has been written using RestructuredText and converted to HTML using rst2html command.

See the document source text