การกำหนดค่า Astro

ที่เก็บเนื้อหาไม่ได้จัดการ astro.config.mjs ของตัวเอง แต่จะนำเข้า configuration factory จากแพ็กเกจ npm ชื่อ @f5-sales-demo/docs-theme ซึ่งคืนค่าการกำหนดค่า Astro ที่สมบูรณ์พร้อม Starlight, ปลั๊กอินในตัวแปดรายการ และค่าเริ่มต้นของธีมทั้งหมด

การใช้งานธีม

astro.config.mjs ของที่เก็บเนื้อหา (จัดเตรียมโดย Docker builder) เป็นเพียง wrapper บางๆ:

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

export default createF5xcDocsConfig();

การปรับแต่งทั้งหมดทำผ่าน options object หรือตัวแปรสภาพแวดล้อม — ไม่จำเป็นต้องแก้ไขการเชื่อมต่อปลั๊กอิน, การนำเข้า CSS, หรือการแทนที่ส่วนประกอบ

ตัวเลือกการกำหนดค่า

createF5xcDocsConfig รับ object ชนิด 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 };
}

ตัวเลือก	ค่าเริ่มต้น / ค่าสำรองจากตัวแปรสภาพแวดล้อม	วัตถุประสงค์
`site`	`DOCS_SITE` หรือ `https://f5-sales-demo.github.io`	URL ฐานตามมาตรฐาน
`base`	`DOCS_BASE` หรือ `/`	URL base path สำหรับ project sites
`title`	`DOCS_TITLE` หรือ `Documentation`	ชื่อไซต์ในส่วนหัวและแถบเบราว์เซอร์
`description`	`DOCS_DESCRIPTION` หรือสตริงว่าง	คำอธิบายไซต์สำหรับ metadata และ llms.txt
`githubRepository`	`GITHUB_REPOSITORY` หรือสตริงว่าง	เปิดใช้งานลิงก์แก้ไขและไอคอน GitHub social
`llmsOptionalLinks`	`LLMS_OPTIONAL_LINKS` (JSON) หรือ `[]`	ลิงก์เพิ่มเติมสำหรับปลั๊กอิน llms.txt
`additionalIntegrations`	`[]`	Astro integrations เพิ่มเติมที่จะต่อท้าย
`additionalRemarkPlugins`	`[]`	remark plugins เพิ่มเติมที่เพิ่มหลังจาก remark-mermaid
`megaMenuItems`	เมนู Products/Solutions/Docs/Support ในตัว	รายการเมนูหลักระดับบนสุด
`head`	Mermaid CDN `<script>` tag	รายการ `<head>` แบบกำหนดเอง
`logo`	`@f5-sales-demo/docs-theme/assets/github-avatar.png`	โลโก้ sidebar (src เดียวหรือคู่ light/dark)

ปลั๊กอิน Starlight ในตัว

factory เชื่อมต่อปลั๊กอิน Starlight แปดรายการโดยอัตโนมัติ:

ปลั๊กอิน	วัตถุประสงค์
`starlight-mega-menu`	เมนูนำทางหลักแบบ mega menu ที่มีเลย์เอาต์แบบตารางและรายการ
`starlight-videos`	ฝังวิดีโอในหน้าเอกสาร
`starlight-image-zoom`	คลิกเพื่อขยายภาพ
`@f5-sales-demo/docs-theme` (ตัวเอง)	การฉีด CSS, การแทนที่ส่วนประกอบ, route middleware
`starlight-scroll-to-top`	ปุ่มเลื่อนกลับด้านบนพร้อม progress ring
`starlight-heading-badges`	คำอธิบาย badge บนหัวข้อ
`starlight-page-actions`	ปุ่มการดำเนินการในหน้า
`starlight-plugin-icons`	รองรับไอคอนใน Starlight
`starlight-llms-txt`	สร้าง `llms.txt` และ `llms-full.txt` สำหรับการใช้งานของ LLM

ปลั๊กอินเหล่านี้ถูกลงทะเบียนตามลำดับใน config.ts ปลั๊กอินธีม (@f5-sales-demo/docs-theme) เป็น Starlight plugin ที่ทำงานอยู่ในรายการนี้ด้วย

Theme Plugin Hook

ปลั๊กอินธีมถูกกำหนดใน index.ts และลงทะเบียนในบรรดาปลั๊กอินในตัวข้างต้น hook ชื่อ config:setup ทำสามสิ่ง:

ฉีด CSS — เพิ่ม fonts/font-face.css และ styles/custom.css ไว้ข้างหน้าใน array customCss ของ Starlight
แทนที่ส่วนประกอบ — แทนที่ส่วนประกอบ Starlight ห้ารายการ:
- Banner — การนำทางด้วย breadcrumb พร้อมลิงก์แก้ไข
- EditLink — เว้นว่างโดยตั้งใจ (ลิงก์แก้ไขอยู่ใน Banner)
- Footer — ลิงก์สื่อสังคมออนไลน์ต่อท้ายด้านล่าง footer ค่าเริ่มต้น
- SiteTitle — โลโก้พร้อมลิงก์หน้าหลัก
- MarkdownContent — wrapper ที่เปิดใช้งานวิดีโอและการขยายภาพ
เพิ่ม route middleware — ลงทะเบียน route-middleware.ts ซึ่งกรองหน้าดัชนีออกจาก sidebar และซ่อนสารบัญในหน้าดัชนี

// 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 package specifiers (เช่น @f5-sales-demo/docs-theme/styles/custom.css) ซึ่ง resolve ผ่าน exports map ใน package.json

Integrations อื่นๆ

นอกจาก Starlight และปลั๊กอินของมัน factory ยังลงทะเบียน:

@astrojs/react — เปิดใช้งานการรองรับ React component ในหน้า MDX
remark-mermaid — remark plugin แบบกำหนดเองที่แปลงบล็อกโค้ด ```mermaid ให้เป็นไดอะแกรมที่เรนเดอร์แล้ว

Integrations เพิ่มเติมและ remark plugins สามารถต่อท้ายได้ผ่านตัวเลือก additionalIntegrations และ additionalRemarkPlugins

ไม่มีการกำหนด sidebar แบบกำหนดเอง Starlight สร้าง sidebar โดยอัตโนมัติจากโครงสร้างไฟล์ใน docs/ โดยใช้ frontmatter title ของแต่ละหน้าเป็นข้อความลิงก์ และ sidebar.order สำหรับการเรียงลำดับ route middleware จะกรองหน้าดัชนีออกจาก sidebar โดยอัตโนมัติ