البنية المعمارية

نظرة عامة

منشئ التوثيق هو نظام مُحتوى في حاويات يعتمد على Astro + Starlight. توفر مستودعات المحتوى ملفات Markdown/MDX؛ بينما يوفر المنشئ الإطار والسمة ومنطق البناء. يلتقي النصفان في وقت البناء داخل حاوية Docker.

نموذج حقن المحتوى

تحتفظ مستودعات المحتوى بتوثيقها في مجلد docs/. في وقت البناء، تنسخ الحاوية تلك الملفات إلى src/content/docs/، حيث تلتقطها مجموعة محتوى Astro.

content-repo/
  docs/           ← يؤلفها فرق المحتوى
    index.mdx
    guide.mdx

docs-builder/
  src/content/docs/ ← فارغ في حالة السكون (.gitkeep)

يقوم سكريبت نقطة الدخول (docker/entrypoint.sh) بتنفيذ النسخ:

cp -r "$CONTENT_DIR"/* /app/src/content/docs/

هذا يعني أن مستودع المنشئ نفسه يُشحن مع مجلد src/content/docs/ فارغ. يظهر المحتوى فقط في وقت البناء.

نظام السمات

تُنشر سمة Starlight كحزمة npm منفصلة. يستخدم package.json اسمًا مستعارًا في npm لربط اسم مختصر بحزمة السجل المُحدد النطاق:

"@f5-sales-demo/docs-theme": "^1.29.0"

تمتلك حزمة السمة ملف astro.config.mjs. في وقت البناء، ينسخه سكريبت نقطة الدخول إلى جذر المشروع:

cp /app/node_modules/@f5-sales-demo/docs-theme/astro.config.mjs /app/astro.config.mjs

هذا يحافظ على مركزية التكوين — لا تحتفظ مستودعات المحتوى ولا المنشئ نفسه بتكوين Astro خاص بها.

هيكل مجلد المصدر

src/
  components/
    PlaceholderForm.tsx          # نموذج React لتحرير قيم العناصر النائبة
    PlaceholderFormWrapper.astro # غلاف Astro، يحمّل سكريبت DOM وCSS العام
  content/
    docs/                        # نقطة التحميل للمحتوى المحقون
  content.config.ts              # تعريف مجموعة محتوى Starlight
  data/
    placeholders.json            # تعريفات رموز العناصر النائبة
  lib/
    placeholder-store.ts         # إدارة الحالة: تحميل، حفظ، حساب، إصدار
  scripts/
    placeholder-dom.ts           # متجول DOM على جانب العميل ومُصيّر Mermaid

مجموعة المحتوى

يُعرّف src/content.config.ts مجموعة docs واحدة باستخدام مُحمّل ومخطط Starlight:

import { defineCollection } from 'astro:content';
import { docsLoader } from '@astrojs/starlight/loaders';
import { docsSchema } from '@astrojs/starlight/schema';

export const collections = {
  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
};

أي ملف .md أو .mdx يُوضع في src/content/docs/ يصبح صفحة في الموقع المبني.

تدفق البناء

يوضح المخطط التالي خط أنابيب البناء من البداية إلى النهاية عند تشغيل حاوية Docker:

flowchart LR
    A[Content Repo<br/>docs/] -->|mount| B[Container<br/>/content/docs]
    B -->|entrypoint.sh<br/>cp| C[src/content/docs/]
    D[npm registry] -->|npm install| E[node_modules/<br/>@f5-sales-demo/docs-theme]
    E -->|cp astro.config| F[astro.config.mjs]
    C --> G[astro build]
    F --> G
    G --> H[dist/<br/>static HTML]
    H -->|cp| I[/output]

المعالجة في وقت البناء مقابل وقت العميل

الشاغل	متى	كيف
MDX → HTML	وقت البناء	مُترجم Astro
كتل كود Mermaid → عناصر div حاوية	وقت البناء	إضافة remark-mermaid.mjs (من docs-theme)
رموز العناصر النائبة → عناصر span تفاعلية	وقت العميل	متجول TreeWalker في placeholder-dom.ts
تصيير SVG لـ Mermaid	وقت العميل	استيراد mermaid عبر CDN في placeholder-dom.ts
حالة نموذج العناصر النائبة	وقت العميل	placeholder-store.ts + localStorage
انتقالات صفحات Astro	وقت العميل	مستمع حدث astro:page-load