Setext 标题

setext 标题由一行或多行文本组成,每行包含至少一个非空字符,不超过 3 个空格缩进,后跟 setext 标题下划线。文本行必须是这样的,如果后面没有跟 setext 标题下划线,它们将被解释为段落:它们不能被解释为代码围栏ATX 标题块引用专门的换行列表项HTML 块

setext 标题下划线 是一系列 = 字符或一系列 - 字符,不超过 3 个空格缩进和任意数量的尾随空格。如果一行包含单个的 -,可以解释为空列表项,它应该以这种方式解释,而不是作为 setext 标题下划线的文本。

如果在 setext 标题下划线中使用 = 字符,则标题为 1 级标题,如果使用 - 字符,则标题为 2 级标题。标题的内容是将前面的文本行解析为 CommonMark 内联内容的结果。

通常,setext 标题不必在空白行之前或之后。但是,它不能使段落中断,所以当一个 setext 标题在段落后时,它们之间需要一个空白行。

简单的例子:

示例 50

Markdown HTML 效果
Foo *bar*
=========

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

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

标题的内容可能跨越多行:

示例 51

Markdown HTML 效果
Foo *bar
baz*
====

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

示例 52

Markdown HTML 效果
  Foo *bar
baz*→
====

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

下划线可以是任意长度:

示例 53

Markdown HTML 效果
Foo
-------------------------

Foo
=

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

标题内容最多可缩进三个空格,不需要与下划线对齐:

示例 54

Markdown HTML 效果
   Foo
---

  Foo
-----

  Foo
  ===

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

缩进四个空格太多了:

示例 55

Markdown HTML 效果
    Foo
    ---

    Foo
---

<pre><code>Foo
---

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

setext 标题下划线最多可以缩进三个空格,并且可以有尾随空格:

示例 56

Markdown HTML 效果
Foo
   ----      

<h2>Foo</h2>

四个空格太多了:

示例 57

Markdown HTML 效果
Foo
    ---

<p>Foo
---</p>

setext 标题下划线不能包含内部空格:

示例 58

Markdown HTML 效果
Foo
= =

Foo
--- -

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

内容行中的尾随空格不会导致换行:

示例 59

Markdown HTML 效果
Foo  
-----

<h2>Foo</h2>

最后也没有反斜杠:

示例 60

Markdown HTML 效果
Foo\
----

<h2>Foo\</h2>

由于块结构的优先级优先于内联结构的优先级,因此以下是文本标题:

示例 61

Markdown HTML 效果
`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>

setext 标题下划线不能是列表项或块引用中的懒延续线

示例 62

Markdown HTML 效果
> Foo
---

<blockquote>
<p>Foo</p>
</blockquote>
<hr />

示例 63

Markdown HTML 效果
> foo
bar
===

<blockquote>
<p>foo
bar
===</p>
</blockquote>

示例 64

Markdown HTML 效果
- Foo
---

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

段落和后续 setext 标题之间需要一个空行,否则该段落将成为标题内容的一部分:

示例 65

Markdown HTML 效果
Foo
Bar
---

<h2>Foo
Bar</h2>

但一般来说,在文本标题之前或之后不需要空白行:

示例 66

Markdown HTML 效果
---
Foo
---
Bar
---
Baz

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

Setext 标题不能为空:

示例 67

Markdown HTML 效果

====

<p>====</p>

Setext 标题文本行不能解释为段落以外的块结构。因此,这些示例中的破折号线被解释为专门的换行:

示例 68

Markdown HTML 效果
---
---

<hr />
<hr />

示例 69

Markdown HTML 效果
- foo
-----

<ul>
<li>foo</li>
</ul>
<hr />

示例 70

Markdown HTML 效果
    foo
---

<pre><code>foo
</code></pre>
<hr />

示例 71

Markdown HTML 效果
> foo
-----

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

如果你想要一个带有 > foo 的标题作为它的文字文本,你可以使用反斜杠转义:

示例 72

Markdown HTML 效果
\> foo
------

<h2>&gt; foo</h2>

兼容性说明: 大多数现有的 Markdown 实现不允许 setext 标题的文本跨越多行。 但是对于如何解释没有达成共识

Foo
bar
---
baz

人们可以找到四种不同的解释:

  1. 段落 “Foo”,标题 “bar”,段落 “baz”
  2. 段落 “Foo bar”,专门的换行,段落 “baz”
  3. 段落 “Foo bar - baz”
  4. 标题为 “Foo bar”,段落 “baz”

我们发现解释 4 最自然,解释 4 通过允许多行标题增加了 CommonMark 的表达能力。 想要解释 1 的作者可以在第一段后面加一个空白行:

示例 73

Markdown HTML 效果
Foo

bar
---
baz

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

想要解释 2 的作者可以在专门的换行周围加上空白行,

示例 74

Markdown HTML 效果
Foo
bar

---

baz

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

或使用不能算作setext 标题下划线的专门的换行,例如

示例 75

Markdown HTML 效果
Foo
bar
* * *
baz

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

想要解释 3 的作者可以使用反斜杠转义:

示例 76

Markdown HTML 效果
Foo
bar
\---
baz

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