Markdown を HTML にする

貼り付けると、見た目とHTMLの両方を出します。どの流儀で変換したかを必ず画面に書きます。

「Markdown」は、ひとつの決まりではありません

ここがこのページで一番大事なところです。同じ文章でも、変換する道具によって違う HTML が出てきます。道具の出来の良し悪しではなく、そもそも決まりが何種類もあるからです。

はじまりは2004年です。ジョン・グルーバーという人が Markdown を作りました。 配布されている最後の版は1.0.1・2004年12月17日で、いまも同じものが置かれています。 ところがこの Markdown には、書き方をすみずみまで決めた文書がありませんでした。 説明の文章と、変換する道具（Perl で書かれたもの）があるだけです。

書いていないところは、道具を作る人がそれぞれ決めるしかありません。 こうして解釈が枝分かれしていきました。それを整理するために書かれたのがCommonMarkで、いまの版は0.31.2（2024年1月28日）です。 CommonMark 自身がその理由を「あいまいでない仕様が無いため、実装はこの10年でかなり食い違ってしまった」（新しいタブで開きます）と書いています。

その CommonMark に、表・打ち消し線・チェックつきの箇条書きなどを足したのがGFM（GitHub Flavored Markdown）です。仕様書は0.29-gfm（2019年4月6日）。 もとの Markdown（2004年）に表はありません。いま当たり前のように書いている表は、あとから足されたものです。

枝分かれの多さは、インターネットの決まりごとを書く文書にも表れています。RFC 7763（新しいタブで開きます）（2016年3月）は Markdown を送るときの型を決めたものですが、そこには「Markdown はいまや、人には広く通じるが、たがいには必ずしも通じない書き方の一族を指す」と書かれ、どの流儀かを添えて送る決まりになっています。 決まりが1つなら、こんな仕組みは要りませんでした。

だからこの道具は、変換した結果のすぐ上に「どの流儀の、どの版で、改行をどう扱って変換したか」を必ず出します。 流儀を書かない変換結果は、あとで別の場所に貼ったときに形が変わっても、 なぜ変わったのかを追いかけられません。

⭐ 同じ3行が、決まりしだいで違う HTML になります

いちばん食い違うのが改行です。空行を入れずに改行だけで分けた3行を、 決まりだけ変えて2通りに変換してみます。元の文章はまったく同じです。

春はあけぼの
やうやう白くなりゆく
山ぎは

<p>春はあけぼの
やうやう白くなりゆく
山ぎは</p>

<p>春はあけぼの<br />
やうやう白くなりゆく<br />
山ぎは</p>

①が仕様どおりです。CommonMark も GFM も、1回の改行を「やわらかい改行」と呼び、HTML の中では改行の文字のまま残すが、行の区切りにはしないと決めています。仕様には「やわらかい改行を、強い改行として描く選び方を用意してもよい」（新しいタブで開きます）とも書かれていて、②はそちらです。どちらも仕様の中にあるので、どちらが正しいという話ではありません。

もとの Markdown を作ったグルーバー自身が、その理由を書き残しています。「すべての改行を br にする単純な決まりは Markdown ではうまくいかない。 メール風の引用や、段落がいくつもあるリストの項目は、 手で折り返して書いたほうが読みやすいからだ」。 つまり「書いている文章そのものが読みやすいこと」を優先した結果、 改行が1つでは足りない決まりになったわけです。

同じ GitHub でも、ファイルとコメント欄で結果が違います

ここが実際にいちばん引っかかるところです。GitHub 自身の説明に、issue やコメント欄では改行がそのまま改行になるけれど、.md ファイルでは1行につながってしまうので、 空白2つか \ か <br> を書き足す必要がある、 と書かれています。

GFM の仕様書（新しいタブで開きます）のほうには、この「1回の改行で改行する」という決まりはありません。つまりコメント欄の動きは仕様ではなく、GitHub の画面の設定です。 コメント欄で書いた文章をそのまま README に貼ると形が崩れるのは、たいていこれが理由です。

日本語だと、つないだところに空白が入りません

①をよく見てください。2行が空白なしでつながっています。これは変換のしかたではなく、ブラウザが描くときの決まりです。

HTML の中では改行はそのまま残っていて、ブラウザがそれを空白に変えるか、消すかを決めます。 英語のように語と語を空白で区切る言語では、消してしまうと「isbroken」のように単語がくっついてしまうので空白に変えます。 日本語や中国語には語の区切りの空白が無いので、消すのが正しいわけです。

CSS の仕様（CSS Text Module Level 3（新しいタブで開きます））は、この判断を「前後の文字を見て決める。やり方はブラウザに任せる」と書いています。さらに「昔の HTML と CSS は改行を必ず空白に変えていて、そのせいで中国語などが行を折って書けなかった」という注記まで付いています。 改行を消してよくなったのは、比較的あたらしい話です。

貼った文章は、どこにも送りません

変換はすべてこの画面の中（お使いの機器の中）で行っています。 文章が機器から出ることはないので、社外に出せない資料でもそのまま貼れます。変換の道具を外から読み込むこともしていません。よく使われる変換の道具を配布元から読み込む作りにすると、その配布元に「誰かがこのページを開いた」ことが伝わります。 だから対応する書き方を絞って、自分で書いています。

同じ理由で、プレビューでは画像を読み込みません。 文章の中に  があったとき、そのまま画像として出すと、 ブラウザがその置き場へ絵を取りに行きます。置き場の持ち主に「この文章を見た人がいる」と伝わってしまうので、 枠と説明の文字だけを出しています。書き出す HTML のほうには、ちゃんと画像として書きます。

他人の書いた文章には、危ないものが入っていることがあります

Markdown を貼る場面は、他人が書いたものを見るときが案外多いものです。 そこには<script>や、押すと命令が動くリンクが混ざっていることがあります。

この道具は、変換した結果をいったん「木」の形にしてから画面を組み立てます。 貼られた文字は必ず「文字の場所」にしか入らないので、 タグとして働く道がそもそもありません。 <script> はそのままの文字として出て、「タグとして働かせず、文字にしました」と画面に出します。 黙って消しません。消してしまうと、もとの文章に何が書いてあったのかが分からなくなるからです。

リンクは別です。javascript: vbscript: data: file: で始まるものは、 押すと文章ではなく命令が動くのでリンクをやめて文字だけ残します。 この4つは思いつきで選んだものではなく、GitHub が使っている変換器（cmark-gfm）（新しいタブで開きます）が、既定で外すものとして挙げている4つと同じです。

【へえ】GFM の仕様には安全のための決まりもありますが、ごくわずかです。「使わせない生の HTML」という節にあるのはtitle・textarea・style・xmp・iframe・noembed・noframes・script・plaintext の9つだけで、しかも「そのほかの HTML タグはそのまま通す」とはっきり書かれています。 つまりGFM の決まりを守るだけでは安全になりません。 cmark-gfm の説明にも「生の HTML を通す設定にするなら、 別に専用の掃除の道具を使うことをすすめる」と書かれています。 この道具が生の HTML を1つも通さないのは、そのためです。

対応している書き方の一覧

外から道具を取ってこない代わりに、対応する書き方を絞っています。 ここに無いものを貼ったときは、そのままの文字として出したうえで「対応していません」と画面に出します。 黙って素通しすると、変換されたつもりで壊れた HTML を持ち帰ることになるからです。

強調（* と _）の判定は、仕様のこまかい決まりをそのまま写したものではありません。 ただし「_ は語の途中では強調にしない」だけは入れてあります。 これが無いと snake_case_name の真ん中が斜体になってしまい、 プログラムの名前を書いた文章が読めなくなるためです。