PHP Markdown Extra 仕様の全訳（意訳） http://michelf.ca/projects/php-markdown/extra/
Markdown拡張仕様であるExtraモードの上記仕様ページを日本語訳したものです。
PHP Markdown Extraは、通常のオリジナルMarkdown記法では利用できない、いくつかの特徴を加えて移植されたPHP Markdown記法の特別なバージョンです。PHP Markdown Extra は、PHP Markdown home pageからダウンロードできます。
このドキュメントでは、PHP Markdown Extraで採用し、Markdown記法に追加した機能や変更を説明しています。このドキュメントを読む前に、オリジナルのMarkdown記法のドキュメントの方に目を通しておくべきでしょう。
- インラインHTML（Inline HTML）
- HTMLブロック内のMarkdown記法（Markdown Inside HTML Blocks）
- 特殊な属性（Special Attributes）
- コードブロック区切り（Fenced Code Blocks）
- 表組み（Tables）
- 定義リスト（Definition Lists）
- 脚注（Footnotes）
- 出力（Output）
- 省略表記（Abbreviations）
- 強調表示（Emphasis）
- バックスラッシュのエスケープ（Backslash Escapes）
従来のMarkdownでは、テキストの中にHTMLを挿入することができます。Markdown記法では書けないとき、HTMLで簡単に書きたいとき、この機能はとても役立ちます。
しかし、ブロック要素を扱うとなると、Markdownには面倒な制限があります。オリジナルのMarkdown記法のドキュメントから引用しましょう。
ブロックレベルのHTML要素、たとえば
<div>,<table>,<pre>,<p>などがある場合、空行で前後を分けないといけません。また、ブロックの開始と終了を示すタグが、タブまたはスペースでインデントされていないことが必要です。
これらの制限を PHP Markdown Extraでは取り払って、より少ない以下の２つの制限に置き換えました。
-
ブロック要素の開始を示すタグは､4つ以上のスペースでインデントしてはいけない｡4つ以上のスペースでインデントされたタグは､標準的なMarkdownのルールに従ってコードブロックとして処理される｡
-
ブロック要素がリストの内側にあるときは､そのブロック要素のインデントはリストのインデントに用いたスペース数と同じにしておくべきである｡(ブロック要素の開始を示すタグが､コードブロックとして処理されてしまうほどにインデントされてなければ､リストのインデント幅を超えてブロック要素をインデントしても問題にはなりません｡ - これは｢1.｣のルール参照のこと｡)
オリジナルのMarkdownでは前提として、<div>要素で囲まれたMarkdown書式のコンテンツを囲むことができません。これは、<div>がブロック要素だからで、オリジナルのMarkdownはそのような内容を書式化しません。
PHP Markdown Extraでは、どのようなブロックレベルのタグ内にも、Markdown書式のテキストを置くことができます。markdownタグ属性の値を1とすることで、実現することができます。たとえば、markdown="1″ というように。
<div markdown="1">
この文章は、*本当は* Markdownテキストで書かれています。
</div>
書かれたmarkdown="1"属性は、取り除かれて、<div>タグ内のコンテンツがMarkdownからHTMLへと変換されます。結果的には、このように出力されます。
<div>
<p>この文章は、<em>本当は</em>Markdownテキストで書かれています。</p>
</div>
PHP Markdown Extraは、markdown属性が加えられたブロックの要素を踏まえて、正しい書式で変換されます。たとえばもし、markdown属性を<p>タグに付けると､そのタグ内にインライン要素がつくられるだけです。リスト、引用（blockquote）、コードブロックなどを同<p>タグ内に含めることはできません｡
また、曖昧な場所があります。たとえば次のような例です。
<table>
<tr>
<td markdown="1">この文章は、*本当は* Markdownテキストで書かれています。</td>
</tr>
</table>
表のセルは、インライン要素とブロック要素を含んでいます。このような場合、PHP Markdown Extraは、インライン要素のルールに従います。もし有効なブロック要素で構築したいのなら、その代わりに markdown="block" とだけ書けば実現できます。
PHP Markdown Extraでは、要素の属性に、idやclass属性を指定することができます。たとえば以下のように､idにしたい文字列に接頭辞（#）を付け波括弧で囲んだものを､見出し文字列以降で行末に来るように書いておきます｡
見出し 1 {#header1}
========
## 見出し 2 ## {#header2}
それから、同じドキュメントのちがう場所に、リンクを生成します。
[見出しへ戻る](#header1)
同様に、class名も、スタイルシートとひもづけて使うことできます。使うときは、ドット（.）で書きます。
## サイト ## {.main}
そのid、複数あるclass名は、同じ特殊な属性ブロック内に、すべて併せて書くことができます。
## サイト ## {.main .shine #the-site}
複数の特殊属性ブロックを使うには、見出し記号で囲まれた形式でのみ使うことができます。
PHP Markdown Extra Version 1.2 では、インデントを使わずにコードブロックを表現することができます。コードブロック区切りは、Markdownの一般的なコードブロック表現と似ていますが、インデントしない代わりに、区切り行の始まりと終わりに境界線を置くことで実現します。３つ以上の ~（チルダ）文字で連なる行で始まり、終端も、始まりと同様に同数のチルダ ~ で表現します。たとえば、このように、
これはパラグラフを表現しています。
~~~~~~~~~~~~~~~~~~~~~
一行のコードブロック
~~~~~~~~~~~~~~~~~~~~~
インデント表現のときとは対照的に、コードブロック区切りは、始まりと終わりに空行を入れることができます。
~~~
空行の前
空行の後ろ
~~~
インデント表現のコードブロックはリストの直後に記述できません。なぜなら、リストのインデントが優先されるためです。ブロックコード区切りを使えば、その制限もまったくありません。
1. リスト項目
インデントされたコードブロックではないが、次のパラグラフは
リスト項目として扱われる
~~~~
ここはコードブロックです。区切り表現によるもの。
~~~~
この表現は､複数行のインデントを一括して変更する機能を持たないエディタ(例えばウェブブラウザーのテキストボックスなど)にコードを貼り付けるような用途にも理想的です｡
また、コードブロックに対して、class名を指定することもできます。これは、言語に応じてちがうコードブロックに異なるスタイルを適用したい場合に役立ちます。このclass名を使えば､適用すべきシンタックスをシンタックスハイライターに対して指定することもできるでしょう｡
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .html
<p>パラグラフ<b>強調</b>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
そのclass名は、最初の区切り記号の最後に書きます。ドットを先に書くこともできますが、これは必須ではありません。特殊属性ブロックのような書き方で使うこともできます。
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.html #example-1}
<p>パラグラフ <b>強調</b>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
HTMLに出力したとき、コードブロック属性は、そのコード要素の属性として割り当てられます。もし、代わりに<pre>要素の属性として割り当てたいのなら、（PHP Markdown Extraの）ファイル先頭にある設定項目の、MARKDOWN_CODE_ATTR_ON_PREを true にします。
PHP Markdown Extra は独自に、シンプルな表組みが実装されています。単純な表組みであれば､次のように書きます。
一番目の題名 | 二番目の題名
------------- | -------------
項目のセル | 項目のセル
項目のセル | 項目のセル
最初の行に、カラムヘッダーを書きます。二行目は、ヘッダーと表の内容とを分ける境界線を必ず書きます。そのあとは、順に必要な表組みの列と行を書いていきます。カラムは、パイプ文字（|）で分かれている必要があります。一度、HTMLに変換してみましょう。結果は次の通りになります。
<table>
<thead>
<tr>
<th>一番目の題名</th>
<th>二番目の題名</th>
</tr>
</thead>
<tbody>
<tr>
<td>項目のセル</td>
<td>項目のセル</td>
</tr>
<tr>
<td>項目のセル</td>
<td>項目のセル</td>
</tr>
</tbody>
</table>
望むなら、表組みの行の最初と最後に、パイプ文字を書くこともできます。好きな方の書式で書くことができ、出力結果は上と同じになります。
| 一番目の題名 | 二番目の題名 |
| ------------- | ------------- |
| 項目のセル | 項目のセル |
| 項目のセル | 項目のセル |
メモ：表組みは、PHP Markdown Extra が正確にパースするために、少なくとも各行につきパイプ文字が一つ必要です。つまり、１カラムのテーブルを作成するときは、行頭か、行末に一つ、あるいはその両方、さらに各項目行にも必要ということを意味します。
各カラムの行揃えを指定したいときは、境界線にコロン（:）を追加します。コロン文字が、境界線の左にあれば、カラムは左寄せとなります。同様に、コロン文字が右にあれば、右寄せになります。両サイドに挿入した場合は、センタリングされます。
| 項目 | 価格 |
| --------- | --------:|
| パソコン | \160000 |
| 電話 | \12000 |
| 水道管 | \1000 |
HTMLのalign属性によって､行揃え設定が対象列の各セルに指定されます｡
また、インライン書式であれば、各セルの中に一般的なMarkdown記法を使うことができます。
| 関数名 | 説明 |
| ------------- | ------------------------------ |
| `help()` | ヘルプウィドウを表示します。 |
| `destroy()` | **パソコンが壊れます！** |
PHP Markdown Extra では、定義リスト（<dl>）を実装しています。定義リストは、辞典のように、単語とその単語の定義（説明）によって構成されます。
PHP Markdown Extra による、シンプルな定義リストは、一行の単語と、それに続くコロン文字（:）と、定義内容によって構成されます。
りんご
: バラ科の一種で、カイドウ類、
梨果属の果物。
みかん
: 柑橘系の常緑樹から採れる果物。
複数の定義を書く場合､単語の行と直前の定義内容行は空行で区切る必要があります｡定義内容は複数行に及んでもよく､その場合はインデントされるべきです｡とはいえ､インデントは必須ではありません｡面倒くさいですものね｡複数行に及ぶ定義内容はインデントしなくても正しく処理されます｡
りんご
: バラ科の一種で、カイドウ類、
梨果属の果物。
みかん
: 柑橘系の常緑樹から採れる果物。
これらの定義リストは、いずれも以下の様な同一のHTMLとして出力されます｡
<dl>
<dt>りんご</dt>
<dd>バラ科の一種で、カイドウ類、
梨果属の果物。</dd>
<dt>みかん</dt>
<dd>柑橘系の常緑樹から採れる果物。</dd>
</dl>
定義識別子を表すコロン文字は、一般に左端から始めますが、スペースが３つになるまでインデントできます。定義識別子の後は、１つ、もしくは複数のスペースやタブを空けなければなりません｡
定義リストは、一つの単語とひもづく、二つ以上の定義内容を持つことができます。
りんご
: バラ科の一種で、カイドウ類、梨果属の果物。
: アメリカのコンピューター会社。
みかん
: 柑橘系の常緑樹から採れる果物。
一つの定義内容に対して、二つ以上の単語をヒモ付けることもできます。
定義１
定義２
: 定義内容Ａ
定義３
: 定義内容Ｂ
空行を先に書いてから定義内容を書くと、PHP Markdown Extra は定義内容を<p>タグで囲み、HTML出力します。たとえば、このようにやります。
りんご
: バラ科の一種で、カイドウ類、梨果属の果物。
みかん
: 柑橘系の常緑樹から採れる果物。
これらは、次のように変換されます。
<dl>
<dt>りんご</dt>
<dd>
<p>バラ科の一種で、カイドウ類、梨果属の果物。</p>
</dd>
<dt>みかん</dt>
<dd>
<p>柑橘系の常緑樹から採れる果物。</p>
</dd>
</dl>
また、よくある一般的なリスト項目のように、定義内容には複数のパラグラフを含むことができます｡他のブロック要素、引用（blockquote）や、コードブロック、リスト、他の定義リストでさえも、含めることができます。
定義１
: これは二つのパラグラフからなる定義です。 Lorem ipsum
dolor sit amet, consectetuer adipiscing elit. Aliquam
hendrerit mi posuere lectus.
Vestibulum enim wisi, viverra nec, fringilla in, laoreet
vitae, risus.
: 定義１の二つ目の定義内容です。また、前に空行があるので、
パラグラフに囲まれていると判断されます。
定義２
: この定義内容はコードブロック、引用、リストを含みます。
コードブロック。
> 引用句
> その二行目
1. 最初のリスト項目
2. 二番目のリスト項目
脚注は、主としてリファレンス形式のリンクとして機能します。脚注は、二つの事柄からなります。テキスト内の識別子が上付き数字に変換されます｡その脚注定義は、ドキュメントの最後に書かれた脚注リストの中にあります。たとえば、次のように書きます。
それは脚注[^1]のついたいくつかのテキストです。
[^1]: そして、それがこの脚注になります。
脚注定義は、ドキュメント内であればどこにあってもかまいませんが、脚注はその識別子が本文内に書かれた順番で並ぶことになります｡注意点として、同じ脚注に対して、二つのリンクを張ることはできません。もしそれをした場合、二番目の脚注参照は、そのままテキストとして残ります。
各脚注は、異なる名前にしなければいけません。その名前は、脚注部分と脚注参照元を繋ぐために使われますが、脚注部分に付与される番号と直接的な影響はありません。それらの名前はHTMLのid属性として有効なら、どのような文字でも使えます。
脚注は、ブロック要素を含むことができます。すなわち複数のパラグラフ、リスト、引用、その他の脚注を置けるということを意味します。リスト項目とまったく同じように動作し、脚注内で４つのスペースのインデント後にパラグラフを続けて書いていきます。
それは脚注[^1]のついたいくつかのテキストです。
[^1]: そして、それがこの脚注になります。
その二番目のパラグラフです。
もしも、行を揃えたいのなら、脚注の最初の行を空にしてから、次の行から最初のパラグラフを書いていくことができます。
[^1]:
そして、それがこの脚注になります。
その二番目のパラグラフです。
おそらく､単一の脚注出力ですべての人を満足させるのは不可能でしょう。今後のバージョンアップで、異なる脚注出力を可能にするようなプログラミングインターフェースを提供するかもしれません。しかし、現在のところ、出力は、ほとんとちがいのないオリジナルのMarkdownの仕様に従います。ここでは、最初に挙げたサンプルから、デフォルトの出力結果を示します。
<p>それは脚注<sup id="fnref:1"><a href="#fn:1" rel="footnote">1</a></sup>のついたいくつかのテキストです。</p>
<div class="footnotes">
<hr />
<ol>
<li id="fn:1">
<p>そして、それがこの脚注になります。
<a href="#fnref:1" rev="footnote">↩</a></p>
</li>
</ol>
</div>
少し暗号めいていますが､ブラウザーだとこのように見えます。
-
そして、それがこの脚注になります。 ↩
リンク上の、rel と、rev 属性は、互いにリンクしている関係を表現しています。リファレンスリンク（すなわち、rel="footnote" ）は、脚注に誘導され、戻るリンク（すなわち、rev="footnote" ）は脚注から戻って来ます。それらは、CSSルールで書けば、このように使われるでしょう。
a[rel="footnote"]
a[rev="footnote"]
脚注リンクと戻るリンクの、class と、title 属性値はカスタマイズすることができます。（PHP Markdown Extraの）ファイル先頭には、これらに関連する四つの設定可能項目があります。これらの属性値内では､%% の部分は、全て該当する脚注番号に置き換わります。たとえば、このように使うことができるでしょう。
define( 'MARKDOWN_FN_LINK_TITLE', "Go to footnote %%." );
PHP Markdown Extra は、（HTMLタグの にあるような）省略表記をサポートしています。とても簡単にできます。次のように省略表記の定義を作ってください。
*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium
それから、ドキュメントの他の場所で、以下のテキストのように書きます。
そのHTMLタグの仕様は、
W3Cによって管理されています。
そして、テキスト内のそれらの定義された単語は、すべて以下のようになります。
その <abbr title="Hyper Text Markup Language">HTML</abbr> タグ仕様は、
<abbr title="World Wide Web Consortium">W3C</abbr>によって管理されています。
省略表記は、大文字小文字を区別します｡また､複数の単語に対し一つの省略表記を定義した場合は､それらの単語に対し省略を展開します。もし省略表記が定義されていないときは、<abbr>タグがテキストに追加されます。ただし、title 属性は除外されます。
ティグラ・ジェネシス作戦は順調だ。
*[ティグラ・ジェネシス]:
省略表記の定義は、ドキュメント内のどこにでも書けます。それらは最終的な出力ドキュメントからは、削除されます。
強調表示のルールは、オリジナルのMarkdown記法からは少しだけ変更されています。PHP Markdown Extra では、単語を繋ぐようにして使われているアンダースコア文字は、文字列として扱われます。アンダースコア文字による強調表示は、単語を囲むようにして使われた場合のみ機能します。もしいくつかの単語だけで強調表示が必要なら、強調表示記号のアスタリスクを使うことで可能です。
たとえば、このように書きます。
"secret_magic_box"フォルダーを開いてください。
PHP Markdown Extra では、単語の中にアンダースコアがあるので、強調表示として変換されません。その出力されるHTMLは、このようになります。
<p>"secret_magic_box"フォルダーを開いてください。 </p>
アンダースコアによる強調表示を行うには、単語全体に対して使います。
_キミがボクを愛してる_というのがいいね
<strong>の強調表示も同じです。PHP Markdown Extra では、単語の中でアンダースコアを使うことが強調表示とはなりませんので、そうしたい場合は強調表示記号であるアスタリスクを使わなくてはいけません。
PHP Markdown Extra では、バックスラッシュ（)でエスケープ可能な文字列にコロン文字（:）と、パイプ文字（|）を追加しました｡これらの文字をバックスラッシュでエスケープすることで､意図しない定義リスト（dl）や表組み（table）への変換を避けることができます。