So I won’t forget; source: reStructuredText Markup Specification – Sections
Rather than imposing a fixed number and order of section title adornment styles, the order enforced will be the order as encountered. The first style encountered will be an outermost title (like HTML H1), the second style will be a subtitle, the third will be a subsubtitle, and so on.
Below are examples of section title styles:
===============
Section Title
===============
---------------
Section Title
---------------
Section Title
=============
Section Title
-------------
Section Title
`````````````
Section Title
'''''''''''''
Section Title
.............
Section Title
~~~~~~~~~~~~~
Section Title
*************
Section Title
+++++++++++++
Section Title
^^^^^^^^^^^^^
When a title has both an underline and an overline, the title text may be inset, as in the first two examples above. This is merely aesthetic and not significant. Underline-only title text may not be inset.
A blank line after a title is optional. All text blocks up to the next title of the same or higher level are included in a section (or subsection, etc.).
All section title styles need not be used, nor need any specific section title style be used. However, a document must be consistent in its use of section titles: once a hierarchy of title styles is established, sections must use that hierarchy.
Each section title automatically generates a hyperlink target pointing to the section. The text of the hyperlink target (the “reference name”) is the same as that of the section title.
I prefer this order because of decreasing “greyness”:
# * = + ^ ~ - : . _ ` ' "
–jeroen