reStructuredText and Sphinx Reference

Example based gentle reference of the reStructuredText and Sphinx syntax, directives, roles and common issues. It demonstrates almost all the markup making it also good for testing Sphinx themes. Free and open-source.

reStructuredText overview

If you starting writing in reStructuredText, you will find it’s not always intuitive. In this guide, you’ll find explanation in plain English of syntax, elementary concepts and important pitfalls to avoid.

What is reStructuredText?

reStructuredText is a lightweight markup language for writing articles, blog posts, documents, and books.

Its syntax (the rules of writing) is suited for a documentation. Programmers write in Java, Python, etc., while tech writers write in plain text files containing reStructuredText. It has a syntax very similar to its close relative Markdown.

Documentation languages as reStructuredText are also called markup languages, because they add the formatting and semantic meaning to the plain text. At the time of writing, you should not be concerned how the text will look like at production. The outputs like web page or PDF may look very different. You concentrate on the structure and content at writing time, not the visual appearance.

For brevity, it is often abbreviated as RST or reST (don’t confuse with the REST which is kind of APIs). A file extension is often .rst or .txt.

Sample document

Have look at the following example of document written using reStructuredText.


Sample document

.. epigraph:: This document demonstrate reStructuredText syntax. Professional books and tech documentation are plain text files written with this easy markup language.

.. tip:: You can try, the online editor with preview useful for learning and testing reStructuredText without installing it.

Inline elements

Paragraphs may contain *emphasised*, **strong emphasised** words. Links to external webs like are auto-recognized. Sometimes you need ``monospaced text``. Useful are also :sup:`superscript` or :sub:`subscript`.


.. image::


Unordered lists usually use ``*`` as bullet symbol:

* A bullet list item
* Second item
* A sub item

Ordered (enumerated) lists that is auto-numbered starts with ``#.``:

#. one
#. two
#. three

Showing code examples

It's easy to show code parts with ``inline literal``, or literal block::

 some literal text

Or, literal block with syntax highlighting:

.. code-block:: javascript

  for (let i = 0; i < 3; i++) {        // shows 0, then 1, then 2

Block and inline elements

reStructuredText contains two types of elements: block and inline-level.

Block-level elements appear as rectangular objects that do not break across lines in the text. Examples of block elements: section title, paragraph, bullet list, and many more.

Inline elements are part of the document text flow and break across lines. Inlines are, e.g., emphasis (italic), strong emphasis (bold), inline literal (code example in the monospace font), and a few more.

It is very intuitive to differentiate between inline and block elements.


Whitespace and indentation


Whitespaces are invisible but very important characters not only in reStructuredText. The common whitespaces are under the Space and Tab keys.

Blank lines

Blank lines are important. For example, they separate paragraph and other block elements, or delimit sublist within a list.

1this is still the
2first paragraph
4second paragraph

this is still the first paragraph

second paragraph

In normal text, multiple successive blank lines are considered as a single blank line. They are only preserved in the literal blocks.

 1Blank lines separates paragraphs and other elements.
 3In normal text, multiple successive blank lines are
 4considered as a single blank line.
 8   They are only
11   preserved in the
14   literal blocks.

Blank lines separates paragraphs and other elements.

In normal text, multiple successive blank lines are considered as a single blank line.

They are only

preserved in the

literal blocks.


Tricky part of reStructuredText is indentation. Indentation means putting whitespaces before the line text itself. We strongly recommend you to use space characters (via Space key) instead of tabs (via Tab key).


Keeping proper indentation and blank line separators in reStructuredText is definitively the biggest trouble not only for beginners! Read the following part very carefully.

The indentation is part of the syntax of many reStructuredText elements:

  • block quotes

  • definition lists

  • bullet and enumerated lists

  • content of literal blocks

  • content of blocks like directive, footnote, comment, etc.

  • any nested content, e.g. a list withing another list item

Wrongly indented means wrongly recognized. For example, just indenting the second paragraph makes it the block quote element. First and third has original indentation and thus are normal paragraphs.

1My favorite quote is
3    Don't count the days, make the days count.
5but I don't remember its author.

My favorite quote is

Don’t count the days, make the days count.

but I don’t remember its author.


Comments are parts of text that should be processed. Syntax is ..  (two dots and one space).

.. This is a comment.

For multline commends you need to indent the text after .. :

   This whole indented block
   is a comment.

   Still in the comment.

Inline comments are not supported. For example, JavaScript supports inline comments with /* and */, e.g. let foo = /* inline comment */ 'bar';.

Previous: Guide to reStructuredText and Sphinx | Next: Directives and roles