ไปป์ไลน์การสร้าง

หน้านี้อธิบายวิธีที่ที่เก็บเนื้อหาใช้แพ็กเกจ npm @f5-sales-demo/docs-theme เพื่อสร้างไซต์เอกสารที่มีแบรนด์อย่างสมบูรณ์

สถาปัตยกรรม

┌─────────────────┐
│  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            │
└───────────────────────────┘

กระบวนการสร้างทีละขั้นตอน

1. การ push ไปยัง content repo — การ push ไปยัง main (หรือการเรียกใช้ด้วยตนเอง) จะเรียกใช้งาน GitHub Pages Deploy workflow
2. Reusable workflow — workflow ของ content repo เรียกใช้ builder:

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

3. Docker builder ทำงาน — Docker image f5xc-docs-builder มีธีมที่ติดตั้งล่วงหน้าผ่าน npm แล้ว ในเวลาสร้างจะดำเนินการดังนี้:
   • คัดลอก astro.config.mjs และ content.config.ts จาก node_modules/@f5-sales-demo/docs-theme/ ไปยังรากโปรเจกต์ Astro
   • คัดลอกไฟล์ docs/ ของ content repo ไปยัง src/content/docs/
4. Astro build — Astro อ่านการกำหนดค่าซึ่งเรียก createF5xcDocsConfig() ฟังก์ชัน factory จะแก้ไข asset ของธีมทั้งหมดผ่าน npm package specifiers (เช่น @f5-sales-demo/docs-theme/styles/custom.css)
5. Deploy — ไซต์แบบ static ที่สร้างแล้วจะถูก deploy ไปยัง GitHub Pages

ข้อกำหนดของ Content Repo

ที่เก็บเนื้อหาต้องการเพียง:

• ไดเรกทอรี docs/ ที่มีไฟล์ Markdown (.md) หรือ MDX (.mdx)
• GitHub Actions workflow ที่เรียกใช้ builder

Workflow ขั้นต่ำ

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

นี่คือ workflow เดียวกันกับที่ที่เก็บธีมนี้ใช้เองเพื่อสร้างเอกสารที่คุณกำลังอ่านอยู่

การแก้ไข Path

path ทั้งหมดในธีมใช้ npm package specifiers ซึ่งแก้ไขผ่าน exports map ใน package.json:

// CSS — resolved from node_modules
'@f5-sales-demo/docs-theme/fonts/font-face.css'
'@f5-sales-demo/docs-theme/styles/custom.css'

// Components — resolved from node_modules
'@f5-sales-demo/docs-theme/components/Footer.astro'
'@f5-sales-demo/docs-theme/components/Banner.astro'

// Assets — resolved from node_modules
'@f5-sales-demo/docs-theme/assets/github-avatar.png'

ไม่มีไดเรกทอรี ./theme/ ใน build workspace Docker builder ติดตั้งธีมเป็น npm dependency ปกติและ Astro แก้ไข specifier ทั้งหมดผ่าน node_modules

หมายเหตุ

path ของไฟล์ฟอนต์ภายใน font-face.css ใช้ ./ (เช่น url("./neusaNextProWide-300.woff2")) ซึ่งเป็น relative path กับตัวไฟล์ CSS เอง ดังนั้นจึงแก้ไขไปยังไฟล์อื่นภายในไดเรกทอรี fonts/ โดยไม่คำนึงถึงวิธีการติดตั้งแพ็กเกจ

การแพร่กระจายการเปลี่ยนแปลง

การเปลี่ยนแปลงธีมจะแพร่กระจายผ่านการอัปเดตแพ็กเกจ npm:

1. การเปลี่ยนแปลงถูก merge ไปยัง main ใน @f5-sales-demo/docs-theme
2. Docker builder image ถูกสร้างใหม่พร้อมแพ็กเกจที่อัปเดตแล้ว
3. ครั้งต่อไปที่ workflow ของ content repo ใดก็ตามทำงาน จะใช้ builder image ที่อัปเดตแล้ว
4. Astro build รับฟอนต์ สไตล์ โลโก้ คอมโพเนนต์ และปลั๊กอินที่อัปเดตแล้ว
5. ไซต์ของ content repo จะ deploy พร้อมธีมใหม่

content repo จะได้รับธีมล่าสุดที่รวมอยู่ใน Docker image เสมอ ซึ่งช่วยให้มั่นใจในความสม่ำเสมอทางภาพลักษณ์ในทุกไซต์ แต่หมายความว่าการเปลี่ยนแปลงธีมควรได้รับการทดสอบอย่างรอบคอบก่อน merge