アーキテクチャ

概要

ドキュメントビルダーは、コンテナ化された Astro + Starlight システムです。コンテンツリポジトリが Markdown/MDX ファイルを提供し、ビルダーがフレームワーク、テーマ、ビルドロジックを提供します。この2つの要素は、Docker コンテナ内のビルド時に結合されます。

コンテンツ注入モデル

コンテンツリポジトリはドキュメントを docs/ ディレクトリに保持します。ビルド時にコンテナがこれらのファイルを src/content/docs/ にコピーし、Astro のコンテンツコレクションがそれらを取得します。

content-repo/
  docs/           ← コンテンツチームが作成
    index.mdx
    guide.mdx

docs-builder/
  src/content/docs/ ← 通常時は空 (.gitkeep)

エントリーポイントスクリプト（docker/entrypoint.sh）がコピーを実行します：

cp -r "$CONTENT_DIR"/* /app/src/content/docs/

これは、ビルダーリポジトリ自体が空の src/content/docs/ ディレクトリを持っていることを意味します。コンテンツはビルド時にのみ表示されます。

テーマシステム

Starlight テーマは別の npm パッケージとして公開されています。package.json は npm エイリアスを使用して、短い名前をスコープ付きレジストリパッケージにマッピングしています：

"@f5-sales-demo/docs-theme": "^1.29.0"

テーマパッケージは astro.config.mjs を所有しています。ビルド時にエントリーポイントがそれをプロジェクトルートにコピーします：

cp /app/node_modules/@f5-sales-demo/docs-theme/astro.config.mjs /app/astro.config.mjs

これにより設定が一元管理されます — コンテンツリポジトリもビルダー自体も、独自の Astro 設定を管理する必要がありません。

ソースディレクトリ構成

src/
  components/
    PlaceholderForm.tsx          # プレースホルダー値を編集するための React フォーム
    PlaceholderFormWrapper.astro # Astro ラッパー、DOM スクリプトとグローバル CSS を読み込み
  content/
    docs/                        # 注入されたコンテンツのマウントポイント
  content.config.ts              # Starlight コンテンツコレクション定義
  data/
    placeholders.json            # プレースホルダートークン定義
  lib/
    placeholder-store.ts         # 状態管理：読み込み、保存、計算、発行
  scripts/
    placeholder-dom.ts           # クライアントサイド DOM ウォーカーと Mermaid レンダラー

コンテンツコレクション

src/content.config.ts は Starlight のローダーとスキーマを使用して単一の docs コレクションを定義しています：

import { defineCollection } from 'astro:content';
import { docsLoader } from '@astrojs/starlight/loaders';
import { docsSchema } from '@astrojs/starlight/schema';

export const collections = {
  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
};

src/content/docs/ に配置された .md または .mdx ファイルは、ビルドされたサイトのページになります。

ビルドフロー

以下の図は、Docker コンテナが実行される際のエンドツーエンドのビルドパイプラインを示しています：

flowchart LR
    A[Content Repo<br/>docs/] -->|mount| B[Container<br/>/content/docs]
    B -->|entrypoint.sh<br/>cp| C[src/content/docs/]
    D[npm registry] -->|npm install| E[node_modules/<br/>@f5-sales-demo/docs-theme]
    E -->|cp astro.config| F[astro.config.mjs]
    C --> G[astro build]
    F --> G
    G --> H[dist/<br/>static HTML]
    H -->|cp| I[/output]

ビルド時処理とクライアント時処理

対象	タイミング	方法
MDX → HTML	ビルド時	Astro コンパイラ
Mermaid コードブロック → コンテナ div	ビルド時	remark-mermaid.mjs プラグイン（docs-theme から提供）
プレースホルダートークン → インタラクティブ span	クライアント時	placeholder-dom.ts TreeWalker
Mermaid SVG レンダリング	クライアント時	placeholder-dom.ts 内の mermaid CDN インポート
プレースホルダーフォームの状態	クライアント時	placeholder-store.ts + localStorage
Astro ページトランジション	クライアント時	astro:page-load イベントリスナー