منصّة هذه الوثائق¶

كيف بُني هذا الموقع نفسه وكيف يعمل. إضافة صفحة وترجمتها ونشرها — كل ذلك هنا.

التقنية¶

المكوّن	الخيار
المحرّك	MkDocs
السمة	Material for MkDocs
التعدّد اللغوي	`mkdocs-static-i18n`
المخطّطات	‏Mermaid (مدمج في Material)
الناتج	‏HTML ساكن — بلا زمن تشغيل

وهي الحزمة نفسها المستعملة في وثائق بقيّة مستودعات المنظومة، ممّا يُسهّل نقل صفحة أو نسخ إعداد من مستودع إلى آخر.

بنية المستودع¶

docs-gerege-mn/
├── mkdocs.yml              # Site configuration, nav, i18n
├── requirements.txt        # mkdocs-material, mkdocs-static-i18n
├── docs/                   # ← The published content
│   ├── index.md
│   ├── assets/logo.webp
│   ├── stylesheets/brand.css
│   ├── ecosystem/
│   ├── platforms/
│   ├── standards/
│   └── operations/
├── deploy/                 # Deployment tooling (NOT part of the site)
│   ├── README.md           # The host runbook
│   ├── deploy.sh
│   ├── docker-compose.yml
│   ├── nginx-site.conf
│   └── edge/
│       └── docs.gerege.mn.conf
└── .github/workflows/
    ├── ci.yml
    └── deploy.yml

كل ما يدخل docs/ يصير علنيًا

الموقع مفتوح على الإنترنت. فعناوين الخوادم وبيانات الاعتماد وسجلّات المخاطر الداخلية يجب ألّا توضع داخل docs/ أبدًا. ومكان هذه المواد هو deploy/ (داخل المستودع الخاص، وخارج الموقع).

التشغيل محليًا¶

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

# خادم التطوير — تظهر التغييرات فورًا
.venv/bin/mkdocs serve

# بناء الإنتاج (strict — التحذيرات تصير أخطاءً)
.venv/bin/mkdocs build --clean --strict

ويعمل mkdocs serve على http://127.0.0.1:8000.

إضافة صفحة¶

أنشئ الملف — ملف .md في المجلّد المناسب (مثل docs/platforms/new.md).
سجّله في nav — أضفه إلى قائمة nav في mkdocs.yml.
ترجمات القائمة — إن أضفت عنوان قائمة جديدًا فأدرجه في nav_translations للغات الست جميعًا (en · ar · zh · fr · ru · es).
افحص ببناء صارم — mkdocs build --strict.

لماذا نحتاج الوضع الصارم؟

يحوّل --strict التحذيراتِ إلى أخطاء: الروابط الداخلية المكسورة، والملفات المذكورة في nav وغير الموجودة، والملفات الموجودة وغير المدرَجة في nav. والتكامل المستمر يعمل بالوضع نفسه، فالفحص محليًا يقي من سقوط طلب الدمج.

إضافة ترجمة¶

يُقدَّم الموقع بالمنغولية إضافةً إلى اللغات الرسمية الست للأمم المتحدة، ويستعمل بنية اللاحقة: page.md (بالمنغولية) وإلى جانبها نسخٌ تحمل رمز اللغة:

docs/platforms/sso.md      ← Монгол (source)
docs/platforms/sso.ar.md   ← العربية
docs/platforms/sso.zh.md   ← 中文
docs/platforms/sso.en.md   ← English
docs/platforms/sso.fr.md   ← Français
docs/platforms/sso.ru.md   ← Русский
docs/platforms/sso.es.md   ← Español

وعند إضافة صفحة:

اكتب الأصل المنغولي وثبّته ببناء صارم.
أضف الترجمات الست معًا — فالعمل المجزّأ يجعل المحتوى يتباعد.
أضف عنوان القائمة إلى nav_translations في mkdocs.yml للغات الست جميعًا.

وبفضل fallback_to_default: true يبقى الموقع كاملًا حتى مع نقص الترجمات؛ إذ تعرض الصفحة الأصلَ المنغولي بدل خطأ 404.

للتفاصيل راجع التعدّد اللغوي.

السمة والعلامة التجارية¶

الألوان مجمَّعة في كتلة واحدة داخل docs/stylesheets/brand.css:

:root {
  --grg-blue:       #004eb6;  /* header / deep cobalt */
  --grg-blue-2:     #0064e1;  /* brand */
  --grg-blue-deep:  #003a8a;
  --grg-blue-light: #3990ff;  /* links in dark mode */
  --grg-gold:       #e4b24a;  /* ONLY for emphasis / marks of trust */
}

لا تُضف قيم hex جديدة خارج هذه الكتلة. فالذهبي ليس لونًا للعلامة التجارية، وإنّما هو للتمييز وعلامات الثقة فقط.

شارات الحالة¶

<span class="grg-badge grg-badge--live">Production</span>
<span class="grg-badge grg-badge--wip">جزئي</span>
<span class="grg-badge grg-badge--plan">مخطَّط</span>

بنية النشر¶

Internet → edge nginx (gerege-nginx)
              │  docs.gerege.mn vhost
              ▼
       docs-gerege-web  (nginx:alpine container)
              │  shared `gerege` Docker network
              ▼
       <deploy path>/site  (the built static HTML)

ويُحدَّث الموقع في موضعه بـ rsync؛ إذ إنّ استبدال المجلّد بأكمله يترك الحاوية ناظرةً إلى الـ inode القديم، فلا يظهر المحتوى الجديد أبدًا.

لماذا حاوية مستقلّة؟ لأنّ إضافة نقطة ربط جديدة إلى حاوية edge nginx تستلزم إعادة إنشائها، وعندها تسقط جميع النطاقات لبرهة. أمّا تقديم الموقع الساكن من حاويته الصغيرة الخاصة فيجعل الحافّة تكتفي بـإضافةٍ في الإعداد ثم إعادة تحميل.

ملكية الإعداد¶

يملك هذا الموقع مضيفه الافتراضي الخاص على الحافّة — deploy/edge/docs.gerege.mn.conf. وفي كل نشرة يُثبَّت ذلك الملف في conf.d الخاص بـ edge nginx، ويُفحَص بـ nginx -t، ثم يُطبَّق بإعادة تحميل. وقد انتقلت Developer Portal وTemplate Platform إلى النموذج نفسه؛ أمّا sso وdan وgsign وxyp فما تزال تُخدَم من الملف المركزي.

والنتيجة أنّ أي تغيير في docs.gerege.mn ينتهي داخل هذا المستودع — بلا طلب دمج في مستودع آخر وبلا انتظار نشرِ فريقٍ آخر.

ولكي يكون مستقلًّا تمامًا، للمضيف الافتراضي نطاقُ تحديد معدّل خاص به وكتلةُ منفذ 80 خاصة (ACME + إعادة توجيه) — فلا يعتمد على نطاق أو خادم افتراضي مُعرَّف في ملف آخر.

المبدأ العام

الإعداد الذي يخصّ خدمةً واحدة مكانه مستودع تلك الخدمة. أمّا وضعه في ملف مركزي فيجعل كل تغيير مرتبطًا بنشر فريقٍ آخر، وتصير الملكية غائمة.

ولمعرفة كيف جرى الانتقال إلى هذا النموذج ولماذا اتُّخذ كل قرار، راجع سجل الأعمال.

النشر¶

يجري النشر تلقائيًا عبر التكامل المستمر عند الدفع إلى main:

بناء MkDocs بوضع --strict،
نسخ أرشيف site/ إلى الخادم،
تحديثه في موضعه بـ rsync،
تحديث الحاوية،
تثبيت المضيف الافتراضي للحافّة ← nginx -t ← إعادة تحميل،
فحص الموقع الحيّ.

وإن سقط nginx -t أُعيد الإعدادُ السابق ولم تُنفَّذ إعادة التحميل — فيواصل nginx العامل عملَه بآخر إعدادٍ سليم لديه.

وإن لزم نشرٌ يدوي فثمّة النص البرمجي deploy/deploy.sh — ولتفاصيل المضيف راجع دليل التشغيل المغلق deploy/README.md.

المساهمة¶

أنشئ فرعًا (docs/<الموضوع> أو feat/<الموضوع>).
أجرِ تعديلك وشغّل mkdocs build --strict محليًا.
افتح طلب دمج — وسيشغّل التكاملُ المستمر البناءَ الصارم.
وبعد الدمج يُنشَر تلقائيًا.

أسلوب الكتابة¶

اكتب النص الأصلي بالمنغولية.
ليَقُل العنوان مباشرةً موضوع الصفحة؛ فالمحدَّد خيرٌ من «نظرة عامة» أو «مقدّمة».
دوّن سبب القرار لا ما فُعل فحسب. فـ«لماذا» هي المعلومة الأبطأ تقادمًا.
ضع المخاطر والتنبيهات في كتلة !!! warning.
الجدول خيرٌ من القائمة الطويلة.