إعداد Astro

لا تحتفظ مستودعات المحتوى بملف astro.config.mjs الخاص بها. بدلاً من ذلك، تستورد مصنع إعداد من حزمة npm الخاصة بـ @f5-sales-demo/docs-theme والتي تُعيد إعداد Astro كاملاً مع Starlight وثمانية إضافات مجمّعة وجميع الإعدادات الافتراضية للسمة.

استخدام السمة

ملف astro.config.mjs الخاص بمستودع المحتوى (المقدَّم من خلال منشئ Docker) هو غلاف خفيف:

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

export default createF5xcDocsConfig();

يتم إجراء جميع التخصيصات من خلال كائن الخيارات أو متغيرات البيئة — لا حاجة للتعامل مع توصيل الإضافات أو استيراد CSS أو تجاوزات المكونات.

خيارات الإعداد

تقبل 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 };
}

الخيار	الافتراضي / متغير البيئة البديل	الغرض
`site`	`DOCS_SITE` أو `https://f5-sales-demo.github.io`	عنوان URL الأساسي الأصلي
`base`	`DOCS_BASE` أو `/`	مسار URL الأساسي لمواقع المشاريع
`title`	`DOCS_TITLE` أو `Documentation`	عنوان الموقع في الترويسة وتبويب المتصفح
`description`	`DOCS_DESCRIPTION` أو سلسلة فارغة	وصف الموقع للبيانات الوصفية وملف llms.txt
`githubRepository`	`GITHUB_REPOSITORY` أو سلسلة فارغة	يُفعّل روابط التحرير وأيقونة GitHub الاجتماعية
`llmsOptionalLinks`	`LLMS_OPTIONAL_LINKS` (JSON) أو `[]`	روابط إضافية لإضافة llms.txt
`additionalIntegrations`	`[]`	تكاملات Astro إضافية لإلحاقها
`additionalRemarkPlugins`	`[]`	إضافات remark إضافية تُضاف بعد remark-mermaid
`megaMenuItems`	قائمة المنتجات/الحلول/المستندات/الدعم المدمجة	إدخالات القائمة الضخمة من المستوى الأعلى
`head`	وسم `<script>` لـ Mermaid CDN	إدخالات `<head>` مخصصة
`logo`	`@f5-sales-demo/docs-theme/assets/github-avatar.png`	شعار الشريط الجانبي (مصدر واحد أو زوج فاتح/داكن)

إضافات 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-icons`	دعم الأيقونات في Starlight
`starlight-llms-txt`	يُنشئ ملفَّي `llms.txt` و`llms-full.txt` لاستهلاك نماذج اللغة الكبيرة

تُسجَّل هذه الإضافات بالترتيب داخل config.ts. تُعدّ إضافة السمة (@f5-sales-demo/docs-theme) بحد ذاتها إضافة Starlight تعمل ضمن هذه القائمة.

خطاف إضافة السمة

تُعرَّف إضافة السمة في index.ts وتُسجَّل ضمن الإضافات المجمّعة أعلاه. يقوم خطاف config:setup الخاص بها بثلاثة أشياء:

حقن CSS — يُضيف مسبقاً fonts/font-face.css وstyles/custom.css إلى مصفوفة customCss في Starlight
تجاوز المكونات — يستبدل خمسة مكونات من Starlight:
- Banner — التنقل عبر مسار التنقل التفصيلي مع رابط التحرير
- EditLink — فارغ عمداً (يوجد رابط التحرير في Banner)
- Footer — روابط التواصل الاجتماعي مُلحَقة أسفل التذييل الافتراضي
- SiteTitle — الشعار مع رابط الصفحة الرئيسية
- MarkdownContent — غلاف يُفعّل مقاطع الفيديو وتكبير الصور
إضافة وسيط المسارات — يُسجّل 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) التي تُحلَّل من خلال خريطة exports في package.json.

التكاملات الأخرى

بالإضافة إلى Starlight وإضافاته، يُسجّل المصنع أيضاً:

@astrojs/react — يُفعّل دعم مكونات React في صفحات MDX
remark-mermaid — إضافة remark مخصصة تحوّل كتل الأكواد ```mermaid إلى مخططات مُصيَّرة

يمكن إلحاق تكاملات وإضافات remark إضافية عبر خيارَي additionalIntegrations وadditionalRemarkPlugins.

الشريط الجانبي

لا يُعرَّف أي شريط جانبي مخصص. يُنشئ Starlight الشريط الجانبي تلقائياً من هيكل الملفات في docs/، مستخدماً قيمة title في frontmatter لكل صفحة كنص الرابط وsidebar.order للترتيب. يُصفّي وسيط المسارات صفحات الفهرس من الشريط الجانبي تلقائياً.