MkDocsでHTMLファイルを直接公開する方法¶

なぜHTMLを直接公開したいのか¶

既存のWordPressや静的ジェネレーターから輸出したHTMLをそのまま活用したい
Markdown化するコストが高いレイアウトや埋め込みウィジェットを保持したい
A/Bテストやランディングページなど短命のページを素早く追加したい

MkDocs Materialでも、docs/ 配下に置いたHTMLはビルド時にそのままコピーされます。以下の手順で運用に組み込めます。

基本手順¶

docs/ 配下にHTMLを配置する（例: docs/blog/readable-code.html）。
同階層のMarkdownからリンクまたはiframeで参照する。
mkdocs build --strict で出力を確認し、必要なら mkdocs gh-deploy で公開する。

Note: HTMLファイルはMkDocsのテンプレート処理を受けないため、テーマやヘッダーを再現したい場合はMarkdown側で囲むか、Jinjaテンプレートを利用します。

HTMLをブログ記事として扱う方法¶

1. HTMLファイルを配置¶

/docs/blog/
  ├─ readable-code.html    # 元のHTML
  ├─ readable-code.md      # 埋め込み用Markdown（日本語）
  └─ readable-code.en.md   # 埋め込み用Markdown（英語）

- iframe内のsrcはMarkdownファイルから見た相対パスで指定します。 - 翻訳ペア運用の場合、Markdown側も.md + .en.mdを作成しておくとcheck_article_pairs.pyを回避できます。

2. iframeで読み込む¶

<div class="embedded-html-article">
  <iframe src="../readable-code.html"
          title="リーダブルコード：プログラマー必読の実践術"
          loading="lazy"
          style="width: 100%; min-height: 2600px; border: none;">
  </iframe>
</div>

- styleで高さやボーダーを指定し、Materialテーマとの段差を調整します。 - スクロールバーが不要な場合はwidth: 100%に加えてheightを固定するか、min-heightで余裕を持たせます。

3. ナビゲーションへ追加¶

mkdocs.yml の nav にMarkdown側（iframeを含むページ）を追加します。HTMLファイルを直接指定するとMaterialの検索やbreadcrumbに載らないため、公開ページとしてはMarkdown側をナビに登録するのが無難です。

  - 📰 ブログ:
      - 記事一覧: blog/index.md
      - 最新記事:
          - リーダブルコード：プログラマー必読の実践術: blog/readable-code.md

HTMLを直接リンクする場合¶

既存のMarkdownから[HTML版はこちら](../readable-code.html)のようにリンクするだけでも公開できます。
ナビゲーションに並べるときはMarkdownのプレースホルダーを作成し、meta refreshでリダイレクトする方法もあります。

<meta http-equiv="refresh" content="0; url=../readable-code.html">

ただし、Materialテーマの検索結果やフィードはMarkdownページを基準に生成されるため、直接HTMLのみをナビに入れる運用は非推奨です。

注意点¶

検証環境: HTML内で外部スクリプトやスタイルを読み込むと mkdocs build --strict やリンクチェッカーで警告が出ることがあります。extra_css への切り出しを検討してください。
翻訳対応: 多言語構成では、HTMLは単一言語として扱われるため、Markdown側でロケールごとに適切な説明文や埋め込みを準備します。
ESCAPE: iframe内に相対パス画像がある場合、../の深さをHTMLの配置場所に合わせて調整する必要があります。
キャッシュ: gh-pages へデプロイ後はCDNキャッシュが効くため、更新を確認できない場合はクエリパラメータを付与するかキャッシュパージを実行します。

まとめ¶

docs/ 配下にHTMLを置けばMkDocsでそのまま配信できる。
公開導線はMarkdownのスタブ（iframe／リンク）経由にすると他機能と整合が取れる。
ビルドやリンクチェックの警告を監視しつつ、再利用性を考えてCSSやスクリプトを整理する。

こうした運用をテンプレート化しておくと、既存HTML資産を活かしたコンテンツ追加が容易になります。