Python-Markdown Extra
初回公開：2018/01/01
最終更新：2018/01/13
「Python-Markdown Extra」のドキュメントをつたない翻訳，勝手な解釈。
【 目次 】
要約
さまざまなPython-Markdown extensionsのコンパイルで、（ほとんど）PHP Markdown Extraを模倣しています。
サポートされる拡張機能は次のとおりです。
構文のドキュメントについては、個々の拡張機能を参照してください。
Extraとそのすべてのサポートされている拡張機能は標準のMarkdownライブラリに含まれています。
使い方
Pythonインタプリタから：
>>> import markdown >>> html = markdown.markdown(text, ['markdown.extensions.extra'])
Extraには含まれていないPython-Markdownで配布される追加の拡張があるかもしれません。
これらのextensionsの機能は、PHP Markdown Extraの一部ではないため、Python-Markdown Extraの一部ではありません。
Extraに追加の拡張機能を追加したい場合は、Extraの独自のクローンを別の名前で作成することをおすすめします（Extension APIを参照）。
HTMLブロック内のmarkdown
その他の追加機能とは異なり、この機能はmarkdownに組み込まれており、markdown.extensions.extraが有効になっているとオンになります。
HTMLブロック要素の内容を開始タグにmarkdown属性を追加するだけで、Markdown形式にすることができます。
markdown属性は出力から取り除かれますが、他の属性はすべて保持されます。
markdown属性の値に1（推奨）またはspanかblock以外の任意の値が設定されている場合、デフォルトの動作が実行されます：
p、h[1-6]、li、dd、dt、 td、th、legend、そしてaddress要素はブロック解析をスキップしますが、他の要素はスキップしません。
デフォルトの値がspanの値によって上書きされた場合、ブロックの解析はタグに関係なくスキップされます。
簡単な例：
This is *true* markdown text. <div markdown="1"> This is *true* markdown text. </div>
結果：
<p>This is <em>true</em> markdown text.</p> <div> <p>This is <em>true</em> markdown text.</p> </div>
訳者による蛇足
訳してみたけど意味がよくわからなかったので、markdown属性の値をいろいろ変えて試してみると。
ブロック要素内のテキストはmarkdownとして解釈されずそのまま出力される
htmlタグ内のテキストはタグがインライン要素の場合、markdownとして解釈されるが、ブロックレベル要素の場合はmarkdownとして解釈されない。
そもそも、ブロックレベル要素とかインライン要素というのは
インライン要素spanタグを例にとると
spanタグの例
<span>This is *true* markdown text.(markdown属性未指定)</span>
html出力
<span>This is <em>true</em> markdown text.(markdown属性未指定)</span>
インライン要素spanタグ内のテキストはmarkdownテキストとして解析されている。
ところが、ブロック要素であるdivタグやpタグ，sectionタグの場合は、
divタグの例
<div>This is *true* markdown text.(markdown属性未指定)</div> <p>This is *true* markdown text.(markdown属性未指定)</p> <section>This is *true* markdown text.(markdown属性未指定)</section> <h1>This is *true* markdown text.(markdown属性未指定)</h1>
html出力
<div>This is *true* markdown text.(markdown属性未指定)</div> <p>This is *true* markdown text.(markdown属性未指定)</p> <section>This is *true* markdown text.(markdown属性未指定)</section> <h1>This is *true* markdown text.(markdown属性未指定)</h1> <section>This is *true* markdown text.(markdown属性未指定)</section>
ブロック要素内のテキストはmarkdownテキストとして解釈されずそのまま出力されている。
markdown属性に1を指定する
ブロック要素内のテキストをmarkdownテキストとして解釈させるにはブロック要素にmarkdown属性を指定する。
markdownテキスト
<div markdown="1">This is *true* markdown text.(markdown="1")</div> <p markdown="1">This is *true* markdown text.(markdown="1")</p> <section markdown="1">This is *true* markdown text.(markdown="1")</section> <h1 markdown="1">This is *true* markdown text.(markdown="1")</h1>
html出力
<div> <p>This is <em>true</em> markdown text.(markdown="1")</p> </div> <p>This is <em>true</em> markdown text.(markdown="1")</p> <section> <p>This is <em>true</em> markdown text.(markdown="1")</p> </section> <h1>This is <em>true</em> markdown text.(markdown="1")</h1>
ブロック要素にmarkdown属性を指定した場合、ブロック要素のmarkdown属性は削除され、そしてブロック要素内のテキストはmarkdownテキストとして処理されているのが確認できる。
注目すべき点は、markdown属性の値に1を指定した場合、divタグやsectionタグではその直下に自動的にpタグが挿入されている。
ところが、pタグやh1タグの場合はpタグは挿入されない。
これは、通常pタグの中にpタグを入れたり見出しの機能をもったh1タグの中にpタグを使う事は無いので好ましい動作である。
markdown属性にspanを指定
でも、ブロック要素の直下に自動的にpタグが挿入したく無い場合、markdown属性にspanを指定する。
markdownテキスト
<div markdown="span">This is *true* markdown text.(markdown="span")</div> <p markdown="span">This is *true* markdown text.(markdown="span")</p> <section markdown="span">This is *true* markdown text.(markdown="span")</section> <h1 markdown="span">This is *true* markdown text.(markdown="span")</h1>
html出力
<div>This is <em>true</em> markdown text.(markdown="span")</div> <p>This is <em>true</em> markdown text.(markdown="span")</p> <section>This is <em>true</em> markdown text.(markdown="span")</section> <h1>This is <em>true</em> markdown text.(markdown="span")</h1>
markdown属性にblockを指定
逆にpタグを強制的に挿入したい場合はmarkdown属性にblockを指定する。
markdownテキスト
<div markdown="block">This is *true* markdown text.(markdown="block")</div> <p markdown="block">This is *true* markdown text.(markdown="block")</p> <section markdown="block">This is *true* markdown text.(markdown="block")</section> <h1 markdown="block">This is *true* markdown text.(markdown="block")</h1>
html出力
<div> <p>This is <em>true</em> markdown text.(markdown="block")</p> </div> <p> <p>This is <em>true</em> markdown text.(markdown="block")</p> </p> <section> <p>This is <em>true</em> markdown text.(markdown="block")</p> </section> <h1> <p>This is <em>true</em> markdown text.(markdown="block")</p> </h1>
markdown属性に任意の値を指定
ブロック要素のmarkdown属性に1でもblockでもspanでも無い任意の値を指定したとすると、markdown属性を1に指定した場合と同じ動作となる。
そして、任意の値では混乱するのでmarkdown属性には1を指定するのが推奨されているという事になる
markdownテキスト
<div markdown="any">This is *true* markdown text.(markdown="any")</div> <p markdown="any">This is *true* markdown text.(markdown="any")</p> <section markdown="any">This is *true* markdown text.(markdown="any")</section> <h1 markdown="any">This is *true* markdown text.(markdown="any")</h1>
html出力
<div> <p>This is <em>true</em> markdown text.(markdown="any")</p> </div> <p>This is <em>true</em> markdown text.(markdown="any")</p> <section> <p>This is <em>true</em> markdown text.(markdown="any")</p> </section> <h1>This is <em>true</em> markdown text.(markdown="any")</h1>
多分、そういう事だと思う。
インライン要素markdown属性を指定
ちなみにインライン要素spanにmarkdown属性を指定した場合には、markdown属性がそのまま残ったままで出力される。
markdownテキスト
<span markdown="1">This is *true* markdown text.(markdown="1")</span>
html出力
<span markdown="1">This is <em>true</em> markdown text.(markdown="1")</span>
コードによる確認
以下は上記の事を確認するためのコードとその実行結果である。
import markdown makedown_text=u"""<span>This is *true* markdown text.(markdown属性未指定)</span> <span markdown="1">This is *true* markdown text.(markdown="1")</span> <span markdown="any">This is *true* markdown text.(markdown="any")</span> <span markdown="span">This is *true* markdown text.(markdown="span")</span> <span markdown="block">This is *true* markdown text.(markdown="block")</span> <div>This is *true* markdown text.(markdown属性未指定)</div> <div markdown="1">This is *true* markdown text.(markdown="1")</div> <div markdown="any">This is *true* markdown text.(markdown="any")</div> <div markdown="span">This is *true* markdown text.(markdown="span")</div> <div markdown="block">This is *true* markdown text.(markdown="block")</div> <p>This is *true* markdown text.(markdown属性未指定)</p> <p markdown="1">This is *true* markdown text.(markdown="1")</p> <p markdown="any">This is *true* markdown text.(markdown="any")</p> <p markdown="span">This is *true* markdown text.(markdown="span")</p> <p markdown="block">This is *true* markdown text.(markdown="block")</p> <section>This is *true* markdown text.(markdown属性未指定)</section> <section markdown="1">This is *true* markdown text.(markdown="1")</section> <section markdown="any">This is *true* markdown text.(markdown="any")</section> <section markdown="span">This is *true* markdown text.(markdown="span")</section> <section markdown="block">This is *true* markdown text.(markdown="block")</section> <h1>This is *true* markdown text.(markdown属性未指定)</h1> <h1 markdown="1">This is *true* markdown text.(markdown="1")</h1> <h1 markdown="any">This is *true* markdown text.(markdown="any")</h1> <h1 markdown="span">This is *true* markdown text.(markdown="span")</h1> <h1 markdown="block">This is *true* markdown text.(markdown="block")</h1> """ print markdown.Markdown(['markdown.extensions.extra']).convert(makedown_text)
実行結果
<p><span>This is <em>true</em> markdown text.(markdown属性未指定)</span> <span markdown="1">This is <em>true</em> markdown text.(markdown="1")</span> <span markdown="any">This is <em>true</em> markdown text.(markdown="any")</span> <span markdown="span">This is <em>true</em> markdown text.(markdown="span")</span> <span markdown="block">This is <em>true</em> markdown text.(markdown="block")</span></p> <div>This is *true* markdown text.(markdown属性未指定)</div> <div> <p>This is <em>true</em> markdown text.(markdown="1")</p> </div> <div> <p>This is <em>true</em> markdown text.(markdown="any")</p> </div> <div>This is <em>true</em> markdown text.(markdown="span")</div> <div> <p>This is <em>true</em> markdown text.(markdown="block")</p> </div> <p>This is *true* markdown text.(markdown属性未指定)</p> <p>This is <em>true</em> markdown text.(markdown="1")</p> <p>This is <em>true</em> markdown text.(markdown="any")</p> <p>This is <em>true</em> markdown text.(markdown="span")</p> <p> <p>This is <em>true</em> markdown text.(markdown="block")</p> </p> <section>This is *true* markdown text.(markdown属性未指定)</section> <section> <p>This is <em>true</em> markdown text.(markdown="1")</p> </section> <section> <p>This is <em>true</em> markdown text.(markdown="any")</p> </section> <section>This is <em>true</em> markdown text.(markdown="span")</section> <section> <p>This is <em>true</em> markdown text.(markdown="block")</p> </section> <h1>This is *true* markdown text.(markdown属性未指定)</h1> <h1>This is <em>true</em> markdown text.(markdown="1")</h1> <h1>This is <em>true</em> markdown text.(markdown="any")</h1> <h1>This is <em>true</em> markdown text.(markdown="span")</h1> <h1> <p>This is <em>true</em> markdown text.(markdown="block")</p> </h1>
HTMLブロック内のネストされたマmarkdown
ネストされた要素は、より敏感であり、慎重に使用する必要があります。予期しない結果を避けるには：
ブロックモード要素内の要素のみをネストします。 内部要素の終了タグに続けて空白行を付けます。 ネストのレベルは1つのみです。
複雑な例：
<div markdown="1" name="Example"> The text of the `Example` element. <div markdown="1" name="DefaultBlockMode"> This text gets wrapped in `p` tags. </div> The tail of the `DefaultBlockMode` subelement. <p markdown="1" name="DefaultSpanMode"> This text *is not* wrapped in additional `p` tags. </p> The tail of the `DefaultSpanMode` subelement. <div markdown="span" name="SpanModeOverride"> This `div` block is not wrapped in paragraph tags. Note: Subelements are not required to have tail text. </div> <p markdown="block" name="BlockModeOverride"> This `p` block *is* foolishly wrapped in further paragraph tags. </p> The tail of the `BlockModeOverride` subelement. <div name="RawHtml"> Raw HTML blocks may also be nested. </div> </div> This text is after the markdown in HTML.
結果：
<div name="Example"> <p>The text of the <code>Example</code> element.</p> <div name="DefaultBlockMode"> <p>This text gets wrapped in <code>p</code> tags.</p> </div> <p>The tail of the <code>DefaultBlockMode</code> subelement.</p> <p name="DefaultSpanMode"> This text <em>is not</em> wrapped in additional <code>p</code> tags.</p> <p>The tail of the <code>DefaultSpanMode</code> subelement.</p> <div name="SpanModeOverride"> This <code>div</code> block is not wrapped in paragraph tags. Note: Subelements are not required to have tail text.</div> <p name="BlockModeOverride"> <p>This <code>p</code> block <em>is</em> foolishly wrapped in further paragraph tags.</p> </p> <p>The tail of the <code>BlockModeOverride</code> subelement.</p> <div name="RawHtml"> Raw HTML blocks may also be nested. </div> </div> <p>This text is after the markdown in HTML.</p>
PHP Markdown ExtraのMarkdown Inside HTML Blocksの訳
おまけとしてPHP Markdown Extraの公式ドキュメントの関連する部分の訳を以下に示す。
インラインHTML
Markdownを使用すると、テキストの途中でHTMLを挿入することができます。
これは、Markdown構文では提供されていないが、HTMLで簡単な機能が必要な場合には非常に便利です。
しかしMarkdownは要素をブロックすることに重大な制限があります。
Markdown構文のドキュメントから：
ブロックレベルのHTML要素、例えば<div>、<table>、<pre>、<p>、等は空白行によって周囲のコンテンツから分離されなければならない、そして、ブロックの開始タグと終了タグは、タブ又はスペースでインデントされてはなりません。
Markdown Extraでこれらの制限が解除され、制限の少ない2つの制限に置き換えられました。
ブロック要素の開始タグは、3つ以上のスペースでインデントしてはいけません。
インデントされたタグは、標準のMarkdownルールに従ってコードブロックとして扱われます。
ブロック要素がリストの中にあるとき、そのすべての内容は、リスト項目がインデントされるのと同じ量のスペースでインデントされるべきです。（最初の開始タグがインデントされすぎてコードブロックにならない限り、より多くの字下げは問題ありません。最初のルールを参照してください）。
HTMLブロック内のmarkdown
以前、Markdownでは<div>要素内にMarkdown形式のコンテンツをラップできませんでした。
これは<div>ブロック要素であり、単純なMarkdownはそのような内容をフォーマットしないからです。
Markdown Extraでは、マークダウン形式のテキストを任意のブロックレベルのタグの中に入れることができます。
これを行うにはタグに値が1のmarkdown属性を追加します。
<div markdown="1"> This is *true* markdown text. </div>
属性markdown="1"が削除され、<div>の内容がmarkdownテキストとしてHTMLに変換されます。
最終結果は次のようになります。
<div> <p>This is <em>true</em> markdown text.</p> </div>
Markdown Extraは、markdown属性を配置したブロック要素に応じて適切な書式設定を適用するのに十分スマートです。
たとえば、markdown属性を<p>タグに適用すると、内部にスパンレベルの要素しか生成されません。
リスト、ブロッククォート、コードブロックは許可されません。
しかし、これはあいまいな場合があります。
たとえば、次のようになります。
<table> <tr> <td markdown="1">This is *true* markdown text.</td> </tr> </table>
表のセルには、span要素とblock要素の両方を入れることができます。このような場合、Markdown Extraはスパンレベルのルールのみを適用します。
ブロック構造を有効にしたい場合は、単にmarkdown="block"を代わりに記述してください。