Markdownが常に正解とは限らない：AIの出力をHTMLで受け取るべき場面
Claude、ChatGPT、Codexの出力をMarkdownとHTMLのどちらで受け取るか、編集、共有、可視化の目的別に判断する基準です。
編集と変更履歴を残す原本はMarkdown、人が読んで判断する最終レビュー版は HTMLで受け取るのが実用的です。どちらか一つを永久に選ぶのではなく、 Markdownを原本として維持し、必要なときにHTMLを生成する流れが最も 管理しやすくなります。
MarkdownとHTMLは競合ではなく異なる層
CommonMarkは段落、見出し、リスト、 引用、コードなどMarkdownの基本構文を明確に定義します。プレーンテキスト なので軽く、Gitのdiffが読みやすく、別のAIへの再入力にも向きます。
HTMLはブラウザーが表現する文書構造です。MDNのHTML文書 で説明されるセマンティック要素、表、画像、リンク、スタイルを使えば、 要約カード、グラフ、目次、レスポンシブレイアウトまで一ファイルに 含められます。
AnthropicのThe unreasonable effectiveness of HTML も、Claude Codeチームが長い成果物を読みやすく豊かに伝えるためにHTMLを 使う例を示しています。Markdownを捨てる主張ではなく、最終表現の選択肢を 増やす事例として捉えるのが正確です。
六つの状況で選ぶ基準
| 状況 | 先に選ぶ形式 | 理由 |
|---|---|---|
| PR説明、Issue、技術仕様 | Markdown | ツールが直接描画し、行単位のdiffが残る |
| 非開発者向けレポート・ダッシュボード | HTML | ブラウザーリンクで同じレイアウトを渡せる |
| リポジトリで長期管理する文書 | Markdown | 変更履歴とレビューが容易 |
| グラフ、視覚比較、簡単な操作 | HTML | CSS、インラインSVG、小さなスクリプトが使える |
| 別のAIやスクリプトへの中間入力 | Markdown | タグが少なく、構造を再利用しやすい |
| 外部パートナーへ渡すレビュー版 | HTML | 相手のエディターとMarkdownビューアーに依存しにくい |
境界が曖昧なら一つだけ質問します。
次にこのファイルを開く人は、エディターとブラウザーのどちらを開くか。
継続して編集するファイルはMarkdown、ブラウザーで読み判断するファイルは HTMLに近い選択です。
同じ分析をMarkdownで受け取るプロンプト
Markdownでは原本と根拠の管理に集中します。
前四半期の決済失敗原因をMarkdownファイルで分析してください。
- ファイル名: payment-failure-analysis.md
- 冒頭に結論と次の行動をそれぞれ3件以内で要約。
- H2とH3で構造化し、表はGFMの表構文を使用。
- 数値にはデータ出典と基準日を併記。
- 未確認は「未確認」、推測は「仮定」と表示。
- 画像や装飾は使わず、必要なグラフは
[グラフ: 比較内容] のプレースホルダーにする。
- 最後に「出典」「仮定」「未解決の質問」を追加。
- APIキー、個人情報、顧客データを含めない。
目的: リポジトリへコミットし、diffで変更履歴を管理する。Markdownの表やチェックボックスはレンダラー拡張によって表示が異なるため、 最終共有前に実際のビューアーで確認します。
同じ分析をHTMLで受け取るプロンプト
HTMLは内容を書き直す段階ではなく、レビュー体験を作る段階で使います。
payment-failure-analysis.mdの内容と数値を変更せず、
共有用の単一HTMLファイル payment-failure-analysis.html に変換してください。
- <!doctype html>から</html>までの完全な文書一つ。
- CSSは<style>、必要な小さなJavaScriptは<script>へインライン化。
- 外部CDN、Webフォント、相対パス画像、ビルドツールは禁止。
- 上部に要点、基準日、「一時レビュー用」の表示。
- 目次はページ内アンカーリンクで構成。
- 表にcaptionとth scopeを含める。
- グラフは外部ライブラリなしのアクセシブルなインラインSVG。
- 360pxのモバイル幅と印刷スタイルに対応。
- システムフォントを使い、全体を1MB以下にする。
- APIキー、トークン、個人情報、顧客データ、内部URLを含めない。
目的: コードを読まない関係者へリンクでレビューを依頼する。「内容と数値を変更しない」という制約が重要です。形式変換の途中でモデルが 文章を整え、意味や数字まで変えないよう境界を示します。
二つの形式を維持する最も単純な流れ
- AIから先にMarkdownの原本を受け取る。
.mdをリポジトリまたは文書ツールでレビューする。- 共有時にMarkdownを入力として単一HTMLを生成する。
- HTMLを再生成可能な成果物として扱う。
- 修正はMarkdownへ反映し、HTMLを再生成する。
原則は一文です。
編集はMarkdownで、伝達はHTMLで。
HTMLを直接修正すると原本とレビュー版の数値がずれる可能性があります。 両ファイルをコミットする必要があるなら生成を自動化し、不要ならHTMLは 一時成果物のディレクトリに置きます。
両方の形式をリンクで共有する
完成した .md または .html はHTML2WEBのHTML-to-URLツール
へアップロードするか本文を貼り付けられます。ログイン不要の無料経路は
1MBまで対応し、有効期限は30分・1時間・24時間から選べます。標準は1時間、
共有結果には標準で noindex が適用されます。
開発者にはMarkdown原本リンク、非開発者にはHTMLレビューリンクと分ける こともできます。ただし、どちらも一時共有物であり、継続的な文書運用を 置き換えるものではありません。
実務で壊れやすい点
Markdownの表が記号のまま見える
表、チェックボックス、脚注はMarkdown実装の拡張機能である場合があります。 共有先が同じ拡張を支えるか確認するか、HTMLレビュー版に変換します。
HTMLが断片だけ出力される
<section> 一つだけなら完全な文書ではありません。doctype、html、
head、body をすべて含めて再依頼します。
HTMLの外部素材が消える
別CSS、JavaScript、ローカル画像は単一ファイルと一緒に公開されません。 最初のレビュー版は一つのファイルだけで動くようにします。
Base64画像で1MBを超える
大きな画像を本文へ直接埋め込まず、表、CSS、インラインSVGへ変えます。 画像が中心で容量を減らせない場合は本番ホスティングが適しています。
HTMLを手で直して原本とずれる
HTMLを修正せずMarkdownを直して再生成します。生成日とデータ基準日を 文書上部に表示すると、古いレビュー版も見分けやすくなります。
セキュリティ境界は形式に依存しない
MarkdownもHTMLも内容をそのまま保持します。HTMLコメント、JavaScript定数、 折りたたみ領域の値もページソースから確認できます。
パスワードは補助境界であり、noindex はアクセス制御ではありません。
APIキー、トークン、個人情報、顧客データは形式に関係なく公開前に削除します。
よくある質問
AIには常にMarkdownから依頼するべきか
継続編集や根拠追跡が必要なら有利です。一度見て破棄する視覚的モックアップ なら、最初からHTMLでも構いません。
HTMLをGitへコミットしてはいけないか
禁止ではありませんが、生成HTMLのdiffは読みにくい場合があります。原本を Markdownや構造化データで管理し、HTMLを自動生成する方法を先に検討します。
PDFとHTMLではどちらがよいか
印刷、保存、固定レイアウトにはPDF、モバイルブラウザーでの閲覧と操作には HTMLが向きます。長期保存文書は組織の文書方針に従います。
MarkdownもHTML2WEBで読みやすく表示されるか
はい。Markdownを安全なブラウザー文書としてレンダリングし、一時リンクで 共有できます。グラフや複雑なレイアウトが必要な場合だけHTMLを選びます。