4.3Setext headings

A setext heading consists of one or more lines of text, not interrupted by a blank line, of which the first line does not have more than 3 spaces of indentation, followed by a setext heading underline. The lines of text must be such that, were they not followed by the setext heading underline, they would be interpreted as a paragraph: they cannot be interpretable as a code fence, ATX heading, block quote, thematic break, list item, or HTML block.

A setext heading underline is a sequence of = characters or a sequence of - characters, with no more than 3 spaces of indentation and any number of trailing spaces or tabs.

The heading is a level 1 heading if = characters are used in the setext heading underline, and a level 2 heading if - characters are used. The contents of the heading are the result of parsing the preceding lines of text as CommonMark inline content.

In general, a setext heading need not be preceded or followed by a blank line. However, it cannot interrupt a paragraph, so when a setext heading comes after a paragraph, a blank line is needed between them.

Simple examples:

Example 80Try It 
Foo *bar*
=========

Foo *bar*
---------

<h1>Foo <em>bar</em></h1>
<h2>Foo <em>bar</em></h2>

The content of the header may span more than one line:

Example 81Try It 
Foo *bar
baz*
====

<h1>Foo <em>bar
baz</em></h1>

The contents are the result of parsing the headings’s raw content as inlines. The heading’s raw content is formed by concatenating the lines and removing initial and final spaces or tabs.

Example 82Try It 
  Foo *bar
baz*→
====

<h1>Foo <em>bar
baz</em></h1>

The underlining can be any length:

Example 83Try It 
Foo
-------------------------

Foo
=

<h2>Foo</h2>
<h1>Foo</h1>

The heading content can be preceded by up to three spaces of indentation, and need not line up with the underlining:

Example 84Try It 
   Foo
---

  Foo
-----

  Foo
  ===

<h2>Foo</h2>
<h2>Foo</h2>
<h1>Foo</h1>

Four spaces of indentation is too many:

Example 85Try It 
    Foo
    ---

    Foo
---

<pre><code>Foo
---

Foo
</code></pre>
<hr />

The setext heading underline can be preceded by up to three spaces of indentation, and may have trailing spaces or tabs:

Example 86Try It 
Foo
   ----      

<h2>Foo</h2>

Four spaces of indentation is too many:

Example 87Try It 
Foo
    ---

<p>Foo
---</p>

The setext heading underline cannot contain internal spaces or tabs:

Example 88Try It 
Foo
= =

Foo
--- -

<p>Foo
= =</p>
<p>Foo</p>
<hr />

Trailing spaces or tabs in the content line do not cause a hard line break:

Example 89Try It 
Foo  
-----

<h2>Foo</h2>

Nor does a backslash at the end:

Example 90Try It 
Foo\
----

<h2>Foo\</h2>

Since indicators of block structure take precedence over indicators of inline structure, the following are setext headings:

Example 91Try It 
`Foo
----
`

<a title="a lot
---
of dashes"/>

<h2>`Foo</h2>
<p>`</p>
<h2>&lt;a title=&quot;a lot</h2>
<p>of dashes&quot;/&gt;</p>

The setext heading underline cannot be a lazy continuation line in a list item or block quote:

Example 92Try It 
> Foo
---

<blockquote>
<p>Foo</p>
</blockquote>
<hr />
Example 93Try It 
> foo
bar
===

<blockquote>
<p>foo
bar
===</p>
</blockquote>
Example 94Try It 
- Foo
---

<ul>
<li>Foo</li>
</ul>
<hr />

A blank line is needed between a paragraph and a following setext heading, since otherwise the paragraph becomes part of the heading’s content:

Example 95Try It 
Foo
Bar
---

<h2>Foo
Bar</h2>

But in general a blank line is not required before or after setext headings:

Example 96Try It 
---
Foo
---
Bar
---
Baz

<hr />
<h2>Foo</h2>
<h2>Bar</h2>
<p>Baz</p>

Setext headings cannot be empty:

Example 97Try It 

====

<p>====</p>

Setext heading text lines must not be interpretable as block constructs other than paragraphs. So, the line of dashes in these examples gets interpreted as a thematic break:

Example 98Try It 
---
---

<hr />
<hr />
Example 99Try It 
- foo
-----

<ul>
<li>foo</li>
</ul>
<hr />
Example 100Try It 
    foo
---

<pre><code>foo
</code></pre>
<hr />
Example 101Try It 
> foo
-----

<blockquote>
<p>foo</p>
</blockquote>
<hr />

If you want a heading with > foo as its literal text, you can use backslash escapes:

Example 102Try It 
\> foo
------

<h2>&gt; foo</h2>

Compatibility note: Most existing Markdown implementations do not allow the text of setext headings to span multiple lines. But there is no consensus about how to interpret

Foo
bar
---
baz

One can find four different interpretations:

  1. paragraph “Foo”, heading “bar”, paragraph “baz”
  2. paragraph “Foo bar”, thematic break, paragraph “baz”
  3. paragraph “Foo bar — baz”
  4. heading “Foo bar”, paragraph “baz”

We find interpretation 4 most natural, and interpretation 4 increases the expressive power of CommonMark, by allowing multiline headings. Authors who want interpretation 1 can put a blank line after the first paragraph:

Example 103Try It 
Foo

bar
---
baz

<p>Foo</p>
<h2>bar</h2>
<p>baz</p>

Authors who want interpretation 2 can put blank lines around the thematic break,

Example 104Try It 
Foo
bar

---

baz

<p>Foo
bar</p>
<hr />
<p>baz</p>

or use a thematic break that cannot count as a setext heading underline, such as

Example 105Try It 
Foo
bar
* * *
baz

<p>Foo
bar</p>
<hr />
<p>baz</p>

Authors who want interpretation 3 can use backslash escapes:

Example 106Try It 
Foo
bar
\---
baz

<p>Foo
bar
---
baz</p>