MkDocs GitHub Actions設定手順¶

このドキュメントでは、GitHub ActionsでMkDocsを自動化し、GitHub Pagesにデプロイする手順を説明します。

前提条件¶

GitHubリポジトリがすでに作成されている
Node.jsプロジェクトが設定済み（package.jsonが存在する）
MkDocsプロジェクトが設定済み（mkdocs.ymlが存在する）
GitHub Pagesを使用する権限がある

手順¶

1. GitHub Actionsワークフローファイルの作成¶

リポジトリのルートに.github/workflowsディレクトリを作成し、その中にmkdocs.ymlを作成します。

name: Deploy MkDocs

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout the repository
        uses: actions/checkout@v3

      - name: Use Node.js latest
        uses: actions/setup-node@v3
        with:
          node-version: latest
          cache: 'npm'

      - name: Install dependencies
        run: npm install

      - name: Deploy HTML files
        run: npm run docs:build

      - name: mkdocs deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
          publish_dir: ./site

2. デプロイキーの設定¶

このワークフローはデプロイキーを使用してGitHub Pagesにデプロイします。

デプロイキーの生成¶

ローカル環境でSSHキーペアを生成：

ssh-keygen -t rsa -b 4096 -C "your_email@example.com" -f github-actions-deploy

生成された2つのファイル：
github-actions-deploy (秘密鍵)
github-actions-deploy.pub (公開鍵)

GitHubでの設定¶

Deploy Keysの設定（公開鍵）：
リポジトリの Settings → Deploy keys → Add deploy key
Title: GitHub Actions
Key: github-actions-deploy.pubの内容をコピー&ペースト
Allow write accessにチェック
Add keyをクリック
Secretsの設定（秘密鍵）：
リポジトリの Settings → Secrets and variables → Actions
New repository secretをクリック
Name: ACTIONS_DEPLOY_KEY
Value: github-actions-deploy（秘密鍵）の内容をコピー&ペースト
Add secretをクリック

3. package.jsonスクリプトの設定¶

package.jsonに以下のスクリプトが必要です：

{
  "scripts": {
    "docs:build": "mkdocs build"
  }
}

4. GitHub Pagesの設定¶

GitHubリポジトリページにアクセス
Settings タブをクリック
左側のメニューから Pages を選択
Source セクションで以下を設定：
Source: Deploy from a branchを選択
Branch: gh-pagesを選択
Folder: / (root)を選択

5. ローカルでのテスト¶

デプロイ前にローカルで動作確認：

# npmパッケージのインストール
npm install

# ローカルサーバーの起動
npm run docs:dev

# ビルドのテスト
npm run docs:build

6. デプロイの実行¶

変更をコミット
mainブランチにプッシュ
GitHub Actionsが自動的に実行される
Actions タブで進行状況を確認

7. デプロイの確認¶

デプロイが成功したら、以下のURLでサイトにアクセス可能：

https://<username>.github.io/<repository-name>/

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

よくある問題と解決方法¶

1. デプロイキーのエラー¶

デプロイキーが正しく設定されていない場合： - Deploy Keysに公開鍵が追加されているか確認 - Secretsに秘密鍵が正しく設定されているか確認 - "Allow write access"がチェックされているか確認

2. ビルドエラー¶

npm run docs:buildが失敗する場合： - package.jsonにスクリプトが定義されているか確認 - MkDocsがインストールされているか確認 - mkdocs.ymlの設定が正しいか確認

3. デプロイ後404エラー¶

GitHub Pagesの設定でgh-pagesブランチが選択されているか確認
デプロイが成功しているか Actions タブで確認

mkdocs.ymlのsite_url設定を確認：

site_url: https://<username>.github.io/<repository-name>/

4. peaceiris/actions-gh-pages@v3 の権限エラー¶

Error: Action failed with error: The process '/usr/bin/git' failed with exit code 128

このエラーが発生した場合： - デプロイキーの権限を確認 - リポジトリのDefault branchがprotectedでないか確認

デバッグ方法¶

ワークフローにデバッグステップを追加：

- name: Debug - List files
  run: |
    echo "Current directory:"
    pwd
    echo "Files in current directory:"
    ls -la
    echo "Files in site directory:"
    ls -la site/

カスタマイズ¶

複数ブランチのサポート¶

異なるブランチを異なる環境にデプロイする場合：

on:
  push:
    branches:
      - main
      - develop
      - 'release/*'

Node.jsバージョンの固定¶

特定のNode.jsバージョンを使用する場合：

- name: Use Node.js
  uses: actions/setup-node@v3
  with:
    node-version: '18.x'  # 特定のバージョンを指定
    cache: 'npm'

カスタムドメインの設定¶

docs/CNAMEファイルを作成し、カスタムドメインを記載
mkdocs.ymlに以下を追加：
```
extra_files:
  - CNAME
```

環境変数の使用¶

秘密情報や設定値を環境変数として使用：

- name: Deploy HTML files
  env:
    SITE_URL: ${{ secrets.SITE_URL }}
  run: npm run docs:build