Markdown と HTML ドキュメント、README、API でそれぞれを使用するタイミング

Markdown が実際に何であるか

Markdown は軽量のマーキング言語です — プレーンテキストをシンプルな規則（太字には星印、見出しにはハッシュ、コードにはバックティック）で書きます。そのマーキングは HTML に変換されます。一つの公式な Markdown 標準は存在しません。使用するパーサーによって得られる結果は異なります。

最も一般的な変種：

• CommonMark — 严格的かつ明確に規定された標準。最も「ベーシックな Markdown」と言えるものです。
• GitHub フラワード マーキング（GFM） — CommonMark にテーブル、タスクリスト、ストライクアウト、自動リンク付きURLを追加。GitHub および GitLab が表示するものです。
• kramdown、Pandoc、MultiMarkdown — 補足機能として、フィートノート、定義リスト、カスタム属性など、CommonMarkには存在しない機能を提供しています。

README を作成し、GitHub がそれをレンダリングするのを期待している場合は、GFM がその基準です。静的サイトジェネレーターを使用している場合は、どのパーサーを使用しているか確認してください — たとえば、ネストされたリストやraw HTMLの処理において、そのパーサー間で差異が生じます。

Markdown が勝つ場面

README および開発者向けドキュメント Markdown は開発者ドキュメントのデフォルトです。GitHub、GitLab、Bitbucket、npm、PyPI などはすべて、Markdown をネイティブでレンダリングしています。README を HTML で書くことは技術的には可能ですが、編集者がそれを編集する必要があるため、実用的には不適切です。

Wiki および変更ログ 人間が編集できる、バージョン管理されたテキストファイルで、差分が読みやすいことが求められます。HTML は冗長で、意味のない差分を生成します。Markdown はシンプルに残ります。

ドキュメントサイト MkDocs、Docusaurus、Hugo、Jekyll などのツールは、Markdown ファイルを受け取り、ビルド時に HTML に変換します。作成者は Markdown を書きます。サイト側がプレゼンテーションを担当します。

非開発者によるコンテンツ作成のとき Markdown は HTML より学習しやすく、書くことのハードルが低いです。コンテンツパイプラインに非開発者（フロントエンドエンジニアではない）が含まれる場合、Markdown は大きな摩擦を減らします。

HTML が勝つ場面

メール メールクライアント — 特にOutlookは — CSSのサポートが有名に不一致です。HTML ではレイアウト、フォントサイズ、スペース、インラインスタイルに対して明確な制御が可能です。Markdown から HTML に変換されたメールは、特定のクライアントでタグを削除されたり、レンダリングがサポートされていない場合に破綻します。

細かいレイアウトとスタイル 必要な特定のカラム幅、フロートレイアウト、またはカスタムCSSクラスがある場合、Markdown は邪魔になります。あなたはraw HTMLを混ぜたり、パーサーの出力と戦わなければなりません。

複雑なテーブル GFMのテーブルはシンプルなグリッドに適しています。マージセル、複数行のセル、または列のスパンが必要な場合、Markdownの構文は機能しなくなります。HTML が適しています。 <table> 適しています。

CMSで管理されるコンテンツ ほとんどのCMSプラットフォームは、投稿コンテンツをHTMLとして保存したり、ブロックベースのエディタを使用して構造化されたHTMLを生成します。Markdownをそのパイプラインに強制することは、変換層を追加するだけであり、CMSがそのように設計されていない限り、明確なメリットはありません。

比較の概要

使用事例	マークダウン	html	勝者
GitHub README	ネイティブサポート	冗長で使いにくい	マークダウン
メールテンプレート	一貫性がない	フルコントロール	html
ドキュメントサイト	ネイティブでSSGを使用	ビルドステップが必要	マークダウン
複雑なテーブル	限定	フルコントロール	html
APIレスポンスボディ	一般的なパターン	動作するが冗長	マークダウン
CMSコンテンツ	変換が必要	ネイティブ	html
変更ログ	きれいな差分	過剰	マークダウン

GFM：CommonMarkより追加される機能

GitHub フラワード マーキングは、開発者が頻繁に使う機能をCommonMarkに追加します。以下は、CommonMarkに存在しない2つの例です：GFMテーブルとタスクリスト。これらは、純粋なCommonMarkパーサーではレンダリングされません。もしドキュメントのパイプラインが拡張機能なしのCommonMarkを使用している場合、これらのブロックはそのままテキストとして表示されます。常に、使用するパーサーに合わせて構文を設定してください。

## GFM Table
| Name     | Role     | Status  |
|----------|----------|---------|
| Alice    | Author   | Active  |
| Bob      | Reviewer | Pending |

## GFM Task List
- [x] Write draft
- [x] Add code examples
- [ ] CMO review
- [ ] Schedule publish

どちらも、CommonMark拡張機能なしのパーサーではレンダリングされません。もしドキュメントのツールチェーンが拡張機能なしのCommonMarkを使用している場合、これらのブロックはそのままテキストとして表示されます。常に、使用するパーサーに合わせて構文を設定してください。

Markdown と HTML の混在

ほとんどのMarkdownパーサーは、インラインでraw HTMLを許容します。CommonMarkはデフォルトで許容し、GFMも同様に許容しています（一部のセキュリティ処理を含む）。これにより、パーサーが表現できない要素を表現するために、 <div> または <table> をMarkdownファイルに挿入できます。

通常に破れるのは、MarkdownをHTMLブロックの中にネストすることです。もし <div> を開き、その中にMarkdownを書くと、ほとんどのパーサーはそのブロック全体をraw HTMLとして扱います。HTMLのラップ内でMarkdownコンテンツが必要な場合は、パーサーがそれをサポートしている必要があります（kramdownにはこのために markdown="1" 属性がありますが、他の多くはサポートしていません）。

ルール：構造的なオーバーライドのためにHTMLブロックをまれに使用してください。Markdownファイル内で完全なセクションをHTMLで書くのは避け、その時点でHTMLを直接書くべきです。

APIレスポンスボディにおけるMarkdown

一般的で実用的なパターン：APIはレスポンスフィールドにMarkdown文字列を返します。Notionの富テキストAPI、Slackのブロックキット、さまざまなヘルプデスクやCMSのAPIは、クライアントがレンダリングするMarkdownコンテンツを送信します。

なぜなら、Markdownはコンパクトで人間が読みやすく、エディタに優しいからです。ストレージ **bold text** は、ストレージ <strong>bold text</strong>よりも安価で明確です。また、データ形式が特定のHTML構造に依存しないことにより、データのフォーマットがより独立しています。人間が読みやすいコンテンツを返すAPIを構築している場合、Markdownを文字列フィールドに含めるのは妥当なデフォルトです — ただし、使用している変種を明確にドキュメント化してください。

Markdownを安全にレンダリング

フロントエンドでユーザー入力されたMarkdownを未処理でレンダリングすることは、XSSのベクトルになります。Markdownパーサーがraw HTMLをサポートしている場合、ユーザーのコンテンツに <script>alert('xss')</script> が含まれている場合、それをそのまま通過させます。

解決策：HTML出力をスキャン 、Markdown入力をスキャンするのではなく、HTML出力をスキャンしてください。DOMPurify（ブラウザ）、sanitize-html（Node.js）、またはBleach（Python）などのライブラリは、レンダリングされたHTMLから危険なタグや属性を削除しつつ、安全なフォーマットを維持します。信頼できないMarkdownをDOMに直接レンダリングしないでください。スキャン処理を実施しない限り、パーサーはあなたのセキュリティ層ではありません。、Markdownの入力ではない。DOMPurify（ブラウザ用）、sanitize-html（Node.js）、またはBleach（Python）などのライブラリは、レンダリングされるHTMLから危険なタグや属性を削除し、安全なフォーマットを保持します。信頼できないMarkdownをDOMに直接レンダリングしないでください。パーサーはあなたのセキュリティ層ではありません。

ブラウザで試してみる

Markdownのレンダリングを試したい場合、GFM構文をテストしたり、テーブルやタスクリストのプレビューを確認したり、raw HTMLがMarkdown内でどのように動作するかを確認したりできます。この IO Tools Markdown Editor は、インストール不要でブラウザ上で動作する高速なMarkdownエディタです。ドキュメント作成、READMEファイルのプレビュー、またはフォーマットを確定する前にパーサーの動作をテストするために使用できます。

あなたも好きかもしれません