PHP Markdown Extra 仕様の全訳（意訳）

PHP_Markdown_Extra.md

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）

---

インラインHTML（Inline HTML）

従来のMarkdownでは、テキストの中にHTMLを挿入することができます。Markdown記法では書けないとき、HTMLで簡単に書きたいとき、この機能はとても役立ちます。

しかし、Markdownはブロック要素が来たとき、面倒な制限があります。オリジナルのMarkdown記法のドキュメントから引用しましょう。

ブロックレベルのHTML要素、たとえば　<div>, <table<, <pre&gt, <p&gtなどがある場合、空行で前後を分けないといけません。また、初めのブロックタグと、終わりのブロックタグが、タブまたはスペースでインデントされていないことが必要です。

これらの制限を PHP Markdown Extraでは取り払って、より少ない以下の２つの制限に置き換えました。

1. ブロック要素タグの始まりは、３つより多いスペースでインデントしてはいけない。インデントはいくつでも良く、いずれのタグも、標準的なMarkdownのルールに従って、コードブロックとして扱われる。

2. ブロック要素が、リストの内側にあるときは、そのコンテンツはすべて、リスト項目として同じ量のスペースでインデントされる。（最初のタグがそれほどインデントが多くせずともコードブロックになれば、さらに多くのインデントを入れる必要もなくなり、その弊害はなくなるでしょう。 – これは前述の「1.」のルール参照のこと。）

HTMLブロック内のMarkdown記法（Markdown Inside HTML Blocks）

オリジナルのMarkdownでは前提として、<div>要素で囲まれたMarkdown書式のコンテンツを囲むことができません。これは、<div>がブロック要素だからで、オリジナルのMarkdownはそのような内容を書式化しません。

PHP Markdown Extraでは、どのようなブロックレベルのタグ内にも、Markdown書式のテキストを置くことができま。markdownタグ属性の値を1とすることで、実現することができます。たとえば、markdown="1″ というように。

<div markdown="1">
この文章は、*本当は* Markdownテキストで書かれています。
</div>

書かれた markdown="1″ 属性は、取り除かれて、

内のコンテンツがMarkdownからHTMLへと変換されます。結果的には、このように出力されます。

<div>

<p>この文章は、<em>本当は</em>Markdownテキストで書かれています。</p>

</div>

PHP Markdown Extraは、markdown属性が加えられたブロックの要素を踏まえて、正しい書式で変換されます。たとえばもし、markdown属性を

タグに付けたならば、それはインライン要素がつくられるだけです。また、リスト、引用（blockquote）、コードブロックなどでは機能しません。

また、曖昧な場所があります。たとえば次のような例です。

<table>
<tr>
<td markdown="1">この文章は、*本当は* Markdownテキストで書かれています。</td>
</tr>
</table>

表のセルは、インライン要素とブロック要素を含んでいます。このような場合、PHP Markdown Extraは、インライン要素のルールに従います。もし有効なブロック要素で構築したいのなら、その代わりに markdown="block"　とだけ書けば実現できます。

特殊な属性（Special Attributes）

PHP Markdown Extraでは、要素の属性に、idやclass属性を指定することができます。たとえば、見出し行の終わりから、さらに後ろに、波括弧に囲まれた文字列に接頭辞（#）を付けたidを設置します。次のように書きます。

見出し 1            {#header1}
========

## 見出し 2 ##      {#header2}

それから、同じドキュメントのちがう場所に、リンクを生成します。

[見出しへ戻る](#header1)

同様に、class名も、スタイルシートとひもづけて使うことできます。使うときは、ドット（.）で書きます。

## サイト ##    {.main}

そのid、複数あるclass名は、同じ特殊な属性ブロック内に、すべて併せて書くことができます。

## サイト ##    {.main .shine #the-site}

複数の特殊属性ブロックを使うには、見出し記号で囲まれた形式でのみ使うことができます。

コードブロック区切り（Fenced Code Blocks）

PHP Markdown Extra Version 1.2 では、インデントを使わずにコードブロックを表現することができます。コードブロック区切りは、Markdownの一般的なコードブロック表現と似ていますが、インデントしない代わりに、区切り行の始まりと終わりに境界線を置くことで実現します。３つ以上の ~（チルダ）文字で連なる行で始まり、終端も、始まりと同様に同数のチルダ ~ で表現します。たとえば、このように、

これはパラグラフを表現しています。

~~~~~~~~~~~~~~~~~~~~~
一行のコードブロック
~~~~~~~~~~~~~~~~~~~~~

インデント表現のときとは対照的に、コードブロック区切りは、始まりと終わりに空行を入れることができます。

~~~

空行の前
空行の後ろ

~~~

インデント表現のコードブロックは、次のようなリストをすぐに使うことはできません。なぜなら、リストのインデントが、先行しているためです。ブロックコード区切りを使えば、その制限もまったくありません。

1.  リスト項目

    インデントされたコードブロックではないが、次のパラグラフは
    リスト項目として扱われる

~~~~
ここはコードブロックです。区切り表現によるもの。
~~~~

ブロックコード区切り表現はまた、いくつかのソースコードをウェブブラウザーのテキストボックスのようなものからエディタへ貼り付けるときなどで理想的です。挿入するテキストに、いちいちインデントを追加していく必要もないからです。

また、コードブロックに対して、class名を指定することもできます。これは、言語に応じて、ちがうコードブロックに異なるスタイルを適用したい場合に役立ちます。また、何らかのシンタックスハイライターを呼び出して使うことを想定しています。

‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾ .html
<p>パラグラフ<b>強調</b>
‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾

そのclass名は、最初の区切り記号の最後に書きます。ドットを先に書くこともできますが、これは必須ではありません。特殊属性ブロックのような書き方で使うこともできます。

‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾ {.html #example-1}
<p>パラグラフ <b>強調</b>
‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾

HTMLに出力したとき、コードブロック属性は、そのコードの要素に割り当てることができます。もし、代わりに

要素として表示させたいのなら、（PHP Markdown Extraの）ファイル先頭にある設定項目の、MARKDOWN_CODE_ATTR_ON_PREを true にします。

表組み（Tables）

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()`   | **パソコンが壊れます！**       |

定義リスト（Definition Lists）

PHP Markdown Extra では、定義リスト（<dl>）を実装しています。定義リストは、辞典のように、単語とその単語の定義（説明）によって構成されます。
PHP Markdown Extra による、シンプルな定義リストは、一行の単語と、それに続くコロン文字（:）と、定義内容によって構成されます。
りんご
:   バラ科の一種で、カイドウ類、梨果属の果物。

みかん
:   柑橘系の常緑樹から採れる果物。

これらの定義リストは、HTMLにすると、以下のように出力されます。
<dl>
<dt>りんご</dt>
<dd>バラ科の一種で、カイドウ類、梨果属の果物。</dd>

<dt>みかん</dt>
<dd>柑橘系の常緑樹から採れる果物。</dd>
</dl>

定義を表すコロン文字は、一般に左端から始めますが、スペースが３つになるまでインデントできます。定義を表す文字の後は、１つ、もしくは複数のスペースやタブを空けてから続けて書いていきます。
定義リストは、一つの定義とひもづく、一つ以上の定義内容を持つことができます。
りんご
:   バラ科の一種で、カイドウ類、梨果属の果物。
:   アメリカのコンピューター会社。

みかん
:   柑橘系の常緑樹から採れる果物。

定義内容に対して、一つ以上の定義をヒモ付けることもできます。
定義１
定義２
:   定義内容Ａ

定義３
:   定義内容Ｂ

空行を先に書いてから定義内容を書くと、PHP Markdown Extra は定義内容を
タグで囲み、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.  二番目のリスト項目

脚注（Footnotes）

脚注は、主としてリファレンス形式のリンクとして機能します。脚注は、二つの事柄からなります。テキスト内の記号が上付きの数字として表現されます。その脚注定義は、ドキュメントの最後に書かれた脚注リストの中にあります。たとえば、次のように書きます。
それは脚注[^1]のついたいくつかのテキストです。

[^1]: そして、それがこの脚注になります。

脚注定義は、ドキュメント内であればどこにあってもかまいませんが、脚注は常にそのテキスト内で、リンクされた順番でリストされている必要があります。注意点として、同じ脚注に対して、二つのリンクを張ることはできません。もしそれをした場合、二番目の脚注参照は、そのままテキストとして残ります。
各脚注は、異なる名前にしなければいけません。その名前は、脚注と定義される脚注リンクとして使われますが、脚注のナンバリングとの直接的な影響はありません。それらの名前は、HTMLのid属性として有効なら、どのような文字でも使えます。
脚注は、ブロック要素を含むことができます。すなわち複数のパラグラフ、リスト、引用、その他の脚注を置けるということを意味します。リスト項目とまったく同じように動作し、脚注内で４つのスペースのインデント後にパラグラフを続けて書いていきます。
それは脚注[^1]のついたいくつかのテキストです。

[^1]: そして、それがこの脚注になります。

    その二番目のパラグラフです。

もしも、行を揃えたいのなら、脚注の最初の行を空にしてから、次の行から最初のパラグラフを書いていくことができます。
[^1]:
    そして、それがこの脚注になります。

    その二番目のパラグラフです。

出力（Output）

おそらく一つの脚注だけでは、すべての人が満足できないでしょう。将来的なバージョンで、異なるマークアップから、脚注の生成を許可するプログラミングインターフェースを提供するかもしれません。しかし、現在のところ、出力は、ほとんとちがいのないオリジナルの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">&#8617;</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 %%." );

省略表記（Abbreviations）

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 属性は除外されます。
ティグラ・ジェネシス作戦は順調だ。

*[ティグラ・ジェネシス]:

省略表記の定義は、ドキュメント内のどこにでも書けます。それらは最終的な出力ドキュメントからは、削除されます。
強調表示（Emphasis）

強調表示のルールは、オリジナルのMarkdown記法からは少しだけ変更されています。PHP Markdown Extra では、単語の中にあるアンダースコア文字は、文字列として扱われます。アンダースコア文字による強調表示は、全体の単語に対して機能します。もしいくつかの単語だけで強調表示が必要なら、強調表示記号のアスタリスクを使うことで可能です。
たとえば、このように書きます。
"secret_magic_box"フォルダーを開いてください。 

PHP Markdown Extra では、単語の中にアンダースコアがあるので、強調表示として変換されません。その出力されるHTMLは、このようになります。
<p>"secret_magic_box"フォルダーを開いてください。 </p>

アンダースコアによる強調表示を行うには、単語全体に対して使います。
_キミがボクを愛してる_というのがいいね

<strong>の強調表示も同じです。PHP Markdown Extra では、単語の中でアンダースコアを使うことが強調表示とはなりませんので、強調表示記号であるアスタリスクもそのようにして使わなくてはいけません。
バックスラッシュのエスケープ（Backslash Escapes）

PHP Markdown Extra では、コロン文字（:）と、パイプ文字（|）を文字リストに加えるには、バックスラッシュ（¥)を使います。これを行うことで、定義リスト（dl）や表組み（table）表現になるのを避けることができます。

原稿ありがとうございます｡フォークして修正を加えたのですが､Gistにはプルリクエストの機能がないようです｡お手数ですが差分をご確認いただけますでしょうか？

Revisions · PHP_Markdown_Extra.md