Headers

Headers in rST aren’t as straightforward as in Markdown. You need to match the title’s length with an accompanying line below made with exactly one of the following characters:

=, -, ^, ", *, #

It doesn’t matter which characters represent which heading level, they are determined by their first occurence. So you can switch them around as long as you consistently use one for its respective header within the same document.

The next document can use a completely match.

Furthermore, you can also add the same line above the title, which makes it a different heading level. (Again, determined by their first occurence.)

To avoid confusion, the following layout is recommended:

Header 1
========

Header 2
--------

Header 3
^^^^^^^^

Header 4
""""""""

Header 5
********

Header 6
########

This is largely based on the rST standard used in Python documentation, although even there it is somewhat vague. The above code would render out like this (but it would do the same with any of the lines switched around):

Header 2

Header 3

Header 4

Header 5

Header 6

Warning

Do not use more than one level 1 heading, level 1 headings are meant to be used as document titles.

They also show up in the document-tree which breaks formatting.