跳到內容
Theme

Astro 設定

內容儲存庫不維護自己的 astro.config.mjs。它們從 @f5-sales-demo/docs-theme npm 套件匯入一個設定工廠，該工廠會回傳一個完整的 Astro 設定，其中包含 Starlight、八個內建插件以及所有主題預設值。

使用主題

Section titled “使用主題”

內容儲存庫的 astro.config.mjs（由 Docker 建置器提供）是一個精簡的包裝器：

import { createF5xcDocsConfig } from '@f5-sales-demo/docs-theme/config';


export default createF5xcDocsConfig();

所有自訂設定均透過選項物件或環境變數完成，無需更動插件配線、CSS 匯入或元件覆寫。

設定選項

Section titled “設定選項”

createF5xcDocsConfig 接受一個 F5xcDocsConfigOptions 物件。每個欄位均為選用；環境變數與合理的預設值會填補空缺。

interface F5xcDocsConfigOptions {
  site?: string;
  base?: string;
  title?: string;
  description?: string;
  githubRepository?: string;
  llmsOptionalLinks?: Array<{ title: string; url: string }>;
  additionalIntegrations?: AstroIntegration[];
  additionalRemarkPlugins?: Array<unknown>;
  megaMenuItems?: MegaMenuItem[];
  head?: HeadEntry[];
  logo?: { src: string } | { light: string; dark: string };
}
選項預設值 / 環境變數備援用途
siteDOCS_SITE 或 https://f5-sales-demo.github.io標準基礎 URL
baseDOCS_BASE 或 /專案網站的 URL 基礎路徑
titleDOCS_TITLE 或 Documentation頁首與瀏覽器分頁中的網站標題
descriptionDOCS_DESCRIPTION 或空字串用於元資料與 llms.txt 的網站描述
githubRepositoryGITHUB_REPOSITORY 或空字串啟用編輯連結與 GitHub 社群圖示
llmsOptionalLinksLLMS_OPTIONAL_LINKS（JSON）或 []llms.txt 插件的額外連結
additionalIntegrations[]要附加的額外 Astro 整合
additionalRemarkPlugins[]在 remark-mermaid 之後加入的額外 remark 插件
megaMenuItems內建的產品/解決方案/文件/支援選單頂層巨型選單項目
headMermaid CDN <script> 標籤自訂 <head> 項目
logo@f5-sales-demo/docs-theme/assets/github-avatar.png側邊欄標誌（單一來源或明暗模式配對）

內建 Starlight 插件

Section titled “內建 Starlight 插件”

設定工廠會自動配置八個 Starlight 插件：

插件用途
starlight-mega-menu支援格狀/清單版面的頂部導覽巨型選單
starlight-videos在文件頁面中嵌入影片
starlight-image-zoom點擊圖片以放大
@f5-sales-demo/docs-theme（自身）CSS 注入、元件覆寫、路由中介軟體
starlight-scroll-to-top帶有進度環的返回頂部按鈕
starlight-heading-badges在標題上顯示徽章標註
starlight-page-actions頁面動作按鈕
starlight-plugin-iconsStarlight 中的圖示支援
starlight-llms-txt產生供 LLM 使用的 llms.txt 與 llms-full.txt

這些插件依序在 config.ts 中註冊。主題插件（@f5-sales-demo/docs-theme）本身即為一個 Starlight 插件，並在此清單中執行。

主題插件鉤子

Section titled “主題插件鉤子”

主題插件定義於 index.ts 中，並在上述內建插件中進行註冊。其 config:setup 鉤子執行三件事：

  1. 注入 CSS — 將 fonts/font-face.css 與 styles/custom.css 前置插入 Starlight 的 customCss 陣列
  2. 覆寫元件 — 取代五個 Starlight 元件：
    • Banner — 帶有編輯連結的麵包屑導覽
    • EditLink — 刻意留空（編輯連結位於 Banner 中）
    • Footer — 在預設頁尾下方附加社群媒體連結
    • SiteTitle — 帶有首頁連結的標誌
    • MarkdownContent — 啟用影片與圖片縮放的包裝器
  3. 加入路由中介軟體 — 註冊 route-middleware.ts，用於從側邊欄過濾索引頁面，並在索引頁面上隱藏目錄
// index.ts — Starlight plugin entry point
export default function f5xcDocsTheme(): StarlightPlugin {
  return {
    name: '@f5-sales-demo/docs-theme',
    hooks: {
      'config:setup'({ config, updateConfig, addRouteMiddleware }) {
        addRouteMiddleware({
          entrypoint: '@f5-sales-demo/docs-theme/route-middleware',
          order: 'pre',
        });
        updateConfig({
          customCss: [
            ...(config.customCss ?? []),
            '@f5-sales-demo/docs-theme/fonts/font-face.css',
            '@f5-sales-demo/docs-theme/styles/custom.css',
          ],
          components: {
            ...config.components,
            Banner: '@f5-sales-demo/docs-theme/components/Banner.astro',
            EditLink: '@f5-sales-demo/docs-theme/components/EditLink.astro',
            Footer: '@f5-sales-demo/docs-theme/components/Footer.astro',
            SiteTitle: '@f5-sales-demo/docs-theme/components/SiteTitle.astro',
            MarkdownContent: '@f5-sales-demo/docs-theme/components/MarkdownContent.astro',
          },
        });
      },
    },
  };
}

所有路徑均使用 npm 套件指定符（例如 @f5-sales-demo/docs-theme/styles/custom.css），這些路徑透過 package.json 中的 exports 映射進行解析。

其他整合

Section titled “其他整合”

除了 Starlight 及其插件之外，設定工廠還會註冊：

  • @astrojs/react — 在 MDX 頁面中啟用 React 元件支援
  • remark-mermaid — 自訂 remark 插件，將 ```mermaid 程式碼區塊轉換為已渲染的圖表

額外的整合與 remark 插件可透過 additionalIntegrations 與 additionalRemarkPlugins 選項附加。

側邊欄

Section titled “側邊欄”

未定義自訂側邊欄。Starlight 會自動從 docs/ 的檔案結構產生側邊欄，使用每個頁面的 title frontmatter 作為連結文字，並以 sidebar.order 進行排序。路由中介軟體會自動從側邊欄過濾索引頁面。