Themes » Writing reST content

While the of­fi­cial re­Struc­tured­Text doc­u­men­ta­tion pro­vides an ex­ten­sive syn­tax guide, the in­fo is scat­tered across many pages. The fol­low­ing page will try to ex­plain the ba­sics and men­tion a bunch of tricks that might not be im­me­di­ate­ly ob­vi­ous.

Ba­sic syn­tax

reST is at its core op­ti­mized for fast con­tent au­thor­ing — the text is eas­i­ly hu­man-read­able, with no ex­ces­sive markup, of­ten-used for­mat­ting is kept sim­ple and ev­ery­thing is ex­ten­si­ble to al­low in­tu­itive us­age in many use cas­es. The ba­sic rules are not far from Mark­down:

  • Head­ers are made by un­der­lin­ing a line of text with some non-al­pha­bet­ic char­ac­ter. Length of the un­der­line has to be same as length of the ti­tle. Us­ing a dif­fer­ent char­ac­ter will cre­ate a next lev­el head­ing, there’s no rule which char­ac­ter means what (but fol­low­ing some con­sis­tent rules across all your con­tent is en­cour­aged).
  • Para­graphs are sep­a­rat­ed from each oth­er by a blank line. Con­sec­u­tive lines of text are con­cate­nat­ed to­geth­er us­ing spa­ces, ig­nor­ing the new­lines. See the Ba­sic block el­e­ments sec­tion be­low for more op­tions.
  • Mul­ti­ple con­sec­u­tive white­space char­ac­ters are ren­dered as a sin­gle space (but that’s large­ly due to how HTML be­haves).
  • Ev­ery­thing is es­caped when con­vert­ing to HTML, so in­line HTML will ap­pear as-is, un­like Mark­down.
  • As with Python, in­den­ta­tion mat­ters in reST. Dif­fer­ent­ly in­dent­ed lines of text are usu­al­ly sep­a­rat­ed via a new­line, but ex­cep­tions to this rule ex­ist.
  • Lines start­ing with .. are treat­ed as com­ment to­geth­er with fol­low­ing in­dent­ed lines as long as the in­den­ta­tion lev­el is not less than in­den­ta­tion of the first line.


Heading 1

First paragraph with a bunch of text. Some more text in that paragraph. You can
wrap your paragraph nicely to fit on your editor screen, the lines will be
concatenated together with a space in between.

Second paragraph of text. Each of these paragraphs is rendered as a HTML <p>
character. The main document heading is not part of the content, but rather an
implicit document title metadata.

Heading 2

The above heading is using a different underline character so it will be
rendered as <h2> in the output. Also, the whole section (heading + content
until the next heading) is rendered as HTML5 <section> element.

Heading 3

Another character used, another level of headings.

.. a comment, which is simply ignored when producing HTML output.
    This is still a comment.

    This as well.

This is not a comment anymore.

Heading 2

Going back to already used character, reST remembers for which heading
level it was used the first time, so it goes back to <h2>.

There’s more in­for­ma­tion about ba­sic syn­tax rules in the of­fi­cial reST doc­u­men­ta­tion.

Meta­da­ta fields

Each doc­u­ment can have a bunch of meta­da­ta fields that are not ren­dered as part of the main doc­u­ment con­tent. Ex­am­ple of these is an ar­ti­cle sum­ma­ry, date or over­rid­ing where giv­en page is saved. Meta­da­ta field starts with :name:, where name is field name. Af­ter the colon there is a space and field con­tents. Con­sec­u­tive in­dent­ed lines are treat­ed as part of the same field.

An article

:date: 2017-10-11
:author: Vladimír Vondruš
:summary: Article summary. Because article summary can be quite long, let's
    wrap it on multiple lines.

Article content starts here.

See the Pel­i­can doc­u­men­ta­tion for de­tails about rec­og­nized fields and how var­i­ous meta­da­ta can be al­so au­to­mat­i­cal­ly ex­tract­ed from the filesys­tem. The m.css Pel­i­can theme rec­og­nizes a few more fields.


Spe­cial block el­e­ments (for ex­am­ple to in­clude an im­age) are called di­rec­tives, are in­tro­duced by a line start­ing with .. name::, where name is di­rec­tive name, af­ter the :: there can be op­tion­al po­si­tion­al ar­gu­ments. Af­ter that there can be an op­tion­al set of named di­rec­tive op­tions (in­dent­ed lines start­ing with :name: where name is op­tion name) and af­ter that op­tion­al di­rec­tive con­tent, al­so in­dent­ed. Unin­dent­ing will es­cape the di­rec­tive. Di­rec­tives can be nest­ed and it’s pos­si­ble to pro­vide us­er-de­fined di­rec­tives via plug­ins.

Ex­am­ple and cor­re­spond­ing out­put, note the in­den­ta­tion:

Paragraph with text.

.. block-info:: Info block title

    Info block content.

    .. figure:: ship.jpg
        :alt: Image alt text

        Figure title

        Figure content.

        .. math::

            A = \pi r^2

        This is again figure content.

    This is again info block content.

And this is another paragraph of text, outside of the info block.

Para­graph with text.

And this is an­oth­er para­graph of text, out­side of the in­fo block.

In­ter­pret­ed text roles

While di­rec­tives are for block el­e­ments, in­ter­pret­ed text roles are for in­line el­e­ments. They are part of a para­graph and are in form of :name:\`contents\`, where name is role name and con­tents are role con­tents. The role has to be sep­a­rat­ed with non-al­phanu­mer­ic char­ac­ter from the sur­round­ings; if you need to avoid the space, es­cape it with \; sim­i­lar­ly with the ` char­ac­ter, if you need to use it in­side. Un­like di­rec­tives, roles can’t be nest­ed. Roles are al­so ex­ten­si­ble via plug­ins.

Roles, like di­rec­tives, al­so have op­tions, but the on­ly way to use them is to de­fine a new role based off the orig­i­nal one with the op­tions you need. Use the .. role:: di­rec­tive like in the fol­low­ing snip­pet, where orig­i­nal is op­tion­al name of the orig­i­nal role to de­rive from, new is the name of new role and fol­lows a list of op­tions:

.. role:: new(original)
    :option1: value1
    :option2: value2

Ex­am­ple and a cor­re­spond­ing out­put:

.. role:: red
    :class: m-text m-danger

A text paragraph with :emphasis:`emphasised text`, :strong:`strong text`
and :literal:`typewriter`\ y text. :red:`This text is red.`

A text para­graph with em­pha­sised text, strong text and typewritery text. This text is red.

Ba­sic block el­e­ments

Be­sides head­ings and sim­ple para­graphs, there are more block el­e­ments like quotes, lit­er­al blocks, ta­bles etc. with im­plic­it syn­tax. Some­times you might want to sep­a­rate two in­dent­ed blocks, use a blank line con­tain­ing just .. to achieve that. Like di­rec­tives, block el­e­ments are al­so nestable, so you can have lists in­side quotes and the like.

| Line block
| will
| preserve the newlines

    A quote is simply an indented block.


    A different quote.


    Literal block is itroduced with ::, which can be even part of previous
    paragraph (in which case it's reduced to a single colon).

========= ============
Heading 1 Heading 2
========= ============
Cell 1    Table cell 2
Row 2     Row 2 cell 2
Row 3     Row 3 cell 3
========= ============

-   An unordered list
-   Another item

    1.  Sub-list, ordered
    2.  Another item
    3.  Note that the sub-list is separated by blank lines

-   Third item of the top-level list

Term 1
Term 2
    Description of term 2

Line block
pre­serve the new­lines

A quote is sim­ply an in­dent­ed block.
A dif­fer­ent quote.
Literal block is itroduced with ::, which can be even the ending of
previous paragraph (in which case it's reduced to a single colon).
Head­ing 1 Head­ing 2
Cell 1 Cell 2
Row 2 Row 2 cell 2
Row 3 Cell 3
  • An un­ordered list
  • An­oth­er item
    1. Sub-list, or­dered
    2. An­oth­er item
    3. Note that the sub-list is sep­a­rat­ed by blank lines
  • Third item of the top-lev­el list
Term 1
Term 2
De­scrip­tion of term 2

The of­fi­cial reST doc­u­men­ta­tion has more de­tailed in­fo about block el­e­ments.

Ba­sic in­line el­e­ments

The :emphasis: role can be writ­ten short­er by wrap­ping the con­tent in *, :strong: us­ing ** and :literal: with ``. A sin­gle back­tick \` is re­served and you can re­de­fine to what­ev­er you need in giv­en scope us­ing the de­fault-role di­rec­tive.

Ex­ter­nal links are writ­ten us­ing \`title <URL>\`_, where ti­tle is link text and URL is the link des­ti­na­tion. The link ti­tle can be then used again to link to the same URL as sim­ply \`title\`_. Note that spec­i­fy­ing two links with the same ti­tle and dif­fer­ent URLs is an er­ror — if you need that, use anony­mous links that are in a form of \`title <URL>\`__ (two un­der­scores af­ter).

In­ter­nal links: ev­ery head­ing can be linked to us­ing \`heading\`_, where head­ing is the head­ing text, more­over the head­ing it­self can be wrapped in back­ticks and an un­der­score to make it a click­able link point­ing to it­self. Ar­bi­trary an­chors in­side the text flow that can be linked to lat­er can be cre­at­ed us­ing the .. _anchor: syn­tax.

.. _an anchor:

An *emphasised text*, **strong text** and a ``literal``. Link to
`Google <>`_, `the heading below <#a-heading>`_ or just an
URL as-is:

`A heading`_

Repeated link to `Google`_. Anonymous links that share the same titles
`here <>`__ and `here <>`__.
Link to `an anchor`_ above.

An em­pha­sised text, strong text and a literal. Link to Google, the head­ing be­low or just an URL as-is:

A heading

Re­peat­ed link to Google. Anony­mous links that share the same ti­tles here and here. Link to an an­chor above.

There are some spe­cial fea­tures in Pel­i­can for eas­i­er link­ing to in­ter­nal con­tent, be sure to check out the doc­u­men­ta­tion. The reST doc­u­men­ta­tion al­so of­fers more de­tailed in­fo about in­line markup.

Es­sen­tial di­rec­tives

  • A con­tain­er di­rec­tive will just put a <div> around its con­tents and its ar­gu­ments will be put as CSS class­es to that el­e­ment.
  • A class di­rec­tive will put its ar­gu­ment as CSS class to the im­me­di­ate­ly fol­low­ing el­e­ment. Be­sides that, most of the di­rec­tives al­so ac­cept a :class: op­tion that does the same.
  • Some­times you need to put raw HTML code on­to your page (for ex­am­ple to em­bed a third-par­ty wid­get). Use the raw di­rec­tive to achieve that.
  • For in­clud­ing larg­er por­tions of raw HTML code or big­ger code snip­pets there’s the in­clude di­rec­tive, you can al­so spec­i­fy just a por­tion of the file ei­ther by line num­bers or text match.
  • The con­tents di­rec­tive will au­to­mat­i­cal­ly make a Ta­ble of Con­tents list out of head­ings in your doc­u­ment. Very use­ful for nav­i­ga­tion in large pages and ar­ti­cles.

For stuff like im­ages, fig­ures, code blocks, math list­ing etc., m.css pro­vides var­i­ous plug­ins that do it bet­ter than the builtin way. Head over to the of­fi­cial reST doc­u­men­ta­tion for more in­fo about builtin di­rec­tives.

Es­sen­tial in­ter­pret­ed text roles

  • Be­sides the al­ready men­tioned roles, there’s al­so a sup and sub role for su­per­script and sub­script text.
  • It’s al­so pos­si­ble to put raw HTML code in­line by de­riv­ing from the raw role.

Again, m.css pro­vides var­i­ous plug­ins that al­low you to have in­line code, math, GitHub and Doxy­gen links and much more. Head over to the of­fi­cial reST doc­u­men­ta­tion for more in­fo about builtin roles.