読みにくいmdはClaudeに投げてHTML/CSSにするだけでよかった

はじめに

開発をしていると、手元のドキュメントはだいたいMarkdownで溜まっていきます。仕様書もREADMEも設計メモも、AIに書かせたものも、全部 .md です。

で、それを人に見せようとすると急に読みづらい。Markdownって、そもそも人が読むための形式じゃないんだなと気づきました。

結論から言うと、読みにくいmdはClaudeに投げてHTML/CSSの1枚にしてもらうだけでよかったです。中身は同じなのに読みやすさが全然違ったので、その話をします。手でCSSを書く必要はありません。

Markdownはコンピューターのために読みやすい形式

Markdownが優秀なのは、構造がテキストのまま機械的に取れるところです。

• # の数で見出しの深さがわかる
• 差分がそのまま意味を持つのでGitと相性がいい
• パースしやすいので、ツールもAIも扱いやすい

だからAIに書かせるドキュメントもMarkdownが標準になっているし、それは正しい。コンピューターにとっては、これ以上ないくらい読みやすい形式です。

ただ、そのメリットは全部「機械が処理しやすい」側の話なんですよね。人間が読むときに効いてくる要素は入っていません。

人間が読むときに足りないもの

Markdownで使える装飾は、実質「見出し・太字・リスト・引用・コード・表」だけです。

一番きついのが、強調が太字しかないこと。「絶対にハマるから読んで」も「へえ、そうなんだ」も同じ **太字** になります。結果、太字がページ中に散らばって、どれも目立たなくなる。

あと、そもそも見た目を作る手段がありません。特にGitHubは、レンダリング後に <style> タグを落とし、class / id / インラインの style 属性も削ります（GitHub Community Discussion #22728）。頑張ってHTMLを書き足しても無言で剥がされます。

Markdownが悪いというより、そういう用途のために作られていないというだけの話です。

HTML/CSSにするとどうなるか

やることは単純で、内容はそのまま、見せ方だけHTMLに移します。それだけで変わったのがこのへんでした。

• 情報の役割ごとに見た目を分けられる。ハマりどころは警告ブロック、補足は小さめ薄め、コマンドは等幅。太字1種類で頑張らなくてよくなる
• 目次を左に固定できる（position: sticky を置くだけ）。今どこを読んでいるかが常に見える
• 複数ファイルを1枚にまとめられるので、Ctrl+F が資料全体に効く
• 誰の環境でも同じ見た目になる。GitHubかVS CodeかNotionかで崩れない
• ブラウザの「印刷 → PDF」でそのまま配布物になる

ビルドツールは要りません。.html を1個書いてダブルクリックすれば開きます。npmもnodeも出てこないので、共有ドライブに置くなりSlackに投げるなりでそのまま配れます。

変換はClaudeやCodexに投げるのが早い

とはいえ「HTML書くのか…」と身構えるかもしれませんが、ここはAIに丸投げでいいです。自分は読みにくいmdに当たったら、ClaudeやCodexにそのまま渡しています。

このMarkdownを、人が読む用のHTML1枚に作り直して。
内容は変えずに、見せ方だけ整えてほしい。

- 目次を左に固定
- ハマりどころは警告ブロック、補足は小さめの色で
- ダークモードでも読めるように
- 外部ライブラリなしの単一ファイルで

これで数十秒です。手でCSSを書くことはほぼありませんでした。読みにくいmdほど効果がわかりやすいので、まず1本試してみるのが早いと思います。

ポイントは、pandoc のような機械的な変換ツールではなくAIに頼むことです。機械変換だと見出しが <h2> になるだけで、Markdownの表現力の天井をそのまま引き継ぎます。つまり読みづらさも残る。AIに頼むと、章立てを組み替えたり、どこを警告ブロックにするか判断したりまでやってくれるので、そこが決定的に違いました。

ひとつだけ気をつけているのは、中身が変わっていないか確認すること。「読みやすくして」と頼むとAIが気を利かせて要約したり、書いていないことを補ったりすることがあります。自分は元のmdと並べて、削られた項目がないかだけ見るようにしています。

全部をHTMLにするわけじゃない

READMEまでHTMLにするのは違うと思っています。分け方はシンプルで、

• コンピューターが読むもの（README、設計メモ、AIに渡す資料、PRでレビューするもの）→ Markdownのまま
• 人が読むもの（他チーム向けの解説、オンボーディング資料、配布物）→ HTML/CSS

正典は .md に置いたまま、人に見せるぶんだけHTMLを1枚作る。二重持ちにはなりますが、そこは割り切っています。

まとめ

• Markdownはコンピューターにとって読みやすい形式。人が読む前提では作られていない
• 強調が太字しかないので、情報の重要度の違いを表現できない
• 中身を変えず、見せ方だけHTML/CSSに移すと読みやすくなる
• ビルドツールは不要。.html 1枚をダブルクリックするだけ
• 変換はClaudeやCodexに丸投げでいい。機械変換と違って章立てまで組み替えてくれる

手元に「丁寧に書いたのに読まれてない .md」があったら、それをそのままブラウザで開いて、どこから読めばいいか一目でわかるかを見てみてください。自分はそこで、あ、これ人が読む形じゃないわ、と気づきました。

参考

• GitHub Flavored Markdown doesn't render CSS styles inside a HTML block · GitHub Community Discussion #22728 … GitHubが<style>やclass/idを削る話

関連記事

• プロンプト1行で、赤枠＋番号つきの手順画像をAIに作らせた ~Claude編~ … 同じ「伝わる資料を作る」話を、文章ではなく画像側からやったもの
• AI製UIの「AIっぽさ」を消すのは、地道なひと手間でした ── 非デザイナーがGPTとPencilでUIを作りきるまで … 非デザイナーが見た目を詰めるときの考え方。この記事のCSS部分と地続きです
• AWS RDSとは？ DBを運用込みで借りるサービス … 同じく「初学者に伝わる説明」を意識して書いた解説記事