PHP Markdown Extra 仕様の全訳(意訳)


拙作の「MarkDown#Editor」ですが、次版では、Markdown Extraの実装を検討しています。

でも、そのためには本家Extraの仕様をよく理解していないとつくれません。

Michel Fortin – PHP Markdown Extra

ただ、本家ホームページは全部英語。がんばれば読めないわけではありませんが、楽をしたいなあ、誰か訳していないかなあ、とウェブをうろちょろしてみたのですが、誰もしてくれてなくて・・・

うーん(笑)。

じゃあ、どうせしっかり調べるなら、僕が全訳してしまおうか、という感じでやってみました。

もし英語の得意の方で、かつMarkdown Extraに精通されていて、微妙に本家とニュアンスがちがうだとか、真逆のこと書いてあるということがあれば、適宜ツッコミを入れてください。修正を加えて行きたいと思います。

また、以下の場所に参照しやすいよう、ファイルとしても上げています。よろしければこちらも併せてご参照ください。
https://gist.github.com/hibara/5661760

そして以下が、そのページの全訳。


PHP Markdown Extraは、通常のオリジナルMarkdown記法では利用できない、いくつかの特徴を加えて移植されたPHP Markdown記法の特別なバージョンです。PHP Markdown Extra は、PHP Markdown home pageからダウンロードできます。

このドキュメントでは、PHP Markdown Extraで入れたMarkdown記法に追加した機能や変更を説明しています。このドキュメントを読む前に、オリジナルのMarkdown記法のドキュメントの方に目を通しておくべきでしょう。

 

目次

 

インラインHTML(Inline HTML)

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

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

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

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

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

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

 

HTMLブロック内のMarkdown記法(Markdown Inside HTML Blocks)

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

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

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

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

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

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

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

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

 

特殊な属性(Special Attributes)

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

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

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

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

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

 

コードブロック区切り(Fenced Code Blocks)

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

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

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

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

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

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

HTMLに出力したとき、コードブロック属性は、そのコードの要素に割り当てることができます。もし、代わりに<pre>要素として表示させたいのなら、(PHP Markdown Extraの)ファイル先頭にある設定項目の、MARKDOWN_CODE_ATTR_ON_PREを true にします。

 

表組み(Tables)

PHP Markdown Extra は独自に、シンプルな表組みが実装されています。まさに「シンプル」な表組みです。次のように書きます。

最初の行に、カラムヘッダーを書きます。二行目は、ヘッダーと表の内容とを分ける境界線を必ず書きます。そのあとは、順に必要な表組みの列と行を書いていきます。カラムは、パイプ文字(|)で分かれている必要があります。一度、HTMLに変換してみましょう。結果は次の通りになります。

望むなら、表組みの行の最初と最後に、パイプ文字を書くこともできます。好きな方の書式で書くことができ、出力結果は上と同じになります。

メモ:表組みは、PHP Markdown Extra が正確にパースするために、少なくとも各行につきパイプ文字が一つ必要です。つまり、1カラムのテーブルを作成するときは、行頭か、行末に一つ、あるいはその両方、さらに各項目行にも必要ということを意味します。

各カラムの行揃えを指定したいときは、区切り文字にコロン(:)を追加します。コロン文字が、区切り文字の左にあれば、カラムは左寄せとなります。同様に、コロン文字が右にあれば、右寄せになります。両サイドに挿入した場合は、センタリングされます。

出力されたHTMLの行揃え(align属性)は、そのセルが関係するカラムによって決まります。

また、インライン書式であれば、各セルの中に一般的なMarkdown記法を使うことができます。

 

定義リスト(Definition Lists)

PHP Markdown Extra では、定義リスト(<dl>)を実装しています。定義リストは、辞典のように、単語とその単語の定義(説明)によって構成されます。

PHP Markdown Extra による、シンプルな定義リストは、一行の単語と、それに続くコロン文字(:)と、定義内容によって構成されます。

これらの定義リストは、HTMLにすると、以下のように出力されます。

定義を表すコロン文字は、一般に左端から始めますが、スペースが3つになるまでインデントできます。定義を表す文字の後は、1つ、もしくは複数のスペースやタブを空けてから続けて書いていきます。

定義リストは、一つの定義とひもづく、一つ以上の定義内容を持つことができます。

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

空行を先に書いてから定義内容を書くと、PHP Markdown Extra は定義内容を

タグで囲み、HTML出力します。たとえば、このようにやります。

これらは、次のように変換されます。

また、よくある一般的なリスト項目のように、定義内容には複数のパラグラフを含むことができ、他のブロック要素の、引用(blockquote)や、コードブロック、リスト、他の定義リストでさえも、含めることができます。

 

脚注(Footnotes)

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

脚注定義は、ドキュメント内であればどこにあってもかまいませんが、脚注は常にそのテキスト内で、リンクされた順番でリストされている必要があります。注意点として、同じ脚注に対して、二つのリンクを張ることはできません。もしそれをした場合、二番目の脚注参照は、そのままテキストとして残ります。

各脚注は、異なる名前にしなければいけません。その名前は、脚注と定義される脚注リンクとして使われますが、脚注のナンバリングとの直接的な影響はありません。それらの名前は、HTMLのid属性として有効なら、どのような文字でも使えます。

脚注は、ブロック要素を含むことができます。すなわち複数のパラグラフ、リスト、引用、その他の脚注を置けるということを意味します。リスト項目とまったく同じように動作し、脚注内で4つのスペースのインデント後にパラグラフを続けて書いていきます。

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

 

出力(Output)

おそらく一つの脚注だけでは、すべての人が満足できないでしょう。将来的なバージョンで、異なるマークアップから、脚注の生成を許可するプログラミングインターフェースを提供するかもしれません。しかし、現在のところ、出力は、ほとんとちがいのないオリジナルのMarkdownの仕様に従います。ここでは、最初に挙げたサンプルから、デフォルトの出力結果を示します。

少し隠れてしまいますが、ブラウザーによっては、このように見えるでしょう。

それは脚注1のついたいくつかのテキストです。


  1. そして、それがこの脚注になります。

リンク上の、rel と、rev 属性は、互いにリンクしている関係を表現しています。リファレンスリンク(すなわち、rel=”footnote” )は、脚注に誘導され、戻るリンク(すなわち、rev=”footnote” )は脚注から戻って来ます。それらは、CSSルールで書けば、このように使われるでしょう。

脚注リンクと戻るリンクの、class と、title 属性値はカスタマイズすることができます。(PHP Markdown Extraの)ファイル先頭には、動作に影響する、四つの設定可能項目があります。これらの属性値内でいくつかある、%% の部分は、カレントの脚注番号に置き換わります。たとえば、このように使うことができるでしょう。

 

省略表記(Abbreviations)

PHP Markdown Extra は、(HTMLタグの <abbr> にあるような)省略表記をサポートしています。とても簡単にできます。次のように省略表記の定義を作ってください。

それから、ドキュメントの他の場所で、以下のテキストのように書きます。

そして、テキスト内のそれらの定義された単語は、すべて以下のようになります。

省略表記は、大文字小文字を区別し、そのように定義し、合致した複数の単語に展開されます。もし省略表記が定義されていないときは、<abbr> タグがテキストに追加されます。ただし、title 属性は除外されます。

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

 

強調表示(Emphasis)

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

たとえば、このように書きます。

PHP Markdown Extra では、単語の中にアンダースコアがあるので、強調表示として変換されません。その出力されるHTMLは、このようになります。

アンダースコアによる強調表示を行うには、単語全体に対して使います。

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

 

バックスラッシュのエスケープ(Backslash Escapes)

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

 


 

以上が全訳です。

フィードバックやツッコミ大歓迎です。

追記:2013-03-23
メールで早速ツッコミをいただきましたので、「インラインHTML」の一部を修正しました。
ご指摘ありがとうございました。

追記:2013-05-28
メールでのご要望があり、編集または参照しやすいようにファイルとして以下の場所に上げました。
https://gist.github.com/hibara/5661760

お気軽にコメントをどうぞ〜

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です

コメントフィード

s