section¶
Document structure is hierarchy of its section elements. reStructuredText calls heading the section and takes different approach on section leveling than you probably expect. Section titles are decorated with the punctuation characters and importance (a section level) depends on its usage order in a document.
See also
If you want a section-like element that doesn’t make up the table of contents, consider rubric. Is not actually a section, only looks like a minor section to the readers.
Syntax¶
Section is text of title that is underlined, or both underlined and overlined, with same punctuation character. Decoration character is usually one of the following:
= - ` : . ' " ~ ^ _ * + #
:orphan:
#####
Hello
#####
***********
How are you
***********
It's a beautiful day
====================
Even it's Monday
----------------
Recognizing section level¶
Level is importance of section in the document. For example, in HTML every section level has own element like <h1>, <h2> and so on. reStructuredText has different approach.
What level has sections in above example? Answer is in the order of decoration styles usage in the document. Example above uses four decoration styles (underlined, or both underlined and overlined) so you have four levels:
section with title “Hello” is underlined and overlined with
#will become level 1 (top)section with title “How are you” is underlined and overlined with
*will become level 2section with title “It’s beautiful day” is underlined with
=will become level 3section with title “Even it’s Monday” is underlined with
-will become level 4
If above example each decoration style is used just once. First style will become level 1, second level 2 and so on. If decoration style is used once again later, it’s still the same level.
:orphan:
#################
Planet Earth (L1)
#################
***********
Europe (L2)
***********
Great Britain (L3)
==================
Czech Republic (L3)
===================
******************
North America (L2)
******************
Canada (L3)
===========
United States (L3)
==================
Section conventions¶
This flexibility is difficult at writing time to remember what style is what level. Therefore almost all reStructuredText tech-writers adhere the following prevalence convention (we used it in above examples too).
By this convention, first two the most important sections are both under- and overlined, the rest sections underlined only.
Section level |
Decoration style |
Suggested for |
|---|---|---|
1 |
#######
Level 1
#######
|
Document titles |
2 |
*******
Level 2
*******
|
Chapters |
3 |
Level 3
=======
|
Sections |
4 |
Level 4
-------
|
Subsections |
5 |
Level 5
^^^^^^^
|
Subsubsections |
6 |
Level 6
'''''''
|
Paragraphs |
:orphan:
############################
Sections L1 (document title)
############################
Here, we test 6 sections levels.
**********
Section L2
**********
***************************************************************
Very very very very very very very loooooooooooooong section L2
***************************************************************
Section L3
==========
Very very very very very very very loooooooooooooong section L3
===============================================================
Section L4
----------
Very very very very very very very loooooooooooooong section L4
---------------------------------------------------------------
Section L5
^^^^^^^^^^
Very very very very very very very loooooooooooooong section L5
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Section L6
''''''''''
Very very very very very very very loooooooooooooong section L6
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
Common issues¶
Decoration and title length mismatch¶
reStructuredText is very strict about decoration character that must be exactly the same length as title, or longer:
1#########################
2Correct length decoration
3#########################
4
5************************************************
6Longer that title is okay too but ugly
7************************************************
8
9!Shorted that title causes error!
10====================
Overline only section¶
Section title decorated only with overline is not allowed
1================
2Will cause error
and will cause WARNING: Missing matching underline for section title overline..
Under- and overline section are different levels¶
Decoration style is couple of used character + underline or overline. The following decoration styles (and levels) are thus different:
1################################
2Level 1 is under- and over-lined
3################################
4
5********************************
6Level 2 is under- and over-lined
7********************************
8
9Level 3 because it's only overlined
10***********************************
Section on multiple single lines¶
Multiline section titles are actually recognized by reStructuredText as paragraph so no error or warning is thrown.
1This is not multiline
2section but paragraph
3=====================
Deeper levels than supported by the output format¶
Despite due to reStructuredText section level recognition, you are not limited to e.g., six levels as in HTML, it is highly not recommended to use more then six levels.
Levels deeper than supported by output format are rendered identically. For example, in HTML that allows six levels (<h1> to <h6>), the seventh and further levels are rendered as <h6>.