ドキュメントの仕組みとコントリビューション

ドキュメントの仕組みとコントリビューション

当サイト（github-docs）は、ALNEAS エコシステム（eaos-workspace, tools, web-framework）の技術ドキュメント、API仕様、アーキテクチャ解説を集約する単一窓口ポータルです。

全体のアーキテクチャ

flowchart TD
    subgraph Upstream["各プロジェクト (所有元リポジトリ)"]
        SRC["TypeScript ソースコード<br/>(英語 JSDoc)"]
        GUIDES["Markdown ガイド<br/>(docs/**/*.md)"]
        MANIFEST["docs.manifest.json"]
    end

    subgraph Pipeline["取り込み・生成・翻訳パイプライン"]
        INGEST["scripts/ingest.ts<br/>(マニフェスト取り込み & リンク自動変換)"]
        DOCGEN["scripts/docgen.ts<br/>(Swagger風カード型生成)"]
        TRANSLATE["scripts/translate.ts<br/>(AI CLI: agy / codex / claude)"]
        DICT["src/data/translations/api-ja.json"]
    end

    subgraph PublicSite["Cloudflare Pages (グローバルエッジ)"]
        EN["英語ルート (/docs)"]
        JA["日本語ミラー (/ja/docs)"]
        EDGE["エッジキャッシュ & 301 リダイレクト"]
    end

    GUIDES --> MANIFEST --> INGEST --> EN
    SRC --> DOCGEN --> EN
    DOCGEN --> DICT --> TRANSLATE --> JA
    EN --> EDGE
    JA --> EDGE

---

コア設計原則

1. 正本（SSOT）は各プロジェクトに保持

• 自動生成されたファイルを直接手編集してはなりません。
• 各プロジェクトが正本（技術ガイド・コード）を所有し、当リポジトリへは一方向で同期されます。

2. Diátaxis フレームワーク準拠

すべてのページは目的別に厳格に4分類されます：

• Tutorials（チュートリアル）: 0から10分で動く一本道の手順。
• How-To Guides（ハウツー手順）: 特定の課題を解決するレシピ。
• Reference（リファレンス）: Swagger/カード形式による厳密なAPI仕様。
• Explanation（設計解説）: アーキテクチャの背景とトレードオフ。

3. 日本語・英語の安全なパリティ（Graceful Fallback）

• 英語ファースト: 外部コントリビューターは英語のみでPRを提出できます。
• ビルドエラーゼロ: 日本語訳が存在しない場合でも、英語原文を代替表示してビルド・公開を継続します。
• AI CLI 連携: メンテナーがローカルで bun run translate（agy, codex, claude）を実行することで、未翻訳ページやAPIを一括で日本語化できます。

---

デプロイアーキテクチャ: Cloudflare Pages Git 直接連携

本ドキュメントポータルは、Private GitHub リポジトリ（dataarthub/docs）と Cloudflare Pages の Git 連携機能 を直接接続して運用されています。

1. main ブランチへのコミットによる自動ビルド

• main ブランチへコミット（プッシュ）されると、Cloudflare のグローバルエッジ上で即座に自動ビルドが開始されます。
• Build Command: bun install && bun run build
• Build Output Directory: dist
• Node ランタイム: .node-version により Node 24 を指定。
• 外部の GitHub Actions ワークフローを完全排除しているため、CI利用枠の消費やトークン漏洩リスクがありません。

2. 公開用と社内用の「2プロジェクト同時デプロイ」構成

単一の Private リポジトリから、Cloudflare Pages 上で 2つの異なる Pages プロジェクト を運用しています：

プロジェクト	URL / ドメイン	ビルド設定	セキュリティとアクセス制限
公開用ポータル	https://docs-d1x.pages.dev	bun install && bun run build (環境変数 INTERNAL なし)	完全パブリック公開 静的配信のため無制限無料。社内専用の手順書・機密情報は静的HTML生成の段階で物理的に除外されます。
社内用ポータル	https://internal.alneas.org (または社内Pages URL)	bun install && bun run build 環境変数: INTERNAL=true	Cloudflare Access (Zero Trust) 認証 公開ドキュメントに加えて、社内運用手順書（/internal/*）を内包した完全版スーパーセット。社内Google/SSO認証で保護。

---

新規プロジェクトの接続方法

新しいパッケージやプロジェクトを当ドキュメントサイトに登録するには、リポジトリルートに docs.manifest.json を配置します：

{
  "$schema": "https://alneas.github.io/schemas/docs-manifest.v1.json",
  "projectId": "my-project",
  "displayName": "My New Project",
  "documents": [
    {
      "title": "Getting Started",
      "slug": "getting-started",
      "source": "docs/getting-started.md",
      "sourceJa": "docs/getting-started.ja.md",
      "archetype": "how-to"
    }
  ]
}

プッシュ前にローカルで検証：

bun --cwd ../github-docs ingest --verify --project=./docs.manifest.json