MarkdownとHTML：適切なソース形式を選ぶ

書き込み速度、ソースの可読性、移植性、バージョン管理の差分が最も重要ならMarkdownを選びましょう。ドキュメントにMarkdownでは表現できないセマンティクスやコンポーネントが必要な場合、またはレンダリングされるWebページを直接所有している場合はHTMLを選びます。

Markdownは、作成者がドキュメントの階層と言葉に集中できるようにします。クラス名、スペーシングトークン、レスポンシブブレークポイントを決めることなく、見出しは見出しとして書けます。これにより、日常の技術文書作成が速くなり、レビューの差分も穏やかになります。

トレードオフは、最終的な見た目をレンダラーが決めることです。同じテーブルやタスクリストでも、GitHub、エディター、静的サイトジェネレーターで見た目が異なる可能性があり、一部の拡張機能はどこでも使えるとは限りません。

HTMLは、コアのMarkdownでは表現できないナビゲーション、図、詳細パネル、フォーム、定義、メディア、リッチなアクセシビリティの関係性を表現できます。CSSと組み合わせることで、精密なレイアウトやデザインシステムをサポートします。

その力には責任が伴います。作成者やコンポーネントシステムは、有効なセマンティクス、キーボードフレンドリーな操作、レスポンシブなスタイリング、安全なコンテンツ境界を提供する必要があります。信頼できないドキュメント由来の生HTMLは、サニタイズなしに注入してはなりません。

一般的なパイプラインは、記事をMarkdownで保存し、HTMLに変換してから、共有コンポーネントとCSSを適用します。作成者は読みやすいソースを得て、ウェブサイトはナビゲーション、シンタックスハイライト、レスポンシブレイアウト、アクセシビリティ機能を得ます。

Markdown内で生HTMLを許可するシステムもあります。その逃げ道は控えめに使いましょう。移植性が低下し、セキュリティ面が広がる可能性があります。公開プラットフォームがドキュメント化されたコンポーネントや拡張機能を提供している場合は、そちらを優先してください。

意味的な見出し、段落、リンク、リスト、コード、単純なテーブルには通常、明確な対応物があります。CSSレイアウト、クラス名、スクリプト、フォーム、カスタムウィジェットにはありません。優れた変換は読みやすいドキュメントを残し、Webアプリケーションを置き去りにします。

変換後は、相対リンク、画像参照、コードフェンス、生の断片を確認してください。エディターのプレビューは信頼できない出力をサニタイズするべきですが、公開にも独自のコンテンツポリシーが必要です。