ビルドパイプライン

このページでは、コンテンツリポジトリが @f5-sales-demo/docs-theme npm パッケージを利用して、完全にブランド化されたドキュメントサイトを生成する方法について説明します。

アーキテクチャ

┌─────────────────┐
│  Content Repo   │
│  (docs/ folder) │
└────────┬────────┘
         │
         ▼
┌───────────────────────────┐
│   f5xc-docs-builder       │
│   (Docker image)          │
│                           │
│  npm install              │
│  @f5-sales-demo/docs-theme ─────┐  │
│                        ▼  │
│  node_modules/            │
│    @f5-sales-demo/docs-theme/       │
│      ├── config.ts        │
│      ├── index.ts         │
│      ├── fonts/           │
│      ├── styles/          │
│      ├── assets/          │
│      └── components/      │
│                           │
│  Astro Build              │
└─────────────┬─────────────┘
              ▼
┌───────────────────────────┐
│   Astro Build Output      │
│   (static HTML/CSS)       │
└─────────────┬─────────────┘
              ▼
┌───────────────────────────┐
│   GitHub Pages            │
└───────────────────────────┘

ビルドプロセスのステップごとの説明

コンテンツリポジトリへのプッシュ — main へのプッシュ（または手動ディスパッチ）により、GitHub Pages デプロイワークフローがトリガーされます
再利用可能ワークフロー — コンテンツリポジトリのワークフローがビルダーを呼び出します:
```
jobs:
  docs:
    uses: f5-sales-demo/docs-control/.github/workflows/github-pages-deploy.yml@main
```
Docker ビルダーの実行 — f5xc-docs-builder Docker イメージには、npm 経由でテーマがあらかじめインストールされています。ビルド時には以下の処理が行われます:
- node_modules/@f5-sales-demo/docs-theme/ から astro.config.mjs と content.config.ts を Astro プロジェクトルートにコピー
- コンテンツリポジトリの docs/ ファイルを src/content/docs/ にコピー
Astro ビルド — Astro は createF5xcDocsConfig() を呼び出す設定ファイルを読み込みます。このファクトリーは、npm パッケージ指定子（例: @f5-sales-demo/docs-theme/styles/custom.css）を通じてすべてのテーマアセットを解決します
デプロイ — ビルドされた静的サイトが GitHub Pages にデプロイされます

コンテンツリポジトリの要件

コンテンツリポジトリに必要なものは以下のみです:

Markdown（.md）または MDX（.mdx）ファイルを含む docs/ ディレクトリ
ビルダーを呼び出す GitHub Actions ワークフロー

最小限のワークフロー

name: GitHub Pages Deploy
on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: true

jobs:
  docs:
    uses: f5-sales-demo/docs-control/.github/workflows/github-pages-deploy.yml@main

これは、このテーマリポジトリ自体が現在ご覧のドキュメントをビルドする際に使用しているワークフローと同じです。

パス解決

テーマ内のすべてのパスは npm パッケージ指定子を使用しており、package.json の exports マップを通じて解決されます:

// CSS — node_modules から解決
'@f5-sales-demo/docs-theme/fonts/font-face.css'
'@f5-sales-demo/docs-theme/styles/custom.css'

// Components — node_modules から解決
'@f5-sales-demo/docs-theme/components/Footer.astro'
'@f5-sales-demo/docs-theme/components/Banner.astro'

// Assets — node_modules から解決
'@f5-sales-demo/docs-theme/assets/github-avatar.png'

ビルドワークスペースには ./theme/ ディレクトリは存在しません。Docker ビルダーはテーマを通常の npm 依存関係としてインストールし、Astro は node_modules を通じてすべての指定子を解決します。

変更の反映

テーマの変更は npm パッケージの更新を通じて反映されます:

@f5-sales-demo/docs-theme の main に変更がマージされます
Docker ビルダーイメージが更新されたパッケージで再ビルドされます
次回いずれかのコンテンツリポジトリのワークフローが実行されると、更新されたビルダーイメージが使用されます
Astro ビルドにより、更新されたフォント、スタイル、ロゴ、コンポーネント、およびプラグインが取り込まれます
コンテンツリポジトリのサイトが新しいテーマでデプロイされます

コンテンツリポジトリは常に Docker イメージにバンドルされた最新のテーマを取得します。これにより、すべてのサイトで視覚的な一貫性が確保されますが、テーマの変更はマージ前に十分なテストが必要です。