خط أنابيب البناء

تصف هذه الصفحة كيفية استهلاك مستودعات المحتوى لحزمة 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. دفع مستودع المحتوى — يؤدي الدفع إلى main (أو التشغيل اليدوي) إلى تشغيل سير عمل نشر GitHub Pages
2. سير العمل القابل لإعادة الاستخدام — يستدعي سير عمل مستودع المحتوى المنشئ:

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

3. تشغيل منشئ Docker — تحتوي صورة Docker الخاصة بـ f5xc-docs-builder مسبقاً على السمة المثبتة عبر npm. في وقت البناء تقوم بما يلي:
   • نسخ astro.config.mjs و content.config.ts من node_modules/@f5-sales-demo/docs-theme/ إلى جذر مشروع Astro
   • نسخ ملفات docs/ الخاصة بمستودع المحتوى إلى src/content/docs/
4. بناء Astro — يقرأ Astro الإعداد الذي يستدعي createF5xcDocsConfig(). يحل المصنع جميع أصول السمة من خلال محددات حزم npm (مثل @f5-sales-demo/docs-theme/styles/custom.css)
5. النشر — يُنشر الموقع الثابت المبني على GitHub Pages

متطلبات مستودع المحتوى

يحتاج مستودع المحتوى فقط إلى:

• دليل docs/ يحتوي على ملفات Markdown (.md) أو MDX (.mdx)
• سير عمل GitHub Actions يستدعي المنشئ

سير العمل الأدنى

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

هذا هو سير العمل نفسه الذي يستخدمه مستودع السمة هذا لبناء التوثيق الذي تقرأه الآن.

حل المسارات

تستخدم جميع المسارات في السمة محددات حزم npm، يتم حلها من خلال خريطة exports في 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/ في مساحة عمل البناء. يثبت منشئ Docker السمة كتبعية npm عادية ويحل Astro جميع المحددات من خلال node_modules.

ملاحظة

تستخدم مسارات ملفات الخطوط داخل font-face.css الرمز ./ (مثل url("./neusaNextProWide-300.woff2")). هذه المسارات نسبية إلى ملف CSS نفسه، لذا فإنها تحل إلى ملفات أخرى داخل دليل fonts/ بغض النظر عن طريقة تثبيت الحزمة.

انتشار التغييرات

تنتشر تغييرات السمة من خلال تحديثات حزمة npm:

1. يُدمج تغيير في main ضمن @f5-sales-demo/docs-theme
2. تُعاد إعادة بناء صورة منشئ Docker مع الحزمة المحدّثة
3. في المرة القادمة التي يعمل فيها سير عمل أي مستودع محتوى، يستخدم صورة المنشئ المحدّثة
4. يلتقط بناء Astro الخطوط والأنماط والشعار والمكونات والملحقات المحدّثة
5. ينتشر موقع مستودع المحتوى بالسمة الجديدة

تحصل مستودعات المحتوى دائماً على أحدث سمة مجمّعة في صورة Docker. يضمن هذا الاتساق البصري عبر جميع المواقع، لكنه يعني أن تغييرات السمة يجب اختبارها بعناية قبل الدمج.