Markdown: マークダウン内での HTML の使用
Markdown は万能ではありません。構文が不十分な場合は、HTML を直接記述するだけです。
1. 学ぶこと
- Markdown に HTML を埋め込むための基本ルール
- インライン HTML とブロックレベル HTML の違い
- HTML がギャップを埋める一般的なシナリオ
- HTML と Markdown の間のエッジケース
- セキュリティと互換性に関する考慮事項
2. フロントエンド開発者の実際の話
(1) 問題点: Markdown の制限ブロック要件
リサは会社の技術ドキュメントを作成していて、表のセル内に色付きのステータス ラベル (赤の「失敗」、緑の「合格」など) を表示する必要がありました。マークダウン テーブルは背景色やテキストの色をサポートしていません。彼女はあらゆる種類の Markdown 回避策を試し、2 時間を無駄にし、最終的にはラベルのスクリーンショットを撮って画像を貼り付ける必要がありましたが、画像は検索できません。
(2) 解決策: Markdown で HTML を直接記述する
シニア エンジニアの Tom は彼女に、「Markdown 内で HTML を書くことができます。」と言いました。リサは、style 属性を持つ <span> タグを使用して、色付きのラベルを作成しました。スクリーンショットは必要なく、テキストは検索可能なままで、HTML を数行追加するだけです。
MARKDOWN
| Test Case | Status |
|:----------|:------|
| User Login | <span style="color: green;">✅ Passed</span> |
| Payment API | <span style="color: red;">❌ Failed</span> |
3. マークダウンの HTML ルール
Markdown は、「HTML をより簡単に記述する方法」として設計されました。その結果、ドキュメントへの HTML の埋め込みがネイティブにサポートされます。
graph TB
A[Markdown Document] --> B[Markdown Syntax]
A --> C[HTML Syntax]
B --> D[Headings / Lists / Tables]
C --> E[Block-level HTML]
C --> F[Inline HTML]
E --> G[div / table / pre]
F --> G[span / img / br]
| HTML タイプ | 特徴 | 例 |
|---|---|---|
| インライン HTML | Markdown 段落内に直接記述します。 <span style="color:red">text</span> |
|
| ブロックレベルの HTML | 空白行で囲まれたスタンドアロン ブロック | <div>content</div> |
| ブロック内のマークダウン | ブロックレベル HTML 内のマークダウンはレンダリングされない可能性があります。 <div>**bold** might not work</div> |
(1) インライン HTML
HTML
This is a paragraph with <span style="color: red;">red text</span> and
<strong>bold text</strong> (using HTML tags).
Press Ctrl + <br> to break line (<br> is an HTML tag).
▶ 例: Markdown では実現できないことを HTML を使用して実現する
HTML
This is text in regular Markdown.
<kbd>Ctrl</kbd> + <kbd>S</kbd> to save file.
Upgrade to <abbr title="Version 3.0">v3.0</abbr> release.
⚠️ 注: ブロックレベルの HTML タグ内では、標準の Markdown 構文 (
**bold** など) は通常解析されません。 HTML タグを直接使用します: <strong>bold</strong>。
(3) Common Block-Level HTML Uses
HTML
<!-- Custom container -->
<div style="border: 1px solid #ddd; padding: 16px; border-radius: 8px;">
<h3>Important Update</h3>
<p>Scheduled maintenance this weekend.</p>
</div>
<!-- Multi-column layout -->
<div style="display: flex; gap: 16px;">
<div style="flex: 1;">Left column</div>
<div style="flex: 1;">Right column</div>
</div>
<!-- Styled table -->
<table>
<tr>
<th style="background: #4CAF50; color: white;">Name</th>
<th>Price</th>
</tr>
<tr>
<td>Product A</td>
<td>$29</td>
</tr>
</table>
5. HTML によるギャップ埋めの一般的なシナリオ
| シナリオ | 値下げ制限 | HTML ソリューション |
|---|---|---|
| 文字の色 | ❌ サポートされていません | <span style="color:red">text</span> |
| 画像の寸法 | ❌ サポートされていません | <img src="url" width="200"> |
| 新しいタブでリンクを開く | ❌ サポートされていません | <a href="url" target="_blank">text</a> |
| 結合された表のセル | ❌ サポートされていません | <td colspan="2">merged</td> |
| カスタムスタイリング | ❌ サポートされていません | <div style="...">content</div> |
| 表内の改行 | ❌ サポートされていません | <br> タグ |
▶ 例: Markdown ではできないことを行う HTML
HTML
<!-- Open in new tab -->
<a href="https://example.com" target="_blank">Open in new window</a>
<!-- Custom image size -->
<img src="logo.png" width="150" alt="Logo" style="border-radius: 8px;">
<!-- Keystroke styling -->
<kbd>Enter</kbd> or <kbd>Ctrl</kbd> + <kbd>V</kbd>
<!-- Callout with background color -->
<blockquote style="background: #fff3cd; border-left-color: #ffc107;">
This is a custom-styled callout box.
</blockquote>
💡 ヒント: これらはすべて、Markdown 自体では実行できないことです。 HTML を適切に使用すると、ドキュメントがより専門的なものになります。ただし、やりすぎないでください。コンテンツの 80% は標準の Markdown で問題ありません。
6. HTML と Markdown の境界
(1) ブロックレベル HTML 内のマークダウンは通常解析されません
HTML
<div>
**This text will not be bold** (Markdown syntax fails inside div)
<strong>This text is bold with HTML</strong>
</div>
例外: 一部のパーサー (Pandoc など) は HTML タグ内のマークダウン解析をサポートしていますが、GFM (GitHub) はサポートしません。安全のため、ブロックレベルの HTML タグ全体で HTML 構文を使用してください。
(2) インライン HTML 内のマークダウン
HTML
<span style="color: red;">**This text may render bold in some parsers**</span>
⚠️ 注: パーサーの動作は異なります。推奨事項: HTML タグ内では HTML 構文を一貫して使用し、Markdown と混合しないでください。
▶ 例: 安全な混合と安全でない混合
MARKDOWN
✅ Safe:
- Write Markdown for body text: **bold**
- Use HTML for custom needs: <span style="color: red;">red</span>
❌ Unsafe:
<div style="padding: 8px;">
**This bold won't work on GitHub**
</div>
7. セキュリティと互換性
(1) これはやってはいけない
HTML
❌ Unsafe: <script>alert('XSS')</script>
❌ Unsafe: <img src="x" onerror="alert('attack')">
❌ Unsafe: <iframe src="https://malicious-site.com"></iframe>
⚠️ 注: GitHub などのプラットフォームは、XSS 攻撃コードを自動的にフィルタリングし、
<script> およびイベント ハンドラーを実行しません。ただし、Markdown ソースを他のプラットフォームにエクスポートする場合は、安全でない HTML を埋め込まないようにしてください。
(2) HTML 互換性チェックリスト
HTML
<!-- ✅ Cross-platform compatible -->
<strong>bold</strong>
<em>italic</em>
<kbd>keystroke</kbd>
<br>
<hr>
<!-- ⚠️ Some platforms don't support -->
<details><summary>Collapsible content</summary>Hidden text</details>
<mark>highlighted text</mark>
💡 ヒント: Markdown をプラットフォーム (GitHub、GitLab、ローカル プレビュー、ブログ) 間で移動する必要がある場合は、HTML の使用を最小限に抑えてください。 HTML が増えると、互換性のリスクも高まります。
8. 完全な例: HTML 拡張マークダウン ドキュメント
TEXT
📖 参照専用
HTML-enhanced Markdown document preview:
Product Changelog v3.2:
- Green-styled callout box: summary of updates
- HTML table: module / status / owner (with colored status)
- Keystroke tags: F5 to refresh
- Bash code block: installation command npm install my-app@latest
- Email link: support@example.com (mailto protocol)
期待される結果: Markdown と HTML を組み合わせた製品ログ — Markdown は標準構造を処理し、HTML は色、キーストローク スタイル、およびカスタム コンテナを処理します。
❓ よくある質問
Q Markdown で HTML を使用することは良い習慣ですか?
A 適度に使用してください。コンテンツの 80% は標準の Markdown で動作します。 Markdown では実行できないこと (色、寸法、新しいタブのリンク) にのみ HTML を使用してください。 HTML が増えると移植性が低下します。
Q GitHub はどの HTML タグをサポートしていますか?
A GitHub は最も安全なインラインおよびブロックレベルの HTML タグをサポートしていますが、
<script>、<iframe>、およびその他の安全でないタグやイベント ハンドラー (onclick など) は除外されます。Q Markdown 構文が HTML タグ内で機能しないのはなぜですか?
A Markdown パーサーは、HTML ブロックを処理するときに内部の Markdown 解析をスキップするためです。これは仕様によるものです。修正: HTML ブロック全体で HTML 構文を使用します。
Q ブロックレベルの HTML タグには周囲の空行が必要ですか?
A はい、必要です。空白行がないと、ブロックレベルの HTML が正しくレンダリングされない可能性があります。つまり、パーサーが HTML ブロックの境界を識別できない可能性があります。
Q HTML で CSS クラス名を使用できますか?
A はい、ただしクラス名は、ターゲット プラットフォームに一致する CSS ルールがある場合にのみ有効になります。 GitHub では、カスタム クラス名は何も行いません。自分の Web サイトで、独自のスタイルを定義できます。
📖 まとめ
- Markdown は、インラインとブロックレベルの両方で HTML の埋め込みをネイティブにサポートします。
- ブロックレベルの HTML には前後に空行が必要です。通常、内部のマークダウンは解析されません
- HTML は次のギャップを埋めます: 色、寸法、新しいタブのリンク、結合されたセル、キーストロークのスタイル
- 安全でない HTML (
<script>、イベント ハンドラー) の埋め込みを回避します。 - HTML が増える = クロスプラットフォーム互換性が悪化する - 適度に使用する
- コンテンツの 80% は標準の Markdown で問題ありません。 HTML は特別なニーズのみに使用されます
📝 練習問題
-
初心者:
<span>を使用して 1 つの単語を赤色に色付けし、<kbd>を使用して「Ctrl+S」ショートカットを表示する Markdown 段落を作成します。 -
中級: 段落とリンクを含むカスタム スタイルの吹き出しボックスを作成します (背景色と枠線を指定した
<div>を使用)。 VS Code と GitHub でどのようにレンダリングされるかを比較します。 -
課題: スタイル付きのヘッダー行と最初の行に結合されたセルを含む、Markdown テーブルを置き換える HTML テーブル (
<thead>および<tbody>を使用) を構築します。 HTML テーブルと Markdown テーブルの両方を同じドキュメントに配置し、そのレンダリングを比較します。
