Search code examples
documentationmarkuprestructuredtext

Prevent section heading to subtitle transformation in reStructuredText

In reStructuredText, a heading followed by a lower-level heading is read as a subtitle:

Section 1
=========

Subtitle
--------

However, what if I actually want a subsection heading to follow immediately after a section heading? According to the the docs, an empty comment "serves to terminate a preceding construct", but this doesn't seem to apply here, as

Section 1
=========

..

Section 2
---------

still gets turned into a heading for Section 1, followed by a subtitle Section 2 by, for example, rst2latex and pandoc.

Is there another way to prevent "subtitlisation" without writing any actual text between the section and subsection headings?

Solution

  • Nevermind, I figured it out. A backslash followed by a space will work:

    Section 1
=========

\ 

Section 2
--------

    I got the idea from a tip on Simple Tables in the spec:

    To start a new row in a simple table without text in the first column in the processed output, use one of these:

    • an empty comment (".."), which may be omitted from the processed output (see Comments below)
    • a backslash escape ("\") followed by a space (see Escaping Mechanism above)

    IMHO this isn't very consistent: The second method works for breaking up title and subtitle, whereas the first one doesn't, as I stated in my question.