2026年4月13日

Markdown CSS が効かない4つの原因と対処法

Markdown CSS が効かない主な4原因（セレクタ不一致・サニタイズ・パス/CORS・印刷CSS）と、開発者ツールを使った切り分け手順を解説。このサイトのレイアウト設定での安全なスタイル適用方法も紹介します。

この記事でわかること

Markdown に CSS が効かない主な4つの原因
各原因を開発者ツールで切り分ける手順
Markdown から生成されるHTML の構造（セレクタの合わせ方）
サニタイズ（XSS 対策）で style 属性が除去される仕組み
外部 CSS のパス・CORS・読み込み順のトラブルシューティング
印刷・PDF だけ崩れる場合の確認方法

Markdown ファイルに CSS を直接書くことはできません。表示の流れは、まず Markdown を HTML に変換し、次に ブラウザがその HTML に CSS を適用する、という二段階です。「スタイルが効かない」と感じたときは、(1) セレクタが実際の DOM と合っていない、(2) サニタイズや CSP で style が落ちている、(3) 外部 CSS のパスや読み込みに失敗している、(4) 印刷・PDF のみの問題のいずれかが大半です。

理由1: セレクタと生成 HTML が一致しない

Markdown から生成される HTML は、見出しは <h1>〜<h6>、リストは <ul> / <ol> と <li>、コードは <pre><code> のように決まった形です。手元の CSS で .title や #main を指定していても、変換結果にそのクラスや id が付いていなければスタイルは当たりません。ブラウザの開発者ツールで、変換後の要素ツリーを開き、実際に付いているタグ名・クラスに合わせてセレクタを書き直してください。見出しなら article h1 のように祖先要素＋タグで狙うと、クラスに依存しにくくなります。

よくある Markdown → HTML のマッピング：

Markdown 記法	生成される HTML
`# 見出し1`	`<h1>見出し1</h1>`
`太字`	`<strong>太字</strong>`
`- リスト`	`<ul><li>リスト</li></ul>`
`コード`	`<code>コード</code>`
`\```コードブロック````	`<pre><code>コードブロック</code></pre>`

理由2: インライン style や class がサニタイズされる

XSS 対策のため、ブログや Wiki、社内ポータルでは HTML 出力時に style 属性や class、特定のタグが削除されることがあります。Markdown 内に <span style="color:red"> と書いても、サニタイザが除去すれば見た目は変わりません。許可タグの一覧をドキュメントで確認し、許可されていない書き方をしていないかを確認してください。自前の変換パイプラインなら、DOMPurify 等の許可リスト設定を見直す必要があります。

理由3: 外部 CSS のパス・CORS・読み込み順

<link rel="stylesheet" href="..."> で別ファイルを読み込む場合、相対パスがビルド後の配置と合っていないと 404 になります。また CSP で style-src が厳しく、インラインや外部ドメインがブロックされているケースもあります。さらに 読み込み順が後ろのテーマ CSS に上書きされると、「書いたはずのルールが負けている」ように見えます。開発者ツールの Network タブで CSS が 200 で取れているか、Elements で打ち消し線になっていないかを確認してください。

理由4: 印刷・PDF だけ効かない

画面では当たっているのに PDF や印刷だけ崩れるときは、@media print 内の別ルールや、印刷用のユーザースタイルが影響していることがあります。Markdown 本文の話と別レイヤーなので、PDF・印刷で崩れる原因と対策と合わせて確認するとよいです。

対処の方向性

生成 HTML の実際の DOM に合わせてセレクタを書く。
利用ツールのドキュメントで 許可される HTML / CSS を確認する。
このサイトでは、レイアウト設定から安全な範囲でフォント・余白・行間などを指定できます。

詳細度と `!important` に頼る前に

どうしても当たらないとき、詳細度を上げる（祖先セレクタを増やす）、カスタムプロパティでテーマと連携する、といった手があります。安易に !important を増やすと、あとからの保守で打ち消し合いが起きやすくなります。フレームワーク付きのサイトでは、リセット CSS やユーティリティクラスが Markdown 出力の margin を上書きしていることもあるため、開発者ツールの Computed で最終値を追うと早いです。

よくある質問（FAQ）

Q. 開発者ツールで確認するとスタイルに打ち消し線が付いています

別のルールに上書きされています。Elements タブで打ち消しになっているルールを探し、どのセレクタに負けているかを確認してください。詳細度が高いセレクタか、後から読み込まれるスタイルシートによって上書きされている可能性があります。

Q. `style="color:red"` を Markdown に書いたのに適用されません

使用しているツールやサイトが HTML 属性をサニタイズしている可能性が高いです。インライン style 属性は多くのサニタイザでデフォルト除去されます。クラスを使った CSS ルールに変えるか、ツールが許可している方法を確認してください。

Q. ローカルでは CSS が効くのに、デプロイ後に効きません

外部 CSS ファイルのパスがビルド後の配置と一致しているか確認してください。また CSP（Content Security Policy）が本番環境で厳しく設定されており、外部 CSS や inline スタイルをブロックしている可能性があります。

Q. このサイトで CSS をカスタマイズするには？

このサイトではレイアウト設定からフォントサイズ・行間・余白・最大幅を調整できます。生 CSS の直接入力はセキュリティの観点から制限されていますが、レイアウト設定で多くのスタイルニーズに対応できます。

Q. PDF 保存時だけスタイルが崩れます

PDF はブラウザの @media print スタイルを使用します。画面用 CSS と印刷用 CSS が異なることが原因です。詳細は Markdown PDF・印刷で崩れる原因と対策を参照してください。

ツールMarkdown を HTML に（md to html）ブラウザで .md をプレビューし、レイアウトを調整して HTML をダウンロードできます。ツールを開く