0
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@8alfalfa8(Y. Fukumori)

第2回：GitHubのREADME.mdからindex.htmlを自動生成

0
Last updated at Posted at 2026-07-23

【GitHub Actions】README.mdをPushするだけで、数式・図対応のindex.htmlを自動生成する仕組みを作った

この記事でわかること

  • ✅ README.md だけ管理して、GitHub Pages対応のHTMLを自動生成する方法
  • ✅ 数式（MathJax）・Mermaid図・シンタックスハイライトがそのまま動くHTMLを出力
  • ✅ Pandocを使った実用的なMarkdown→HTML変換ワークフロー
  • ✅ 私が実際に運用して気づいた2つの注意点と対処法

はじめに：この悩み、ありませんか？

GitHubでREADME.mdを書いていると、こんな場面ありませんか？

「GitHub Pagesで公開したいのに、Markdownのままだと見栄えが悪くて困る…」

「READMEに書いた数式（LaTeX）やMermaidの図が、HTML化したら表示されなくて手動で修正が大変…」

「社内ドキュメントとしてHTMLで配布したいけど、毎回手動で変換するのが面倒で更新が滞る…」

私もREADME.mdをHTMLに変換する際、数式が崩れたりMermaid図が消えたりして何度も手直ししていました。そこで、README.mdをPushするだけで、数式・図・スタイルが完璧なindex.htmlを自動生成する仕組みを作りました。

本記事では、そのワークフローを完全公開します。

なぜREADME.mdからHTMLを自動生成するのか

Markdownは開発者にとって最高の執筆形式ですが、ブラウザ単体やGitHub以外の環境では以下の課題があります。

課題 影響
数式（LaTeX）が表示されない 技術文書の信頼性が損なわれる
Mermaid図が描画されない フローチャートやシーケンス図が消失
スタイルが貧弱 社内共有時に見栄えが悪い
手動変換が必要 更新のたびに作業が発生し、すぐに陳腐化

そこで、README.mdを「唯一の編集対象」 にし、HTML版はGitHub Actionsで自動生成します。

README.md  ← あなたが編集する（唯一の手作業）
      │
      │ GitHub Actions（自動）
      ▼
index.html ← 数式・図・スタイル完備（自動生成・編集不要）

これにより、「Markdownの手軽さ」と「HTMLの見栄え・機能性」 を両立できます。

このWorkflowで実現できること

今回作成したワークフローは、単なる変換ではなく実運用を見据えた機能を搭載しています。

  • 📄 README.mdからindex.htmlを自動生成
  • 🔢 MathJax対応 — LaTeX数式がそのまま表示
  • 📊 Mermaid対応 — フローチャート・シーケンス図がそのまま描画
  • 🎨 CSS自動適用 — 最低限の見栄えを担保
  • 🚀 GitHub Pushだけで更新 — 手作業ゼロ
  • 🧹 変更があった場合のみCommit — 履歴をクリーンに保持

システム構成（処理の流れ）

README.md を Push
        │
        ▼
GitHub Actions 起動
        │
        ▼
Pandoc で HTML生成
        │
        ▼
MathJax 設定を自動挿入
        │
        ▼
Mermaid 設定を自動挿入
        │
        ▼
CSS スタイルを自動適用
        │
        ▼
index.html 生成
        │
        ▼
変更があれば自動 Commit & Push

開発者がやることは「README.mdを更新してPushする」だけ。
HTML版は触る必要がありません。

事前準備

特別なツールのインストールは不要です。GitHub Actions上でPandocを自動インストールします。

Workflowファイルは以下に配置します。

.github/workflows/readme2index.yaml

ワークフロー全文

name: Generate index.html from README.md

on:
  push:
    paths:
      - 'README.md'
      - '.github/workflows/readme2index.yaml'
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Install Pandoc
        run: |
          sudo apt-get update
          sudo apt-get install -y pandoc

      - name: Generate HTML with Pandoc
        run: |
          pandoc README.md \
            -s \
            --from markdown \
            --to html5 \
            --mathjax \
            --metadata title="プロジェクト概要" \
            -o index.html

      - name: Inject MathJax and Mermaid
        run: |
          # MathJax設定を<head>直後に挿入
          MATHJAX='<script src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script>
          <script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>'

          # Mermaid設定を</body>直前に挿入
          MERMAID='<script type="module">
            import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs";
            mermaid.initialize({ startOnLoad: true });
          </script>'

          # HTMLファイルに挿入
          sed -i "s|</head>|${MATHJAX}</head>|" index.html
          sed -i "s|</body>|${MERMAID}</body>|" index.html

      - name: Inject CSS styles
        run: |
          CSS='<style>
            body {
              font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
              line-height: 1.6;
              max-width: 900px;
              margin: 0 auto;
              padding: 20px;
              color: #24292f;
            }
            pre {
              background: #f6f8fa;
              padding: 16px;
              border-radius: 6px;
              overflow-x: auto;
            }
            code {
              font-family: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, Courier, monospace;
              background: rgba(175, 184, 193, 0.2);
              padding: 0.2em 0.4em;
              border-radius: 3px;
            }
            pre code {
              background: transparent;
              padding: 0;
            }
            img {
              max-width: 100%;
            }
            table {
              border-collapse: collapse;
              width: 100%;
              margin: 16px 0;
            }
            th, td {
              border: 1px solid #d0d7de;
              padding: 8px 12px;
            }
            th {
              background: #f6f8fa;
            }
          </style>'

          sed -i "s|</head>|${CSS}</head>|" index.html

      - name: Verify output
        run: |
          if [ ! -s index.html ]; then
            echo "Error: Generated index.html is empty."
            exit 1
          fi
          echo "index.html generated successfully ($(wc -c < index.html) bytes)"

      - name: Commit and push if changed
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add index.html
          if git diff --cached --quiet; then
            echo "No changes to commit."
          else
            git commit -m "docs: auto-generate index.html from README.md"
            git push
          fi

ワークフローのポイント解説

① README更新を検知

on:
  push:
    paths:
      - 'README.md'

paths フィルタでREADME.mdの変更のみを監視。不要なWorkflow実行を防ぎ、CI実行回数を節約します。

② Pandocで高品質なHTML生成

pandoc README.md -s --from markdown --to html5 --mathjax -o index.html
  • -s（standalone）：完全なHTMLドキュメントとして出力
  • --mathjax：LaTeX数式をMathJax形式に変換
  • --to html5：HTML5準拠の出力

③ MathJax対応

READMEに書いた数式がそのまま表示されます。

$E = mc^2$

$$
x^2 + y^2 = z^2
$$

ブラウザ上できれいにレンダリングされます。

④ Mermaid対応

READMEに書いた図もそのまま描画されます。

⑤ CSS自動適用

GitHub風のシンプルなスタイルを自動適用。フォント、コードブロック、テーブル、行間を調整し、読みやすいHTMLを生成します。

⑥ 変更がなければCommitしない

if git diff --cached --quiet; then
  echo "No changes to commit."

無駄なコミット履歴を増やさず、Gitログをクリーンに保ちます。

実際に運用して気づいた2つの注意点

⚠️ 注意点1：Mermaidのレンダリングタイミング

初期版では、MermaidがDOM読み込み前に実行されて図が描画されないケースがありました。

対処：mermaid.initialize({ startOnLoad: true }) を設定し、DOM構築完了後に描画するよう制御しました。

⚠️ 注意点2：PandocのCSS上書き

Pandocがデフォルトで出力するスタイルと、独自CSSが競合してレイアウトが崩れることがありました。

対処：--to html5 でPandocのデフォルトテンプレートを使いつつ、<style> タグで上書きする方式に統一しました。

導入後の効果

項目 Before After
HTML変換の手間 手動でPandoc実行（5分〜） 0分（完全自動）
数式の表示 崩れる・手動修正必要 MathJaxで自動レンダリング
Mermaid図の表示 消える・手動修正必要 自動描画
GitHub Pages公開 別途HTML管理が必要 README.mdだけでOK
ドキュメント更新頻度 低い（手間のため） 高い（Pushだけなので）

今後の展開

このWorkflowは、GitHub Actions活用シリーズの第2弾です。

さらに、以下のような多言語対応も容易に拡張できます。

README.ja.md → index.ja.html
README.md    → index.html
README.zh.md → index.zh.html

第1回の「多言語自動翻訳Workflow」と組み合わせることで、「日本語README → 自動翻訳 → 自動HTML生成」 という完全自動化も実現可能です。

まとめ

項目 内容
解決した課題 README.mdのHTML化手間、数式・図の表示崩れ
キーワード GitHub Actions, Pandoc, MathJax, Mermaid, 自動ドキュメント生成
得られる効果 GitHub Pages公開が楽になる、ドキュメント品質維持、更新頻度向上

この仕組みを導入すれば、README.mdを書くだけで、見栄えの良いHTMLドキュメントが自動的に完成します。社内共有やGitHub Pages公開が驚くほど楽になります。

ぜひご自身のリポジトリで試してみてください。動作報告や改善案があれば、コメントやGitHub Issueでお知らせください！

ソースコード

今回ご紹介したGitHub Actions Workflowのソースコードは、GitHubでも公開しています。

以下のリポジトリから、Workflowファイルや設定内容を確認できます。

本記事がお役に立ちましたら、いいね❤️ や GitHub Star⭐ をいただけると励みになります！IssueやPull Requestも歓迎していますので、改善案や機能追加のアイデアがありましたら、お気軽にご連絡ください。

📢 掲載通知を受け取る
著者をフォローして次回または新掲載の通知をお待ちください！

0
1
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?