hkdocs/README.md at develop · hiroaki-com/hkdocs

技術ブログ、作業整理、日記などを集約した個人用のナレッジベースサイトです。Docusaurusで構築し、Google Cloud Run上でホストしています。

🌐 https://hkdocs.com/

🔤 English README

📘 システム仕様書

主な機能

コンテンツ

Tech & Exam Docs: 学びの体系的な整理と、資格試験の記録
Blog & Diary: 技術的な学びを綴るブログと、日々の記録を残す日記
Browser Memo: ブラウザ完結型の軽量メモツール
News & Links: 日々の情報収集に役立つ国内外のニュースサイト、学習に役立つリファレンスリンク集

システム

Multilingual Support: Docusaurus i18nによる日本語／英語対応
CI/CD Automation: GitHub ActionsによるビルドからCloud Runへの自動デプロイ
Social Integration: 新規記事の情報をX (旧Twitter) へ自動投稿
CMS Integration: Decap CMSによる日記コンテンツの更新

技術スタック

カテゴリ	技術・サービス
フレームワーク	Docusaurus `v3.10.1`
言語	TypeScript
UIライブラリ	React `v19`
パッケージ管理	pnpm `v11.10.0` (with Corepack)
コンテナ化	Docker, Docker Compose
ホスティング	Google Cloud Run
CI/CD	GitHub Actions
検索	Algolia DocSearch
コンテンツ管理	Decap CMS

システム構成

graph LR
    subgraph "開発 & CI/CD"
        Developer([fa:fa-user 開発者]) -- "① Code Push" --> GitHub(fa:fa-github GitHub)
        Admin([fa:fa-user-shield 管理者]) -- "①' 日記更新 (CMS)" --> GitHub
        GitHub -- "② トリガー" --> Actions(fa:fa-cogs Actions)
        Actions -- "③ ビルド & デプロイ" --> CR(fa:fa-cloud Cloud Run)
        Actions -.-> |自動投稿| X(fa:fa-twitter X)
    end

    subgraph "ユーザー & サイト"
        Visitor([fa:fa-users 訪問者]) -- "④ サイト閲覧" --> CR
        Visitor -- "⑤ 検索" <--> Algolia(fa:fa-search Algolia)
    end

ディレクトリ構成

.
├── .github/              # GitHub Actionsのワークフローとスクリプト
│   ├── scripts/
│   └── workflows/
├── blog/                 # ブログ記事 (日本語)
├── docs/                 # 技術ドキュメント (日本語)
│   ├── exams/
│   └── tech/
├── diary/                # 日記 (日本語)
├── i18n/                 # 国際化対応ファイル (例: 英語翻訳)
│   └── en/
├── src/                  # ソースコードディレクトリ
│   ├── components/       # カスタムReactコンポーネント
│   ├── pages/            # カスタムページ (ニュース、プロフィールなど)
│   └── css/              # カスタムCSS
├── static/               # 静的アセット (画像、CMS設定など)
│   └── admin/            # Decap CMS（コンテンツ管理システム）の設定
├── scripts/              # ビルド前処理スクリプト (動画ショーケース生成など)
├── spec/                 # システム仕様書
├── Dockerfile            # 本番環境用Dockerfile (Cloud Run)
├── Dockerfile.dev        # 開発環境用Dockerfile
├── docusaurus.config.ts  # Docusaurusサイト設定
├── docker-compose.yml    # 開発用Docker Compose設定
├── package.json          # プロジェクトの依存関係とスクリプト
└── deploy.sh             # 手動デプロイスクリプト (Google Cloud Run)

はじめに

前提条件

Git
Docker Desktop (推奨)
または、ローカル環境用の nvm と Node.js v24.20.0

インストール

リポジトリをクローンします。

git clone https://github.com/hiroaki-com/hkdocs.git
cd hkdocs

開発

ローカルでの開発は、Docker Composeを使用する方法を推奨します。

1. Docker Composeを使用する (推奨)

コンテナをビルドして起動 初回、またはDockerfile.devに変更があった場合に実行します。
```
docker-compose up --build
```
2回目以降は --build フラグは不要です。
```
docker-compose up
```
開発サーバーは http://localhost:3000 で利用可能になります。

多言語(i18n)開発 特定の言語で開発サーバーを起動する場合は、以下のコマンドを使用します。

# 英語サイトで開発する場合
docker-compose run --rm --service-ports app pnpm start --locale en

# 日本語サイトで開発する場合
docker-compose run --rm --service-ports app pnpm start --locale ja

停止 Ctrl+Cでサーバーを停止後、コンテナをクリーンアップします。
```
docker-compose down
```

2. ローカル環境を使用する

環境設定

# 1. プロジェクトで指定されたNode.jsバージョンを使用
nvm use

# 2. pnpmを有効化
corepack enable pnpm

# 3. 依存関係をインストール
pnpm install --frozen-lockfile

開発サーバーの起動

# デフォルト言語 (日本語) で起動
pnpm start

# 英語で起動
pnpm start --locale en

開発サーバーは http://localhost:3000 で利用可能になります。

利用可能なスクリプト

pnpm build: 全言語の静的ファイルを build/ ディレクトリに生成します。
pnpm serve: build/ ディレクトリの内容をローカルでプレビューします（http://localhost:8080）。
pnpm typecheck: TypeScriptの型チェックを実行します。
pnpm clear: Docusaurusのキャッシュを削除します。

デプロイ

自動デプロイ

mainブランチにプッシュすると、.github/workflows/deploy_hkdocs_to_cloud_run.yml で定義されたGitHub Actionsワークフローがトリガーされ、ビルドとGoogle Cloud Runへのデプロイが自動的に実行されます。

手動デプロイ

ローカル環境から手動でデプロイする場合は、gcloud CLIが設定されていることを確認の上、以下のスクリプトを実行します。

./deploy.sh

deploy.sh は、グローバルのアクティブ構成ではなく gcloud 構成 hkdocs (プロジェクト hkdocs-461605) を明示的に指定して動作します。実行前に、この構成が存在し認証済みであることを確認してください。

gcloud config configurations list
gcloud --configuration=hkdocs config list

構成名が異なる環境では、deploy.sh 冒頭の GCLOUD_CONFIGURATION を変更するか、プロジェクトIDを環境変数で固定して実行します。

GCP_PROJECT_ID_OVERRIDE=hkdocs-461605 ./deploy.sh

注意: 他プロジェクト (例: sqlquizbook-prod) への誤デプロイを防ぐため、 gcloud config set / gcloud config configurations activate でグローバルのアクティブ構成を切り替える運用は行いません。

ライセンス

コード: このプロジェクトのソースコードは MITライセンスの下で公開されています。
コンテンツ: blog/, diary/, docs/ ディレクトリ内のすべてのコンテンツは CC BY-SA 4.0 の下で公開されています。

FilesExpand file tree

README.md

Latest commit

History