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.
:orphan:
###############
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 https://snippets.documatt.com, 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 https://documatt.com/blog/ are auto-recognized. Sometimes you need ``monospaced text``. Useful are also :sup:`superscript` or :sub:`subscript`.
******
Images
******
.. image:: https://documatt.com/blog/_static/open-doodles-clumsy.svg
*****
Lists
*****
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
alert(i);
}
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¶
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
3
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.
2
3In normal text, multiple successive blank lines are
4considered as a single blank line.
5
6::
7
8 They are only
9
10
11 preserved in the
12
13
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.
Indentation¶
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).
Caution
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
2
3 Don't count the days, make the days count.
4
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.
Previous: Guide to reStructuredText and Sphinx | Next: Directives and roles
Comments¶
Comments are parts of text that should be processed. Syntax is
..(two dots and one space).For multline commends you need to indent the text after
..:Inline comments are not supported. For example, JavaScript supports inline comments with
/*and*/, e.g.let foo = /* inline comment */ 'bar';.