Markdown to HTML：構文対応とスタイル処理

なぜMarkdownをHTMLに変換するのか

Markdownは書き手に優しい軽量マークアップ言語ですが、ブラウザが理解するのはHTMLだけです。Markdownで書いたコンテンツをウェブページに表示するには、HTMLに変換する必要があります。

よくあるユースケース：

• ブログ記事の公開
• ドキュメントサイトのレンダリング
• READMEの表示
• リッチテキストエディタからのHTML出力

MarkdownとHTMLの構文対応

見出し

Markdown：

# 一级标题
## 二级标题
### 三级标题

HTML：

<h1>一级标题</h1>
<h2>二级标题</h2>
<h3>三级标题</h3>

段落

Markdown：空行で区切られたテキスト。 HTML：<p>段落</p>

強調

Markdown：

**粗体**
*斜体*
~~删除线~~

HTML：

<strong>粗体</strong>
<em>斜体</em>
<del>删除线</del>

リンク

Markdown：

[链接文字](https://example.com)

HTML：

<a href="https://example.com">链接文字</a>

画像

Markdown：

![替代文字](image.png)

HTML：

<img src="image.png" alt="替代文字">

リスト

Markdown 順序なしリスト：

- 项目1
- 项目2

HTML：

<ul>
  <li>项目1</li>
  <li>项目2</li>
</ul>

Markdown 順序付きリスト：

1. 第一项
2. 第二项

HTML：

<ol>
  <li>第一项</li>
  <li>第二项</li>
</ol>

コード

Markdown インラインコード：

这是 `code` 行内代码

HTML：这是 <code>code</code> 行内代码

Markdown コードブロック：

代码块

HTML：

<pre><code>代码块</code></pre>

言語指定ハイライト付き：

const x = 1;

変換後、シンタックスハイライトマークアップが含まれます（ハイライトライブラリが必要）。

引用

Markdown：

> 这是引用

HTML：

<blockquote>这是引用</blockquote>

水平線

Markdown：

---

HTML：

<hr>

テーブル

Markdown：

| 姓名 | 年龄 |
| ---- | ---- |
| Tom  | 25   |

HTML：

<table>
  <thead>
    <tr><th>姓名</th><th>年龄</th></tr>
  </thead>
  <tbody>
    <tr><td>Tom</td><td>25</td></tr>
  </tbody>
</table>

拡張構文

標準Markdown（CommonMark）には以下の機能は含まれませんが、多くのパーサーがサポートしています：

タスクリスト

- [x] 已完成
- [ ] 未完成

HTML：

<ul>
  <li><input type="checkbox" checked disabled> 已完成</li>
  <li><input type="checkbox" disabled> 未完成</li>
</ul>

脚注

正文[^1]

[^1]: 脚注内容

取り消し線

~~删除~~

オートリンク

URLが自動的にリンクになります（を手書きする必要なし）。

定義リスト、目次、数式など

一部のパーサーがサポートしていますが、互換性はまちまちです。

変換の注意点

スタイルの欠落

Markdown to HTMLはタグのみを生成し、スタイルは含まれません。表示効果はCSSに依存します：

• 見出しのサイズと間隔
• リストのインデントとマーカー
• コードブロックの背景とフォント
• テーブルの罫線

変換後にCSSを設定しないと見栄えが良くありません。

XSSセキュリティ

MarkdownはHTMLの埋め込みを許可します。ユーザー入力のMarkdownをHTMLに変換する際、埋め込まれた <script> などのタグがそのまま残り、XSSにつながります。

安全なアプローチ：

• 純粋なMarkdownを使う（インラインHTMLを無効化）
• HTMLに変換後、サニタイズライブラリで危険なタグをフィルタリング
• 信頼できるソースのMarkdownのみ許可

エスケープ文字

Markdown内の特殊文字（、#、_、）はエスケープが必要です。Markdownで \* と書くとアスタリスクが表示され、HTMLに変換後は ` となりタグではありません。

画像パス

Markdown内の相対パスの画像は、HTMLに変換後もパスが変更されません。ディレクトリを変えて表示する場合はパスを調整します。

アンカーリンク

Markdownの見出しは自動的にアンカー（id）を生成します。パーサーによって生成ルールが異なるため、アンカーにリンクする際は注意が必要です。

変換ツール

オンライン変換

Markdownを貼り付けるとツールがHTMLを出力します。一時的な変換に適しています。

Markdown to HTMLツールを使う：

1. Markdownの内容を貼り付け
2. ツールが解析して変換
3. HTMLコードを出力
4. コピーして使用

変換はブラウザ上で実行され、内容はアップロードされません。

エディタ統合

VS Code、TyporaなどのエディタにはMarkdown to HTMLのプレビュー機能が組み込まれています。

プログラムによる変換

JavaScriptではmarked、markdown-itライブラリを使用。Pythonではmarkdown、mistuneライブラリを使用。

変換のコツ

Markdownスタイルの統一

異なるMarkdown方言（CommonMark、GFM、MDX）では変換結果が異なる可能性があります。チーム内で一つの方言に統一しましょう。

プレビューで確認

変換後、ブラウザでプレビューして以下を確認：

• 見出しレベルは正しいか
• リストのネストは正常か
• コードブロックのハイライトは機能しているか
• テーブルは整列しているか
• 画像は表示されているか
• リンクはクリックできるか

CSSの用意

Markdownレンダリング用のCSSスタイルシートを用意し、変換したHTMLに適用すれば美しく表示できます。

元のMarkdownを保持

HTMLはレンダリング結果、Markdownはソースファイルです。Markdownを保持しておけば後から編集でき、HTMLは毎回再生成できます。

よくある質問

変換後にスタイルがおかしい

HTMLにCSSが設定されていません。Markdownレンダリング用のスタイルシートを追加してください。

コードブロックがハイライトされない

シンタックスハイライトライブラリ（highlight.js、Prismなど）が必要です。変換ツールにハイライトが統合されているか確認してください。

テーブルがずれる

Markdownのテーブル構文は厳格ではありません（列数の不一致）。変換前にテーブルフォーマットを確認してください。

特殊文字の表示がおかしい

< > & などの文字はHTMLで特別な意味を持ちます。< > & にエスケープする必要があります。

まとめ

Markdown to HTML変換のポイントは構文の対応マッピングです。CSSのスタイル設定、XSSセキュリティ、特殊文字のエスケープに注意してください。DocsAll Markdown to HTMLツールはブラウザ上で動作し、内容が外部に漏れません。