diff options
| -rw-r--r-- | test/spec.txt | 129 |
1 files changed, 105 insertions, 24 deletions
diff --git a/test/spec.txt b/test/spec.txt index f0a54ea..e4a9ee3 100644 --- a/test/spec.txt +++ b/test/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: . @@ -959,6 +971,18 @@ line] in a list item or block quote: . . +> 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>> 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 |