🚀 GitHub Pages + MkDocs完全ガイド2025 - 自動デプロイで高速サイト構築

GitHub PagesとMkDocsを組み合わせることで、無料かつ高速な技術ドキュメントサイトを構築できます。本記事では、2025年最新のベストプラクティスに基づいた実装方法を完全解説します。

🎯 構築対象

基本構成高度な設定

• GitHub Pages + MkDocs環境
• GitHub Actions自動デプロイ
• MkDocs Material テーマ
• レスポンシブデザイン

• カスタムドメイン設定
• SEO最適化
• 多言語対応
• 検索機能

⚡ 5分でクイック構築

ステップ1: リポジトリ作成

# リポジトリを初期化
mkdir my-mkdocs-site
cd my-mkdocs-site
git init

ステップ2: MkDocs設定

# MkDocs Material インストール
pip install mkdocs-material

# 初期設定ファイル作成
mkdocs new .

ステップ3: 基本設定ファイル

mkdocs.ymlを以下の内容で作成：

mkdocs.yml

site_name: My Documentation Site
site_url: https://yourusername.github.io/my-mkdocs-site/

theme:
  name: material
  features:
    - navigation.tabs
    - navigation.sections
    - navigation.expand
    - navigation.path
    - navigation.top
    - search.highlight
    - search.share
    - toc.follow
    - content.code.copy
  palette:
    - scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: Switch to light mode

nav:
  - Home: index.md
  - Getting Started: getting-started.md
  - API Reference: api.md

plugins:
  - search
  - git-revision-date-localized:
      enable_creation_date: true
      type: timeago

markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences
  - admonition
  - pymdownx.details
  - pymdownx.tabbed:
      alternate_style: true
  - attr_list
  - md_in_html

ステップ4: GitHub Actions自動デプロイ

.github/workflows/deploy-mkdocs.ymlを作成：

.github/workflows/deploy-mkdocs.yml

name: Deploy MkDocs to GitHub Pages

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
      with:
        fetch-depth: 0  # git-revision-date-localized用

    - name: Configure Git Credentials
      run: |
        git config user.name github-actions[bot]
        git config user.email 41898282+github-actions[bot]@users.noreply.github.com

    - name: Setup Python
      uses: actions/setup-python@v4
      with:
        python-version: '3.x'

    - name: Upgrade pip
      run: |
        # install pip=>20.1 to use "pip cache dir"
        python3 -m pip install --upgrade pip

    - name: Get pip cache dir
      id: pip-cache
      run: echo "dir=$(pip cache dir)" >> $GITHUB_OUTPUT

    - name: Cache dependencies
      uses: actions/cache@v3
      with:
        path: ${{ steps.pip-cache.outputs.dir }}
        key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
        restore-keys: |
          ${{ runner.os }}-pip-

    - name: Install dependencies
      run: pip install -r requirements.txt

    - name: Build MkDocs
      run: mkdocs build

    - name: Setup Pages
      uses: actions/configure-pages@v3

    - name: Upload artifact
      uses: actions/upload-pages-artifact@v2
      with:
        path: site/

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

ステップ5: 依存関係設定

requirements.txtを作成：

requirements.txt

mkdocs>=1.5.0
mkdocs-material>=9.0.0
mkdocs-git-revision-date-localized-plugin>=1.2.0

🔧 高度な設定

カスタムドメイン設定

1. CNAMEファイル作成

docs/CNAME

yourdomain.com

1. DNS設定

ドメインのDNS設定でCNAMEレコードを追加：

CNAME @ yourusername.github.io

SEO最適化

mkdocs.ymlにSEO設定を追加：

site_description: 高品質な技術ドキュメントサイト
site_author: Your Name

extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/yourusername
    - icon: fontawesome/brands/twitter
      link: https://twitter.com/yourusername

plugins:
  - search
  - git-revision-date-localized:
      enable_creation_date: true
      type: timeago
  - minify:
      minify_html: true

プラグイン拡張

高機能プラグインの追加：

plugins:
  - search
  - git-revision-date-localized
  - minify
  - redirects:
      redirect_maps:
        'old-page.md': 'new-page.md'
  - tags:
      tags_file: tags.md
  - glightbox:  # 画像ズーム機能

🎨 テーマカスタマイズ

カスタムCSS

docs/stylesheets/extra.cssを作成：

docs/stylesheets/extra.css

:root {
  --md-primary-fg-color: #1976d2;
  --md-accent-fg-color: #2196f3;
}

.md-header {
  background: linear-gradient(90deg, #1976d2, #2196f3);
}

.md-typeset h1 {
  color: var(--md-primary-fg-color);
  border-bottom: 2px solid var(--md-accent-fg-color);
  padding-bottom: 0.5rem;
}

mkdocs.ymlに読み込み設定を追加：

extra_css:
  - stylesheets/extra.css

カスタムJavaScript

docs/javascripts/extra.jsを作成：

docs/javascripts/extra.js

// Google Analytics設定例
gtag('config', 'GA_MEASUREMENT_ID');

// カスタム機能の追加
document.addEventListener('DOMContentLoaded', function() {
    // ページ読み込み時の処理
    console.log('MkDocs site loaded successfully!');
});

📊 パフォーマンス最適化

画像最適化

plugins:
  - optimize:
      enabled: !ENV [CI, false]
      cache: true
      optimize_png: true
      optimize_jpg: true

キャッシュ戦略

GitHub Actions でのビルドキャッシュ設定：

- name: Cache pip dependencies
  uses: actions/cache@v3
  with:
    path: ~/.cache/pip
    key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}

- name: Cache MkDocs build
  uses: actions/cache@v3
  with:
    path: site/
    key: mkdocs-${{ runner.os }}-${{ hashFiles('mkdocs.yml', 'docs/**') }}

🔍 トラブルシューティング

よくある問題と解決法

GitHub Pages設定

リポジトリ設定の「Pages」で「Source」を「GitHub Actions」に変更する必要があります

ビルドエラー対応

# ローカルでビルドテスト
mkdocs build --clean --strict

# 詳細なログ出力
mkdocs build --verbose

プラグインエラー

requirements.txtにすべての依存関係を明記してください

デプロイ失敗の対処法

# 権限エラーの場合
git config --global user.name "github-actions[bot]"
git config --global user.email "actions@github.com"

# キャッシュクリア
mkdocs build --clean

🚀 応用例

マルチリポジトリ構成

複数のプロジェクトドキュメントを統合：

nav:
  - Home: index.md
  - Project A:
    - Overview: project-a/index.md
    - API: project-a/api.md
  - Project B:
    - Overview: project-b/index.md
    - Guide: project-b/guide.md

CI/CDパイプライン統合

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - name: Run tests
      run: |
        # テスト実行
        python -m pytest

    - name: Link check
      run: |
        # リンクチェック
        mkdocs build --strict

📈 運用のベストプラクティス

コンテンツ管理

• 定期更新: 月次でコンテンツレビュー
• SEO対策: メタデータの最適化
• ユーザビリティ: ナビゲーション構造の改善

チーム開発

• ブランチ戦略: feature → develop → main
• レビュープロセス: Pull Requestベースのレビュー
• ドキュメント規約: 執筆ガイドラインの策定

🔗 関連リソース

• MkDocs公式ドキュメント
• Material for MkDocs
• GitHub Actions Documentation

まとめ

GitHub Pages + MkDocsの組み合わせにより、無料で高品質な技術ドキュメントサイトを構築できます。GitHub Actionsによる自動デプロイで、メンテナンス負荷を最小限に抑えながら継続的な更新が可能になります。

本ガイドの設定を基に、あなたのプロジェクトに最適なドキュメントサイトを構築してください！