Markdown in HTML
《 初回公開：2022/03/26 , 最終更新：未 》
原文は
旧バージョンの記事は
【 目次 】
要約
HTMLタグ内のMarkdownを解析する拡張機能。
構文
デフォルトでは、Markdownは素のHTMLブロックレベル要素内のコンテンツをすべて無視します。
md-in-html拡張機能を有効にすると、開始タグにmarkdown属性を含めることで、素のHTMLブロックレベル要素のコンテンツをマークダウンとして解析できます。
markdown属性は出力から削除されますが、他のすべての属性は保持されます。
markdown属性には、「1」、「block」、または「span」の3つの値のいずれかを割り当てることができます。
Note
このドキュメントで使用されている“block-level”および“span-level”という表現は、HTML仕様に従った要素の指定を指します。
一方、markdown属性に割り当てられた"span"と"block"の値は、Markdownパーサーの動作を参照します。
markdown="1"
markdown属性が「1」に設定されている場合、パーサーはその特定のタグのデフォルトの動作を使用します。
次のタグはデフォルトでblock動作をします：article、aside、blockquote、body、colgroup、details、div、dl、fieldset、figcaption、figure、footer、form、group、header、hgroup、hr、iframe、main、map、 menu、nav、noscript、object、ol、output、progress、section、table、tbody、tfoot、thead、tr、ul、およびvideo。
たとえば、次のようになります。
<div markdown="1">
This is a *Markdown* Paragraph.
</div>
…は次のようにレンダリングされます。
<div>
<p>This is a <em>Markdown</em> Paragraph.</p>
</div>
次のタグには、デフォルトでspan動作となります：address、dd、dt、h [1-6]、legend、li、p、td、およびth。
たとえば、次のようになります。
<p markdown="1">
This is not a *Markdown* Paragraph.
</p>
…は次のようにレンダリングされます。
<p>
This is not a <em>Markdown</em> Paragraph.
</p>
markdown="block"
markdown属性が"block"に設定されている場合、パーサーは、要素がblockタグまたはspanタグの1つである限り、要素のコンテンツに対してblock動作を強制します。
block要素のコンテンツは、block-levelのコンテンツに解析されます。
つまり、テキストは段落、ヘッダー、リスト、ブロッククォートなどとしてレンダリングされます。
これらの要素内のインライン構文もすべて処理されます。
たとえば、次のようになります。
<section markdown="block">
# A header.
A *Markdown* paragraph.
* A list item.
* A second list item.
</section>
…は次のようにレンダリングされます。
<section>
<h1>A header.</h1>
<p>A <em>Markdown</em> paragraph.</p>
<ul>
<li>A list item.</li>
<li>A second list item.</li>
</ul>
</section>
警告
デフォルトではないため、無効なHTMLが生成される可能性がある時に、要素をblock要素として解析するように強制します。
たとえば、<p>要素を別の<p>要素内に強制的にネストさせることができます。
ほとんどの場合、markdown = "1"のデフォルトの動作を使用することをお勧めします。
明示的にmarkdown = "block"を設定することは、HTML仕様と、ブラウザーがHTMLを解析およびレンダリングする方法を理解している上級ユーザーのために予約されています。
markdown="span"
markdown属性が「span」に設定されている場合、パーサーは、要素がblockタグまたはspanタグの1つである限り、要素のコンテンツにspan動作を強制します。
span要素のコンテンツは、block-levelのコンテンツに解析されません。
つまり、コンテンツは段落やヘッダーなどとしてレンダリングされません。
links, strong, emphasisなどのインライン構文のみがレンダリングされます。
たとえば、次のようになります。
<div markdown="span">
# *Not* a header
</div>
…は次のようにレンダリングされます。
<div>
# <em>Not</em> a header
</div>
無視される要素
次のタグは、markdown属性に関係なく、常に無視されます：canvas、math、option、pre、script、style、およびtextarea。
他のすべての素のHTMLタグはspan-levelのタグとして扱われ、この拡張機能の影響を受けません。
ネスティング
複数レベルの素のHTML要素をネストする場合は、block-levelの要素ごとにmarkdown属性を定義する必要があります。
markdown属性を持たないblock-levelの要素の場合、markdown属性を持つ子要素を含め、その要素内のすべてが無視されます。
たとえば、次のようになります。
<article id="my-article" markdown="1">
# Article Title
A Markdown paragraph.
<section id="section-1" markdown="1">
## Section 1 Title
<p>Custom raw **HTML** which gets ignored.</p>
</section>
<section id="section-2" markdown="1">
## Section 2 Title
<p markdown="1">**Markdown** content.</p>
</section>
</article>
…は次のようにレンダリングされます。
<article id="my-article">
<h1>Article Title</h1>
<p>A Markdown paragraph.</p>
<section id="section-1">
<h2>Section 1 Title</h2>
<p>Custom raw **HTML** which gets ignored.</p>
</section>
<section id="section-2">
<h2>Section 2 Title</h2>
<p><strong>Markdown</strong> content.</p>
</section>
</article>
要素のmarkdown属性の値がその親よりも許容度が高い場合、親のより厳密な動作が適用されます。
たとえば、span要素内にネストされたblock要素は、span動作を使用して解析されます。
ただし、要素のmarkdown属性の値がその親と同じであるか、より制限的である場合、子要素の動作は守られます。
たとえば、block要素には子としてblock要素またはspan要素のいずれかが含まれる場合があり、各要素は指定された動作を使用して解析されます。
タグの正規化
デフォルトの動作では、Markdownは素のHTMLを変更しませんが、この拡張機能は素のHTML要素のコンテンツを解析しているため、block-levelの要素のタグを正規化します。
たとえば、次の素のHTML：
<div markdown="1">
<p markdown="1">A Markdown paragraph with *no* closing tag.
<p>A raw paragraph with *no* closing tag.
</div>
…は次のようにレンダリングされます。
<div>
<p>A Markdown paragraph with <em>no</em> closing tag.
</p>
<p>A raw paragraph with *no* closing tag.
</p>
</div>
パーサーは、閉じられていない<p>タグが、別の<p>タグが開始したとき、または親要素が終了したときに終了することを正しく認識していることに注意してください。
どちらの場合も、markdown属性が要素に割り当てられているかどうかに関係なく、要素の最後に終了</ p>が追加されました。
正規化を回避するために、要素は、markdown属性が定義されているblock-levelの要素の子孫であってはなりません。
警告
正規化の動作はここでのみ文書化されているため、ドキュメントの作成者は、慎重に作成された素のHTMLがMarkdownによって変更されても驚かないようになっています。
この拡張機能は、有効なHTMLを正規化して生成するために使用しないでください。
最良の結果を得るには、Markdownドキュメントに常に有効な素のHTML（開始タグと終了タグの両方を含む）を含めてください。
使い方
Pythonインタープリターから：
>>> import markdown
>>> html = markdown.markdown(text, extensions=['md_in_html'])
愚鈍人の独り言
原文を読んでいて、markdown属性のspanとblockの違いがどうもよくわからない。
結論としては。
Markdownテキスト内に(素の)HTMLタグを記述する場合、そのHTMLタグ内で囲まれたMarkdownテキストはHTMLテキストとして展開されない。
htmlに展開させるためには(素の)HTMLタグにmarkdown属性を指定しなければならない。
この時、markdown属性の値として通常は1を指定する。