・ 更新: 入門・テンプレート

執筆・検証: MD Converter編集部

MarkdownをHTMLに変換する方法｜仕組み・手順・画像の注意点

MarkdownをHTMLに変換する仕組みと方法を初心者向けに解説。ブラウザ、エディタ、Pandocの選び方、画像・CSS・CMS・安全性の注意点までまとめます。

MarkdownをHTMLに変換すると何が起きるか

MarkdownからHTMLへの変換は、# 見出しや- リストのような記号を、ブラウザが解釈できるHTML要素へ置き換える処理です。

# お知らせ

- 公開日: 8月17日
- 対象: 全ユーザー

変換後は、おおむね次のようなHTMLになります。

<h1>お知らせ</h1>
<ul>
  <li>公開日: 8月17日</li>
  <li>対象: 全ユーザー</li>
</ul>

Markdownパーサーは文書の構造をHTMLへ変換しますが、余白、色、フォントなどの見た目は主にCSSが担当します。変換結果が「壊れている」ように見える場合も、実際にはHTMLではなくCSSや画像パスが原因であることがあります。

変換方法を選ぶ

方法向いている用途主な注意点
ブラウザの変換サービスインストールせず単発で確認・保存機密性、出力形式、外部通信を確認する
エディタのプレビュー・拡張機能執筆しながら見た目を確認公開先とMarkdown方言が違う場合がある
PandocなどのCLIバッチ処理、CI、再現性が必要コマンド、テンプレート、CSSを管理する
プログラムのMarkdownライブラリWebアプリやCMSへ組み込むサニタイズと依存関係の更新が必要

手作業で一度だけ変換するならブラウザやエディタ、同じ形式を何度も作るならCLI、サービスへ組み込むならライブラリが選びやすい目安です。なお、発表資料などHTMLやPDF以外の形式で出力したい場合はMarkdownをスライドPDFに変換する方法を参照してください。

ブラウザやエディタで変換する手順

どの画面を使う場合も、作業は次の順序で進めます。

  1. .mdファイルを開くか、Markdown本文を貼り付ける
  2. プレビューで見出し、リスト、表、コード、画像を確認する
  3. 必要ならCSSやテーマを選ぶ
  4. HTML断片または完全なHTMLファイルとして保存する
  5. 保存したファイルを別のブラウザでも開いて確認する

「HTMLをコピー」する機能は本文断片だけを返す場合があります。単独で開けるファイルが必要なら、<!doctype html>、<html>、<head>、<body>を含むstandalone形式かを確認してください。保存したHTMLを印刷してPDFとして配布するまでの手順はMarkdownを印刷・PDFに変換する方法で解説しています。

Pandocで完全なHTMLファイルを作る

Pandocを利用できる環境では、次のコマンドでMarkdownから単独のHTML文書を作れます。

pandoc input.md --standalone --output output.html

--standaloneを付けない出力は、別のHTMLへ埋め込むための断片になることがあります。CSSを指定する場合は、そのCSSファイルも共有するのか、HTMLへ埋め込んで1ファイルにするのかを先に決めます。変換環境によってオプションや埋め込み方法は異なるため、利用しているバージョンの公式マニュアルも確認してください。

画像が表示されないときの確認

次のMarkdownは、HTMLファイルから見た相対位置に画像がある場合だけ表示できます。

![構成図](./images/architecture.png)

HTMLだけを別フォルダへ移動すると、相対パスの基準が変わって画像が見つからなくなります。受け渡し方法は次のいずれかに統一します。

  • HTMLと画像フォルダを同じ構成のまま共有する
  • 画像を公開URLへ置き、絶対URLで参照する
  • 画像をdata URLとしてHTMLへ埋め込む

1ファイルへの埋め込みは共有しやすい一方、HTMLの容量が大きくなります。公開Webページではキャッシュしやすい別ファイル、メール添付やオフライン配布では埋め込みというように、用途で選びます。

CSSが反映されないときの確認

HTMLの構造が正しくても、CSSの読み込み先が間違っていると装飾されません。開発者ツールやブラウザのネットワーク表示で、CSSが404になっていないか確認します。また、CMSへ貼り付けた後だけ見た目が変わる場合は、CMS側のテーマCSSが上書きしている可能性があります。

影響範囲を限定するには、変換した本文をクラス付きの要素で囲みます。

<article class="markdown-body">
  <!-- converted HTML -->
</article>

.markdown-body h2 {
  margin-block: 2rem 0.75rem;
}

詳しい切り分けはMarkdownでCSSが効かない理由と対処法も参照してください。

CMSへ貼り付ける前に確認する

WordPressなどのCMSは、貼り付けたHTMLからscript、iframe、一部の属性を削除することがあります。これは変換失敗ではなく、投稿権限や安全対策による制限です。

  • 通常の段落ブロックではなくHTML入力用ブロックを使う
  • 貼り付け前後のHTMLを比較する
  • インラインスタイルが許可されるか確認する
  • 公開前にPCとスマートフォンの両方で確認する

CMSへ継続的に掲載するなら、毎回手で貼り付けるより、CMSが対応するMarkdown機能や公式APIを使う方が差分管理しやすい場合があります。

信頼できないMarkdownはそのまま公開しない

Markdownパーサーによっては、原稿内のHTMLをそのまま出力できます。第三者が入力したMarkdownをWebページに表示する場合、危険なHTMLやURLが混ざる可能性があります。

不特定ユーザーの入力を扱うときは、HTML入力を無効にする、許可するタグと属性を限定する、変換後のHTMLを実績のあるサニタイザーへ通す、といった対策が必要です。表示先のContent Security Policyも併用し、プレビュー画面だけで安全と判断しないでください。

よくある質問

.mdをブラウザで開くと装飾されないのはなぜですか？

多くのブラウザはMarkdownをWebページとして直接描画しません。MarkdownパーサーでHTMLへ変換してから開く必要があります。

変換後のHTMLを直接編集できますか？

編集できます。ただしHTML側の変更は元のMarkdownへ自動では戻りません。継続的に更新する文書ではMarkdownを正本にし、変換を繰り返せる状態にします。

改行が反映されないのは変換ミスですか？

Markdownでは、空行で段落を分けるのが基本です。1回の改行を<br>として扱うかはMarkdown方言や設定で異なります。Markdownで改行されない原因で記法を確認してください。

まとめ

MarkdownからHTMLへの変換では、パーサーだけでなく、完全なHTML文書か、CSSと画像をどう共有するか、公開先がどのタグを許可するかまで確認します。まず短い原稿を変換し、保存ファイルを実際の配布・公開環境で開いてから長い文書へ進むと、原因を切り分けやすくなります。

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