BlueFeather マニュアル

# Markdown記法の拡張

BlueFeatherでは、従来のMarkdown記法に加え、PHP Markdown Extraなどから多くの拡張を取り込んでいます。

- PHP Markdown Extra
  - 定義リスト（dl）
  - 脚注
  - ID付き見出し
  - 仕切り付きコードブロック
  - 表組み
  - PHP Markdown Extra との違い
- 独自拡張
  - 目次
  - 強制ブロック区切り

## PHP Markdown Extra

- 元々の PHP Markdown Extra については、http://michelf.com/projects/php-markdown/extra/ を参照してください。

### 定義リスト（dl）

定義語と `:` 記号から始まる説明文の組み合わせは、定義リストとして変換されます。

    みかん
    : オレンジ色で甘酸っぱい。

    りんご
    : 赤くて甘い。

> みかん
>   オレンジ色で甘酸っぱい。
> りんご
>   赤くて甘い。

定義語や説明文は、それぞれ複数重ねることもできます。

    みかん
    : オレンジ色。
    : 甘酸っぱい。

    りんご
    アップル
    : 赤くて甘い。

> みかん
>   オレンジ色。
>   甘酸っぱい。
> りんご
> アップル
>   赤くて甘い。

また、定義語と説明文の間に空行を挟むと、説明文を段落（p要素）にすることができます。 さらにその後にインデント付きで、他のブロック要素（リストなど）を含めることもできます。

    みかん

    : オレンジ色で甘酸っぱく、ジュースにもなる。

    りんご

    : 以下のような特徴を持つ。

        * 甘い
        * 見た目は赤くて丸い（青いのもある）
        * 皮にも栄養がある

> みかん

>   オレンジ色で甘酸っぱく、ジュースにもなる。

> りんご

>   以下のような特徴を持つ。

>   - 甘い
>   - 見た目は赤くて丸い（青いのもある）
>   - 皮にも栄養がある

### 脚注

次のように書くことで、任意の箇所に脚注を付けることができます。

    チャルメラ醤油味は、卵を入れる[^1]と美味しく作ることができる。

    [^1]: できあがり直前に弱火にしてから割り入れて、短時間だけ煮込むのがコツ。

> チャルメラ醤油味は、卵を入れる[1]と美味しく作ることができる。

脚注の定義（できあがり直前に～）は、文書中のどこに書いても構いません。

また、脚注には番号でなく、任意のIDを付けることもできます。 その場合であっても、ブラウザ上の表示ではIDに関わらず連番が振られます。

    チャルメラとんこつ味には、もやし[^moyashi]がよく合う。

    [^moyashi]: 歯応え重視で太めのもやしを選ぶのがお奨め。

> チャルメラとんこつ味には、もやし[2]がよく合う。

### ID付き見出し

任意の見出し（h*要素）の後ろに次のように書くことにより、その見出しにIDを付け、リンクすることが出来ます。

    レシピ {#recipe}
    ----

    [「レシピ」の項](#recipe)を参照してください。

    ## レシピ ## {#recipe}

    [「レシピ」の項](#recipe)を参照してください。

> ## レシピ

> 「レシピ」の項を参照してください。

なお、見出しの内容とID記述の間には空白を入れても構いませんが、ID記述の直後に改行以外を入れてはいけません。

### 仕切り付きコードブロック

    ~~~
    3つ以上のチルダ記号（~）がある行から、同じ数のチルダ記号がある行までは
    丸ごとコードブロックとして扱われます。
    ~~~

>     3つ以上のチルダ記号（~）がある行から、同じ数のチルダ記号がある行までは
>     丸ごとコードブロックとして扱われます。

### 表組み

パイプ記号（`|`）でセルを区切ることで、表組みを作ることができます。 1行目に項目名（ヘッダ）を、2行目に項目名とデータの区切りを、3行目以降にデータを記入してください。

    |名前  |色      |個数|

    3e7f357d60f9294f22d53da11c533a4d

> 名前 | 色 | 個数
> --- | --- | ---
> りんご | 赤 | 8
> みかん | オレンジ | 32

右端のパイプ記号や、セルの見た目を揃えるための空白は省略可能です。そのため、以下の例はどちらも有効です。

    |名前  |色      |個数

    3e7f357d60f9294f22d53da11c533a4d

    41c743822aad8b2633eb368791a3de83

ただし、PHP Markdown Extraと異なり、左端のパイプ記号は省略することができません。ご注意ください。

2行目の区切り部、右端にコロン記号（`:`）を付けることにより、その列を右寄せにすることができます。 また、両端に同じ記号を付けると中央寄せになります。

    |名前  |色      |個数|

    8894f831376be36f9e7e9cb4bcb095a5

> 名前 | 色 | 個数
> --- | --- | ---
> りんご | 赤 | 8
> みかん | オレンジ | 32

### PHP Markdown Extra との違い

- PHP Markdown Extra ではブロック要素のHTMLタグをインデントできるように変更されていますが、BlueFeather ではインデントは許可されません（本家 Markdown と同じ）。

- PHP Markdown Extra では、以下のような記述のときには強調を行わない仕様になっています。

      Please open the folder "secret_magic_box".

  ですが、BlueFeather ではこの場合でも強調を行います（本家 Markdown と同じ）。

- Markdown Inside HTML Blocks （HTML内でのMarkdown記法）、およびAbbreviations（略語定義）には対応していません。

- 表組みの左側のパイプ記号（ボーダー）は必須です。

## 独自拡張

### 目次

行頭に `{toc}` と記入することにより、その位置に目次（テキスト内にある見出しの一覧）を表示させることができます。

    {toc}

> - PHP Markdown Extra
>   - 定義リスト（dl）
>   - 脚注
>   - ID付き見出し
>   - 仕切り付きコードブロック
>   - 表組み
>   - PHP Markdown Extra との違い
> - 独自拡張
>   - 目次
>   - 強制ブロック区切り

また、どのレベルからの見出しを目次に含めるかを指定することもできます。 たとえば、次の例であれば、h1 ～ h2 は無視され、h3 ～ h6 のみが目次に含まれます。

    {toc:h3..}

> - 定義リスト（dl）
> - 脚注
> - ID付き見出し
> - 仕切り付きコードブロック
> - 表組み
> - PHP Markdown Extra との違い
> - 目次
> - 強制ブロック区切り

指定がなかった場合には、標準で h2 ～ h6 が目次に含まれます。

見出しレベルの指定には、以下のような書き方を使うことができます。

    {toc:h3-}    (上記の例と同じ）
    {toc:h3}     (h3 のみ）
    {toc:h3..h4} (h3 ～ h4）
    {toc:..h4}   (h2 ～ h4)

なお、目次にリストアップされるのは、Markdown記法の変換によって生成され、なおかつ他のブロック要素に含まれていない見出しのみです。 つまり、次のような見出しは目次に含まれません。

    <h2>目次に含まれない見出し</h2>

    > ## 目次に含まれない見出し ##

### 強制ブロック区切り

通常、リストやコードブロックは、間に空行があっても一つのブロックに結合されます。 しかし、連続して2つ以上のリストを置きたい場合など、この動作を抑制したいケースがあります。

    1. リスト1項目1
    2. リスト1項目2
    3. リスト1項目3

    1. リスト2項目1
    2. リスト2項目2
    3. リスト2項目3

    <ol>
    <li>リスト1項目1</li>
    <li>リスト1項目2</li>
    <li><p>リスト1項目3</p></li>
    <li><p>リスト2項目1</p></li>
    <li>リスト2項目2</li>
    <li>リスト2項目3</li>
    </ol>

ひとつの解決策は、間に水平線を挟むことです。

    1. リスト1項目1
    2. リスト1項目2
    3. リスト1項目3

    ----

    1. リスト2項目1
    2. リスト2項目2
    3. リスト2項目3

    <ol>
    <li>リスト1項目1</li>
    <li>リスト1項目2</li>
    <li>リスト1項目3</li>
    </ol>

    <hr />

    <ol>
    <li>リスト2項目1</li>
    <li>リスト2項目2</li>
    <li>リスト2項目3</li>
    </ol>

しかし、水平線を使わずに区切りたい場合もあるでしょう。 そういった場合、BlueFeather では行にチルダ記号（~）を1つだけ置くことで、その行でリストやコードブロックを強制的に区切ることができます。

    ~

たとえば、次のように使うことが出来ます。

    1. リスト1項目1
    2. リスト1項目2
    3. リスト1項目3

    ~

    1. リスト2項目1
    2. リスト2項目2
    3. リスト2項目3

    <ol>
    <li>リスト1項目1</li>
    <li>リスト1項目2</li>
    <li>リスト1項目3</li>
    </ol>

    <ol>
    <li>リスト2項目1</li>
    <li>リスト2項目2</li>
    <li>リスト2項目3</li>
    </ol>

1. できあがり直前に弱火にしてから割り入れて、短時間だけ煮込むのがコツ。 ↩

2. 歯応え重視で太めのもやしを選ぶのがお奨め。 ↩