コンテンツにスキップ

ドキュメントサイトの閲覧（ローカル）と将来の Private Pages 化

設計ドキュメントサイト（mkdocs-material）は 現状は公開デプロイせず、ローカル閲覧と private リポジトリ上での docs/**.md 直接閲覧で運用する。将来 GitHub Enterprise へ移行後に GitHub Private Pages（アクセス制御付き）デプロイを追加する予定。

  • CI（.github/workflows/docs.yml）は docs/** / mkdocs.yml 変更で mkdocs build --strict の検証のみを行う（公開デプロイなし）。
  • 公開しない理由: 現行プラン（GitHub Team）は Private Pages 非対応で、Pages を有効化すると URL を知る誰でも閲覧できる公開状態になる。設計書（アーキテクチャ / RLS モデル / スキーマ等）の情報開示を避けるため公開デプロイしない。

主: ローカル閲覧（mkdocs serve）

.venv は リポジトリ外またはリポジトリ内でも .gitignore 済みの場所に作り、コミットに混入させない。

python3 -m venv .venv           # 仮想環境を作成（.gitignore 済み・またはリポジトリ外に作る）
source .venv/bin/activate
pip install -r docs/requirements.txt
mkdocs serve                    # → http://127.0.0.1:8000
  • mkdocs serve はファイル変更を監視してライブリロードする。
  • ワンショットで健全性だけ確認するなら mkdocs build --strict（CI と同じ・壊れたリンク / Mermaid 設定 warning を失敗扱い）。

補助として、private リポジトリの GitHub 上で docs/**.md を直接閲覧してもよい（Mermaid は github.com 上でレンダリングされる）。

将来: GitHub Enterprise の Private Pages（骨子）

GitHub Enterprise へ移行後、アクセス制御付きの Private Pages で社内公開する。手順の骨子:

  1. プラン移行: リポジトリ（または Organization）を GitHub Enterprise プランにする（Private Pages は Enterprise 限定機能）。
  2. Pages を Private/内部公開に設定: repo Settings > Pages で公開範囲を Private（Enterprise メンバー限定） に設定し、ソースを GitHub Actions にする。
  3. docs.yml にデプロイジョブを追加: 既存の build ジョブに続けて GitHub Pages デプロイを足す。骨子:
  4. permissions: に pages: write と id-token: write を追加（現状は contents: read のみ）。
  5. build ジョブで actions/upload-pages-artifact（path: site）を実行して mkdocs の出力をアーティファクト化。
  6. デプロイジョブ（environment: github-pages）で actions/deploy-pages を実行。
  7. デプロイは push（main）限定にし、PR では build 検証のみを維持する（現行の PR=build のみ の性質を壊さない）。
  8. アクセス検証: 未認証ブラウザで Pages URL を開き、Enterprise ログインにリダイレクトされ露出しないことを確認してから運用に乗せる。

不干渉の保証

  • トリガー分離: docs.yml の paths は docs/** / mkdocs.yml / docs.yml のみ。apps/** では起動しない。
  • 既存の CI / デプロイ（ci.yml / deploy-api.yml / supabase-deploy.yml 等）とはトリガーもジョブも独立しており干渉しない。

公開範囲の注意

mkdocs.yml の exclude_docs（superpowers/ ・ *.sql ・ requirements.txt）と nav により、 内部作業ドキュメント・テスト SQL はサイトに含まれない。新規に機微情報を docs/ に置く場合は nav / exclude_docs を確認し、最小公開を保つこと（将来 Private Pages 化する際も同じ）。