Libx CommonMark 基礎と葉ブロック

    このページの内容

    4.3Setext見出し

    Setext見出しは、空行による中断のない1行以上のテキストと、それに続くSetext見出しの下線からなります。テキストの最初の行の字下げは、3個のスペースを超えてはいけません。これらのテキスト行は、後ろにSetext見出しの下線がなければ段落として解釈されるものでなければなりません。つまり、コードフェンス、ATX見出し、ブロック引用、主題区切り、リスト項目、HTMLブロックとして解釈できるものであってはいけません。

    Setext見出しの下線は、=を並べた列、または-を並べた列で、先頭の字下げは最大3個のスペース、末尾には任意の数のスペースやタブを置けます。

    =をSetext見出しの下線に使うとレベル1の見出しになり、-を使うとレベル2になります。見出しの内容は、直前のテキスト行をCommonMarkのインライン内容として解析した結果です。

    一般に、Setext見出しの前後に空行は必要ありません。ただし、段落を中断することはできないので、段落の後にSetext見出しが続く場合は、両者の間に空行が必要です。

    単純な例です。

    例80 
    Foo *bar*
=========

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

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

    見出しの内容は、複数行にまたがっていてもかまいません。

    例81 
    Foo *bar
baz*
====

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

    内容は、見出しの生の内容をインラインとして解析した結果です。見出しの生の内容は、各行をつなぎ、先頭と末尾のスペースやタブを取り除いて作ります。

    例82 
      Foo *bar
baz*	
====

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

    下線の長さは任意です。

    例83 
    Foo
-------------------------

Foo
=

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

    見出しの内容の前には、最大3個のスペースによる字下げを置けます。また、下線と位置をそろえる必要はありません。

    例84 
       Foo
---

  Foo
-----

  Foo
  ===

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

    4個のスペースによる字下げは多すぎます。

    例85 
        Foo
    ---

    Foo
---

    <pre><code>Foo
---

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

    Setext見出しの下線の前には、最大3個のスペースによる字下げを置けます。末尾にはスペースやタブを置けます。

    例86 
    Foo
   ----      

    <h2>Foo</h2>

    4個のスペースによる字下げは多すぎます。

    例87 
    Foo
    ---

    <p>Foo
---</p>

    Setext見出しの下線の内部に、スペースやタブを含めることはできません。

    例88 
    Foo
= =

Foo
--- -

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

    内容行の末尾のスペースやタブは、ハード改行にはなりません。

    例89 
    Foo  
-----

    <h2>Foo</h2>

    末尾のバックスラッシュも、ハード改行にはなりません。

    例90 
    Foo\
----

    <h2>Foo\</h2>

    ブロック構造を示す記号はインライン構造を示す記号より優先されるため、次の例はSetext見出しになります。

    例91 
    `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見出しの下線は、リスト項目やブロック引用の省略継続行（lazy continuation line）であってはいけません。

    例92 
    > Foo
---

    <blockquote>
<p>Foo</p>
</blockquote>
<hr />
    例93 
    > foo
bar
===

    <blockquote>
<p>foo
bar
===</p>
</blockquote>
    例94 
    - Foo
---

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

    段落と、それに続くSetext見出しの間には、空行が必要です。そうしないと、その段落も見出しの内容の一部になります。

    例95 
    Foo
Bar
---

    <h2>Foo
Bar</h2>

    ただし、一般にSetext見出しの前後に空行は必要ありません。

    例96 
    ---
Foo
---
Bar
---
Baz

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

    Setext見出しは空にできません。

    例97 
    
====

    <p>====</p>

    Setext見出しのテキスト行は、段落以外のブロック構造として解釈できるものであってはいけません。そのため、これらの例ではハイフンの行は主題区切りとして解釈されます。

    例98 
    ---
---

    <hr />
<hr />
    例99 
    - foo
-----

    <ul>
<li>foo</li>
</ul>
<hr />
    例100 
        foo
---

    <pre><code>foo
</code></pre>
<hr />
    例101 
    > foo
-----

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

    > fooを文字どおりのテキストとする見出しが必要なら、バックスラッシュによるエスケープを使えます。

    例102 
    \> foo
------

    <h2>&gt; foo</h2>

    互換性についての注記: 既存のMarkdown実装のほとんどは、Setext見出しのテキストが複数行にまたがることを許していません。しかし、次の内容をどう解釈するかについて、合意はありません。

    Foo
bar
---
baz

    4つの異なる解釈が見られます。

    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”

    私たちは解釈4が最も自然だと考えています。また、解釈4は複数行の見出しを許すことで、CommonMarkの表現力を高めます。解釈1を望む書き手は、最初の段落の後に空行を置けます。

    例103 
    Foo

bar
---
baz

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

    解釈2を望む書き手は、主題区切りの前後に空行を置けます。

    例104 
    Foo
bar

---

baz

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

    または、Setext見出しの下線にはならない主題区切りを使えます。たとえば次のようにします。

    例105 
    Foo
bar
* * *
baz

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

    解釈3を望む書き手は、バックスラッシュによるエスケープを使えます。

    例106 
    Foo
bar
\---
baz

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