作業履歴 2025-08-02¶

概要¶

2025-08-02の作業内容をまとめています。

コミット: 7a802b7¶

メッセージ¶

docs: add MkDocs GitHub Actions setup documentation and update index

変更されたファイル¶

A "docs/operation/MkDocs_GitHub_Actions\350\250\255\345\256\232.md"
M docs/operation/index.md

変更内容¶

commit 7a802b728eac9b32c3ea49b5f25beb5579fa5890
Author: k2works <kakimomokuri@gmail.com>
Date:   Sat Aug 2 15:19:51 2025 +0900

    docs: add MkDocs GitHub Actions setup documentation and update index

diff --git "a/docs/operation/MkDocs_GitHub_Actions\350\250\255\345\256\232.md" "b/docs/operation/MkDocs_GitHub_Actions\350\250\255\345\256\232.md"
new file mode 100644
index 0000000..1bb5731
--- /dev/null
+++ "b/docs/operation/MkDocs_GitHub_Actions\350\250\255\345\256\232.md"
@@ -0,0 +1,240 @@
+# 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`を作成します。
+
+```yaml
+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にデプロイします。
+
+#### デプロイキーの生成
+
+1. ローカル環境でSSHキーペアを生成：
+   ```bash
+   ssh-keygen -t rsa -b 4096 -C "your_email@example.com" -f github-actions-deploy
+   ```
+
+2. 生成された2つのファイル：
+   - `github-actions-deploy` (秘密鍵)
+   - `github-actions-deploy.pub` (公開鍵)
+
+#### GitHubでの設定
+
+1. **Deploy Keys**の設定（公開鍵）：
+   - リポジトリの **Settings** → **Deploy keys** → **Add deploy key**
+   - Title: `GitHub Actions`
+   - Key: `github-actions-deploy.pub`の内容をコピー&ペースト
+   - **Allow write access**にチェック
+   - **Add key**をクリック
+
+2. **Secrets**の設定（秘密鍵）：
+   - リポジトリの **Settings** → **Secrets and variables** → **Actions**
+   - **New repository secret**をクリック
+   - Name: `ACTIONS_DEPLOY_KEY`
+   - Value: `github-actions-deploy`（秘密鍵）の内容をコピー&ペースト
+   - **Add secret**をクリック
+
+### 3. package.jsonスクリプトの設定
+
+`package.json`に以下のスクリプトが必要です：
+
+```json
+{
+  "scripts": {
+    "docs:build": "mkdocs build"
+  }
+}
+```
+
+### 4. GitHub Pagesの設定
+
+1. GitHubリポジトリページにアクセス
+2. **Settings** タブをクリック
+3. 左側のメニューから **Pages** を選択
+4. **Source** セクションで以下を設定：
+   - **Source**: `Deploy from a branch`を選択
+   - **Branch**: `gh-pages`を選択
+   - **Folder**: `/ (root)`を選択
+
+### 5. ローカルでのテスト
+
+デプロイ前にローカルで動作確認：
+
+```bash
+# npmパッケージのインストール
+npm install
+
+# ローカルサーバーの起動
+npm run docs:dev
+
+# ビルドのテスト
+npm run docs:build
+```
+
+### 6. デプロイの実行
+
+1. 変更をコミット
+2. mainブランチにプッシュ
+3. GitHub Actionsが自動的に実行される
+4. 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`設定を確認：
+  ```yaml
+  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でないか確認
+
+### デバッグ方法
+
+ワークフローにデバッグステップを追加：
+
+```yaml
+- name: Debug - List files
+  run: |
+    echo "Current directory:"
+    pwd
+    echo "Files in current directory:"
+    ls -la
+    echo "Files in site directory:"
+    ls -la site/
+```
+
+## カスタマイズ
+
+### 複数ブランチのサポート
+
+異なるブランチを異なる環境にデプロイする場合：
+
+```yaml
+on:
+  push:
+    branches:
+      - main
+      - develop
+      - 'release/*'
+```
+
+### Node.jsバージョンの固定
+
+特定のNode.jsバージョンを使用する場合：
+
+```yaml
+- name: Use Node.js
+  uses: actions/setup-node@v3
+  with:
+    node-version: '18.x'  # 特定のバージョンを指定
+    cache: 'npm'
+```
+
+### カスタムドメインの設定
+
+1. `docs/CNAME`ファイルを作成し、カスタムドメインを記載
+2. `mkdocs.yml`に以下を追加：
+   ```yaml
+   extra_files:
+     - CNAME
+   ```
+
+### 環境変数の使用
+
+秘密情報や設定値を環境変数として使用：
+
+```yaml
+- name: Deploy HTML files
+  env:
+    SITE_URL: ${{ secrets.SITE_URL }}
+  run: npm run docs:build
+```
+
+## 参考リンク
+
+- [MkDocs公式ドキュメント](https://www.mkdocs.org/)
+- [GitHub Actions公式ドキュメント](https://docs.github.com/en/actions)
+- [GitHub Pages公式ドキュメント](https://docs.github.com/en/pages)
+- [peaceiris/actions-gh-pages](https://github.com/peaceiris/actions-gh-pages)
\ No newline at end of file
diff --git a/docs/operation/index.md b/docs/operation/index.md
index 6bc8c2f..46a2e82 100644
--- a/docs/operation/index.md
+++ b/docs/operation/index.md
@@ -7,6 +7,7 @@
 ## ドキュメント一覧

 - [セットアップ](./セットアップ.md) - 開発環境のセットアップ手順
+- [MkDocs GitHub Actions設定](./MkDocs_GitHub_Actions設定.md) - GitHub ActionsでMkDocsを自動化する手順

 ## 運用関連情報

@@ -18,13 +19,15 @@
 - **コンテナ化**: Docker + Docker Compose
 - **タスクランナー**: Gulp
 - **図表**: Mermaid + PlantUML
+- **CI/CD**: GitHub Actions + GitHub Pages

 ### 運用フロー

 1. **環境構築**: [セットアップ](./セットアップ.md)を参照
 2. **開発**: ドキュメントの編集・更新
 3. **確認**: ローカル環境でのプレビュー
-4. **デプロイ**: 本番環境への反映
+4. **CI/CD設定**: [MkDocs GitHub Actions設定](./MkDocs_GitHub_Actions設定.md)を参照
+5. **デプロイ**: GitHub Actionsによる自動デプロイ

 ### 関連リンク

コミット: d92a835¶

メッセージ¶

build: add MkDocs deployment workflow and clean site directory before build

変更されたファイル¶

M script/mkdocs.js

変更内容¶

commit d92a835919e2ee72dfa46ea4dad70fc21f4a5aed
Author: k2works <kakimomokuri@gmail.com>
Date:   Sat Aug 2 14:44:34 2025 +0900

    build: add MkDocs deployment workflow and clean site directory before build

diff --git a/script/mkdocs.js b/script/mkdocs.js
index 0690c4e..a536308 100644
--- a/script/mkdocs.js
+++ b/script/mkdocs.js
@@ -22,7 +22,7 @@ export default function(gulp) {
       console.log('Starting MkDocs server using Docker Compose...');

       // Execute docker-compose up command to start mkdocs service
-      execSync('docker-compose up -d mkdocs', { stdio: 'inherit' });
+      execSync('docker compose up -d mkdocs', { stdio: 'inherit' });

       console.log('\nMkDocs server started successfully!');
       console.log('Documentation is now available at http://localhost:8000');
@@ -44,7 +44,7 @@ export default function(gulp) {
       removeSiteDirectory();

       // Execute docker-compose run command to build mkdocs documentation
-      execSync('docker-compose run --rm mkdocs mkdocs build', { stdio: 'inherit' });
+      execSync('docker compose run --rm mkdocs mkdocs build', { stdio: 'inherit' });

       console.log('\nMkDocs documentation built successfully!');

@@ -61,7 +61,7 @@ export default function(gulp) {
       console.log('Stopping MkDocs server...');

       // Execute docker-compose down command to stop mkdocs service
-      execSync('docker-compose down', { stdio: 'inherit' });
+      execSync('docker compose down', { stdio: 'inherit' });

       console.log('MkDocs server stopped successfully!');

コミット: 48ed816¶

メッセージ¶

build: add MkDocs deployment workflow and clean site directory before build

変更されたファイル¶

M .github/workflows/mkdocs.yml

変更内容¶

commit 48ed816d2c279836fd3cd27790134bf93aed7f33
Author: k2works <kakimomokuri@gmail.com>
Date:   Sat Aug 2 14:42:12 2025 +0900

    build: add MkDocs deployment workflow and clean site directory before build

diff --git a/.github/workflows/mkdocs.yml b/.github/workflows/mkdocs.yml
index 41c766d..d7d6a7c 100644
--- a/.github/workflows/mkdocs.yml
+++ b/.github/workflows/mkdocs.yml
@@ -3,7 +3,7 @@ name: Deploy MkDocs
 on:
   push:
     branches:
-      - master
+      - main

 jobs:
   deploy:

コミット: 16a6aa1¶

メッセージ¶

build: add MkDocs deployment workflow and clean site directory before build

変更されたファイル¶

A .github/workflows/mkdocs.yml
M script/mkdocs.js

変更内容¶

commit 16a6aa12c124415548a162e4e6bc6d271fbd5683
Author: k2works <kakimomokuri@gmail.com>
Date:   Sat Aug 2 14:41:33 2025 +0900

    build: add MkDocs deployment workflow and clean site directory before build

diff --git a/.github/workflows/mkdocs.yml b/.github/workflows/mkdocs.yml
new file mode 100644
index 0000000..41c766d
--- /dev/null
+++ b/.github/workflows/mkdocs.yml
@@ -0,0 +1,32 @@
+name: Deploy MkDocs
+
+on:
+  push:
+    branches:
+      - master
+
+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
diff --git a/script/mkdocs.js b/script/mkdocs.js
index 8f34075..0690c4e 100644
--- a/script/mkdocs.js
+++ b/script/mkdocs.js
@@ -1,9 +1,21 @@
 'use strict';

 import { execSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';

 // Function to register the mkdocs:serve task
 export default function(gulp) {
+  // Helper function to remove site directory
+  const removeSiteDirectory = () => {
+    const siteDir = path.join(process.cwd(), 'site');
+    if (fs.existsSync(siteDir)) {
+      console.log('Removing existing site directory...');
+      fs.rmSync(siteDir, { recursive: true, force: true });
+      console.log('Site directory removed successfully!');
+    }
+  };
+
   // MkDocs serve task
   gulp.task('mkdocs:serve', (done) => {
     try {
@@ -28,6 +40,9 @@ export default function(gulp) {
     try {
       console.log('Building MkDocs documentation...');

+      // Remove existing site directory before building
+      removeSiteDirectory();
+
       // Execute docker-compose run command to build mkdocs documentation
       execSync('docker-compose run --rm mkdocs mkdocs build', { stdio: 'inherit' });

@@ -56,4 +71,4 @@ export default function(gulp) {
       done(error);
     }
   });
-}
+}
\ No newline at end of file

コミット: d09d846¶

メッセージ¶

docs: add new documentation files and update mkdocs navigation

変更されたファイル¶

M .gitignore
A docs/reference/case-1/CLAUDE.local.md
A docs/reference/case-1/adr/.gitkeep
A docs/reference/case-1/adr/0001-adopt-typescript.md
A docs/reference/case-1/adr/0002-adopt-vitest.md
A docs/reference/case-1/adr/0003-adopt-ddd-architecture.md
A docs/reference/case-1/adr/0004-adopt-canvas-api.md
A docs/reference/case-1/adr/0005-adopt-vercel-deployment.md
A docs/reference/case-1/adr/index.md
A docs/reference/case-1/development/.gitkeep
A "docs/reference/case-1/development/\343\202\242\343\203\274\343\202\255\343\203\206\343\202\257\343\203\201\343\203\243.md"
A "docs/reference/case-1/development/\345\256\237\350\243\205.md"
A "docs/reference/case-1/development/\350\250\255\350\250\210.md"
A "docs/reference/case-1/evaluation/\343\202\242\343\203\227\343\203\252\343\202\261\343\203\274\343\202\267\343\203\247\343\203\263\350\251\225\344\276\241\343\203\254\343\203\235\343\203\274\343\203\210.md"
A docs/reference/case-1/index.md
A docs/reference/case-1/journal/20250731.md
A docs/reference/case-1/journal/20250802.md
A docs/reference/case-1/journal/index.md
A docs/reference/case-1/operation/.gitkeep
A "docs/reference/case-1/operation/Vercel\350\250\255\345\256\232.md"
A docs/reference/case-1/operation/index.md
A "docs/reference/case-1/operation/\343\202\273\343\203\203\343\203\210\343\202\242\343\203\203\343\203\227.md"
A docs/reference/case-1/reference/.gitkeep
A "docs/reference/case-1/reference/\343\202\210\343\201\204\343\202\275\343\203\225\343\203\210\343\202\246\343\202\247\343\202\242\343\201\250\343\201\257.md"
A "docs/reference/case-1/reference/\343\202\242\343\202\270\343\203\243\343\202\244\343\203\253\343\201\252\350\246\213\347\251\215\343\201\250\350\250\210\347\224\273\343\201\245\343\201\217\343\202\212.md"
A "docs/reference/case-1/reference/\343\202\250\343\202\257\343\202\271\343\203\210\343\203\252\343\203\274\343\203\240\343\203\227\343\203\255\343\202\260\343\203\251\343\203\237\343\203\263\343\202\260.md"
A "docs/reference/case-1/reference/\343\203\206\343\202\271\343\203\210\351\247\206\345\213\225\351\226\213\347\231\272\343\201\213\343\202\211\345\247\213\343\202\201\343\202\213TypeScript\345\205\245\351\226\2001.md"
A "docs/reference/case-1/reference/\343\203\206\343\202\271\343\203\210\351\247\206\345\213\225\351\226\213\347\231\272\343\201\213\343\202\211\345\247\213\343\202\201\343\202\213TypeScript\345\205\245\351\226\2002.md"
A "docs/reference/case-1/reference/\343\203\206\343\202\271\343\203\210\351\247\206\345\213\225\351\226\213\347\231\272\343\201\213\343\202\211\345\247\213\343\202\201\343\202\213TypeScript\345\205\245\351\226\2003.md"
A "docs/reference/case-1/reference/\351\226\213\347\231\272\343\202\254\343\202\244\343\203\211.md"
A docs/reference/case-1/requirements/.gitkeep
A "docs/reference/case-1/requirements/\350\246\201\344\273\266\345\256\232\347\276\251.md"
A docs/reference/case-1/template/ADR.md
A docs/reference/case-1/template/README.md
M mkdocs.yml

変更内容¶

```diff commit d09d8460aba421593af836c01e05e84949215d26 Author: k2works kakimomokuri@gmail.com Date: Sat Aug 2 14:12:14 2025 +0900

docs: add new documentation files and update mkdocs navigation

diff --git a/.gitignore b/.gitignore index ad7ecce..356a593 100644 --- a/.gitignore +++ b/.gitignore @@ -134,4 +134,6 @@ dist

wiki site -.vercel \ No newline at end of file +.vercel + +!docs/**/CLAUDE.local.md \ No newline at end of file diff --git a/docs/reference/case-1/CLAUDE.local.md b/docs/reference/case-1/CLAUDE.local.md new file mode 100644 index 0000000..69ba0ed --- /dev/null +++ b/docs/reference/case-1/CLAUDE.local.md @@ -0,0 +1,253 @@ +# CLAUDE.local.md + + uml diagram