Permalink
Browse files

Modified setext heading spec to allow multiline headings.

Text like

    Foo
    bar
    ---
    baz

is now interpreted as heading + paragraph, rather than
paragraph + thematic break + paragraph.

Existing implementations diverge quite a bit on this
case, with several interpretations:

1. paragraph, heading, paragraph
2. paragraph, break, paragraph
3. paragraph containing literal `---`
4. heading, paragraph

Interpretation 4 seems most natural, and it opens up an expressive
possibility otherwise closed off -- multiline headings.

Authors who want interpretation 2 can use a form that can't be
interpreted as a setext heading line, e.g.

    Foo
    bar
    * * *
    baz

or insert blank space around the thematic break.

Authors who want interpretation 3 can use backslash escapes.

Authors who want interpretation 1 can put a blank line
after the first paragraph.
  • Loading branch information...
jgm committed Jan 8, 2016
1 parent 2136f82 commit ca7a7fa7ad536ce4e1f3004ec1e718a1d1d8b1f7
Showing with 105 additions and 24 deletions.
  1. +105 −24 spec.txt
View
129 spec.txt
@@ -786,12 +786,12 @@ ATX headings can be empty:
## Setext headings
A [setext heading](@setext-heading)
consists of a line of text, containing at least one [non-whitespace character],
with no more than 3 spaces indentation, followed by a [setext heading
underline]. The line of text must be
one that, were it not followed by the setext heading underline,
would be interpreted as part of a paragraph: it cannot be
A [setext heading](@setext-heading) consists of one or more
lines of text, each containing at least one [non-whitespace
character], with no more than 3 spaces 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][ATX headings],
[block quote][block quotes], [thematic break][thematic breaks],
[list item][list items], or [HTML block][HTML blocks].
@@ -803,10 +803,11 @@ containing a single `-` can be interpreted as an
empty [list items], it should be interpreted this way
and not as a [setext heading underline].
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 first line as Markdown inline content.
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
@@ -826,6 +827,17 @@ Foo *bar*
<h2>Foo <em>bar</em></h2>
.
The content of the header may span more than one line:
.
Foo *bar
baz*
====
.
<h1>Foo <em>bar
baz</em></h1>
.
The underlining can be any length:
.
@@ -958,6 +970,18 @@ line] in a list item or block quote:
<hr />
.
.
> foo
bar
===
.
<blockquote>
<p>foo
bar
===</p>
</blockquote>
.
.
- Foo
---
@@ -968,26 +992,21 @@ line] in a list item or block quote:
<hr />
.
A setext heading cannot interrupt a paragraph:
A blank line is needed between a paragraph and a following
setext heading, since otherwise the paragraph becomes part
of the heading's content:
.
Foo
Bar
---
Foo
Bar
===
.
<p>Foo
Bar</p>
<hr />
<p>Foo
Bar
===</p>
<h2>Foo
Bar</h2>
.
But in general a blank line is not required before or after:
But in general a blank line is not required before or after
setext headings:
.
---
@@ -1063,6 +1082,68 @@ use backslash escapes:
<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
``` markdown
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:
``` markdown
Foo
bar
---
baz
```
Authors who want interpretation 2 can put blank lines around
the thematic break,
``` markdown
Foo
bar
---
baz
```
or use a thematic break that cannot count as a [setext heading
line], such as
``` markdown
Foo
bar
* * *
baz
```
Authors who want interpretation 3 can use backslash escapes:
``` markdown
Foo
bar
\---
baz
```
## Indented code blocks
An [indented code block](@indented-code-block) is composed of one or more
@@ -8221,8 +8302,8 @@ markers like `>`, list markers, and indentation have been consumed).
This is text that can be incorporated into the last open
block (a paragraph, code block, heading, or raw HTML).
Setext headings are formed when we detect that the second line of
a paragraph is a setext heading line.
Setext headings are formed when we see a line of a paragraph
that is a setext heading line.
Reference link definitions are detected when a paragraph is closed;
the accumulated text lines are parsed to see if they begin with

0 comments on commit ca7a7fa

Please sign in to comment.