架構

概述

文件建構器是一個容器化的 Astro + Starlight 系統。內容儲存庫提供 Markdown/MDX 檔案；建構器提供框架、主題和建構邏輯。這兩個部分在建構時於 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 別名將簡短名稱對應到作用域 registry 套件：

"@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            # 佔位符 token 定義
  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]

建構時處理 vs 客戶端處理

關注事項	時機	方式
MDX → HTML	建構時	Astro 編譯器
Mermaid 程式碼區塊 → 容器 div	建構時	remark-mermaid.mjs 外掛（來自 docs-theme）
佔位符 token → 互動式 span	客戶端	placeholder-dom.ts TreeWalker
Mermaid SVG 渲染	客戶端	placeholder-dom.ts 中的 mermaid CDN 匯入
佔位符表單狀態	客戶端	placeholder-store.ts + localStorage
Astro 頁面轉場	客戶端	astro:page-load 事件監聽器