🚀 GitHub Pages × MkDocs 完全自動化ガイド - CI/CDからデプロイまでワンストップ構築¶
🎯 この記事の目標¶
検索意図: github pages mkdocs で検索するユーザーに対し、MkDocsでGitHub Pagesサイトを構築し、GitHub Actionsで完全自動化する方法を実装レベルで解説します。
こんな方におすすめ
- MkDocsでドキュメントサイトを作りたい
- GitHub Pagesで無料ホスティングしたい
- GitHub Actionsで自動デプロイを実現したい
- 技術ブログやポートフォリオサイトを構築したい
📋 実装ロードマップ¶
Phase 1: 基本環境構築¶
- リポジトリ準備 - GitHub Pages対応リポジトリ作成
- MkDocs初期設定 - 設定ファイルとディレクトリ構造
- ローカル開発環境 - 即座に確認できる開発フロー
Phase 2: GitHub Actions自動化¶
- CI/CDワークフロー - 自動ビルド・デプロイ設定
- 高度な設定 - カスタムテーマとプラグイン統合
- 運用最適化 - パフォーマンスとSEO対策
🛠️ Phase 1: 基本環境構築¶
1.1 GitHubリポジトリセットアップ¶
# 新規リポジトリ作成（GitHubで作成済みの場合）
git clone https://github.com/your-username/your-docs-site.git
cd your-docs-site
# 既存プロジェクトの場合
mkdir docs-site && cd docs-site
git init
重要: リポジトリ名の注意事項
- 個人サイト:
username.github.io→https://username.github.io/ - プロジェクトサイト:
project-name→https://username.github.io/project-name/
1.2 MkDocs環境構築¶
# Python仮想環境作成
python -m venv mkdocs-env
source mkdocs-env/bin/activate # Windows: mkdocs-env\Scripts\activate
# MkDocs関連パッケージインストール
pip install mkdocs mkdocs-material mkdocs-git-revision-date-localized-plugin
# 依存関係ファイル作成
pip freeze > requirements.txt
1.3 基本的なmkdocs.yml設定¶
site_name: あなたのサイト名
site_url: https://your-username.github.io/your-repo-name/
site_description: MkDocsで構築した技術ドキュメントサイト
# テーマ設定
theme:
name: material
palette:
# ライトモード
- scheme: default
primary: indigo
accent: indigo
toggle:
icon: material/brightness-7
name: ダークモードに切り替え
# ダークモード
- scheme: slate
primary: indigo
accent: indigo
toggle:
icon: material/brightness-4
name: ライトモードに切り替え
features:
- navigation.tabs
- navigation.top
- search.highlight
- search.share
- content.code.copy
# プラグイン
plugins:
- search:
lang: ja
- git-revision-date-localized:
type: datetime
timezone: Asia/Tokyo
# マークダウン拡張
markdown_extensions:
- admonition
- pymdownx.details
- pymdownx.superfences
- pymdownx.highlight:
anchor_linenums: true
- pymdownx.inlinehilite
- pymdownx.snippets
- pymdownx.tabbed:
alternate_style: true
# ナビゲーション
nav:
- ホーム: index.md
- ガイド:
- 始め方: guides/getting-started.md
- 設定: guides/configuration.md
- API: api/
- ブログ: blog/
# 追加設定
extra:
social:
- icon: fontawesome/brands/github
link: https://github.com/your-username
- icon: fontawesome/brands/twitter
link: https://twitter.com/your-username
1.4 初期コンテンツ作成¶
# ディレクトリ構造作成
mkdir -p docs/{guides,api,blog}
# メインページ作成
cat > docs/index.md << 'EOF'
# Welcome to Your Documentation
## 🎯 このサイトについて
MkDocsとGitHub Pagesで構築した技術ドキュメントサイトです。
### 🚀 特徴
- **自動デプロイ**: GitHub Actionsで完全自動化
- **レスポンシブ**: モバイル対応のMaterial Design
- **高速検索**: 内蔵検索機能で即座にコンテンツ発見
- **SEO最適化**: 構造化データとサイトマップ自動生成
## 📚 コンテンツ
- [ガイド](/ai-development/guides/getting-started/) - 基本的な使い方
- [API](/ai-development/api/) - APIリファレンス
- [ブログ](/ai-development/blog/) - 技術記事
EOF
# サンプルガイド作成
cat > docs/guides/getting-started.md << 'EOF'
# 🚀 Getting Started
## インストール
\`\`\`bash
pip install mkdocs mkdocs-material
\`\`\`
## 基本コマンド
\`\`\`bash
# 開発サーバー起動
mkdocs serve
# サイトビルド
mkdocs build
\`\`\`
EOF
1.5 ローカル開発フロー¶
# 開発サーバー起動
mkdocs serve
# カスタムポート指定
mkdocs serve --dev-addr 127.0.0.1:8001
# ライブリロード確認
# ブラウザで http://127.0.0.1:8000 を開く
開発効率化のコツ
- ライブリロード: ファイル保存で即座に反映
- 検索テスト: ローカルでも検索機能が動作
- レスポンシブ確認: DevToolsでモバイル表示チェック
⚡ Phase 2: GitHub Actions自動化¶
2.1 GitHub Pages設定¶
リポジトリ設定:
Settings → Pages → Source → GitHub Actionsブランチ戦略:
mainブランチ: ソースコードgh-pagesブランチ: 自動生成（触らない）
2.2 GitHub Actionsワークフロー¶
.github/workflows/deploy.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:
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 0 # git-revision-date-localized-plugin用
- name: Setup Python
uses: actions/setup-python@v4
with:
python-version: '3.11'
cache: 'pip'
- name: Install dependencies
run: |
pip install -r requirements.txt
- name: Build MkDocs
run: |
mkdocs build --verbose --clean
- name: Upload Pages artifact
uses: actions/upload-pages-artifact@v2
with:
path: ./site
deploy:
if: github.ref == 'refs/heads/main'
needs: build
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v2
2.3 高度なワークフロー設定¶
プルリクエスト用プレビュー:
# .github/workflows/preview.yml
name: Build PR Preview
on:
pull_request:
branches: [ main ]
jobs:
build-preview:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Python
uses: actions/setup-python@v4
with:
python-version: '3.11'
cache: 'pip'
- name: Install dependencies
run: pip install -r requirements.txt
- name: Build site
run: mkdocs build
- name: Comment PR
uses: actions/github-script@v6
with:
script: |
github.rest.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: '🚀 Preview build completed! Check the build artifacts.'
})
🎨 Phase 3: 高度なカスタマイズ¶
3.1 カスタムテーマとスタイル¶
カスタムCSS (docs/stylesheets/extra.css):
/* カスタムブランドカラー */
:root {
--md-primary-fg-color: #2563eb;
--md-accent-fg-color: #3b82f6;
}
/* コードブロックの改善 */
.highlight {
border-radius: 8px;
box-shadow: 0 2px 4px rgba(0,0,0,0.1);
}
/* ナビゲーションの強化 */
.md-nav__item--active > .md-nav__link {
font-weight: 600;
color: var(--md-primary-fg-color);
}
/* レスポンシブ画像 */
.md-content img {
max-width: 100%;
height: auto;
border-radius: 4px;
box-shadow: 0 2px 8px rgba(0,0,0,0.1);
}
mkdocs.yml追加設定:
extra_css:
- stylesheets/extra.css
extra_javascript:
- javascripts/extra.js
3.2 プラグイン統合¶
高度なプラグイン設定:
plugins:
- search:
lang: ja
- git-revision-date-localized:
type: datetime
timezone: Asia/Tokyo
locale: ja
- minify:
minify_html: true
minify_css: true
minify_js: true
- social:
cards_layout_options:
background_color: "#2563eb"
- tags:
tags_file: tags.md
3.3 SEO最適化とパフォーマンス¶
構造化データ設定:
# mkdocs.yml
extra:
analytics:
provider: google
property: G-XXXXXXXXXX
schema:
type: WebSite
name: Your Site Name
description: Your site description
url: https://your-username.github.io/
social:
- icon: fontawesome/brands/github
link: https://github.com/your-username
name: GitHub
サイトマップとrobots.txt:
# mkdocs.yml
plugins:
- sitemap:
changefreq: daily
priority: 1.0
site_url: https://your-username.github.io/your-repo/
🔧 運用とトラブルシューティング¶
4.1 よくある問題と解決法¶
デプロイ失敗の対処法
Problem: GitHub Actions が失敗する
# ローカルでビルドテスト
mkdocs build --verbose
# 依存関係確認
pip check
Solution: - requirements.txt のバージョン固定 - プラグインの互換性確認 - Python バージョン統一
パフォーマンス最適化
画像最適化:
# WebP変換自動化
find docs -name "*.png" -exec cwebp {} -o {}.webp \;
ビルド高速化:
plugins:
- optimize:
enabled: !ENV [CI, false]
4.2 メンテナンスとアップデート¶
依存関係更新ワークフロー:
# .github/workflows/update-deps.yml
name: Update Dependencies
on:
schedule:
- cron: '0 9 * * 1' # 毎週月曜日 9時
workflow_dispatch:
jobs:
update:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Update pip packages
run: |
pip install --upgrade pip
pip install -U mkdocs mkdocs-material
pip freeze > requirements.txt
- name: Create PR
uses: peter-evans/create-pull-request@v5
with:
title: "📦 Update dependencies"
body: "Automated dependency update"
branch: update-deps
🎯 成功指標とKPI¶
実装完了チェックリスト¶
- 基本機能: MkDocs サイトがローカルで正常動作
- 自動デプロイ: GitHub Actions でエラーなくデプロイ完了
- レスポンシブ: モバイル・デスクトップで正常表示
- SEO対策: サイトマップ生成とメタデータ設定
- 検索機能: サイト内検索が正常に動作
- パフォーマンス: PageSpeed Insights スコア 90点以上
継続的改善ポイント¶
- コンテンツ品質: 検索クエリに対する完全な回答提供
- ユーザビリティ: ナビゲーションの使いやすさ向上
- SEO最適化: 継続的なキーワード分析と改善
- 技術的負債: 定期的なライブラリアップデート
🔗 関連記事¶
🎯 この記事で解決する検索意図: github pages mkdocs で検索するユーザーが、MkDocsでGitHub Pagesサイトを構築し、完全自動化する方法を段階的に習得できます。実装からデプロイまでワンストップで完結する実践ガイドです。