اصطلاحات Markdown

مرجع كنسي لشكل Markdown وتنسيقه عبر كل مُنتَج .md مكتوب. الملخص في CLAUDE.md §4 الاصطلاحات هو الإعلان المُضمَّن؛ وهذه الصفحة هي المرجع المستقل الذي يستشهد به المساهمون في المراحل اللاحقة.

---

1. النكهة

GitHub-Flavored Markdown (GFM) هي نكهة المضيف. يُعرَض كل مُنتَج بشكل صحيح في واجهة الويب لـGitHub، وفي موقع توثيق Fumadocs، وفي المحررات القياسية المُدرِكة لـMarkdown.

2. تسلسل العناوين

عنوان H1 واحد لكل ملف. تنحدر العناوين اللاحقة بشكل رتيب (H2 → H3 → H4) دون تخطّي المستويات. عناوين بحالة الجملة؛ لا حروف كبيرة بالكامل (ALL-CAPS)، ولا Title Case Across Every Word. يحمل H1 العنوان الرئيس للمستند، وهو نفسه مرساة المستند في تنقّل موقع التوثيق.

3. كتل الشيفرة

تُعلِن كتل الشيفرة المُسوَّرة عن لغتها (```python، ```bash، ```yaml، ```json، ```mermaid). الكتل بلا وسم تكبح إبراز الصياغة وتُشير إلى انحراف في الكِتابة؛ تَفرض قاعدة markdownlint MD040 في .markdownlint.jsonc وسمَ اللغة.

4. الروابط الداخلية

تستخدم الإحالات المتقاطعة الداخلية مسارات نسبية إلى جذر الموقع (مثلًا، [Authorship header](/docs/reference/authorship-header)). تُتجنَّب المسارات النسبية العارية للمستودع ذات اللاحقة .md/.mdx (/docs/foo.md) وعناوين URL الكاملة إلى المستودع نفسه (https://github.com/ahmed-g-gad/apothem/blob/main/...) للروابط داخل الموقع، لأنها لا تصمد أمام إعادة تسمية الصفحات وإعادة تنظيم الأقسام.

تُثبَّت الروابط الخارجية إلى المراجع المتغيرة (main، master، latest، HEAD) إلى SHA الالتزامات أو وسوم الإصدارات كلما كان استقرار المحتوى المربوط مهمًّا؛ وتُوثَّق المراجع المتقلبة على هذا النحو بتعليق {/* volatile */} مجاور.

5. لافتة الكِتابة

يحمل كل مُنتَج Markdown (مع الاستثناءات المُعدَّدة في src/apothem/schemas/header-exceptions.txt) لافتة ترويسة الكِتابة الكنسية عند البايت 0، بصيغة تعليق HTML وفق Authorship header. تجلس اللافتة فوق الـfrontmatter بصيغة YAML حيث يوجد كلاهما.

6. المُتحقِّقات

يَفرض استدعاء markdownlint-cli2 في .markdownlint.jsonc معظم قواعد §§1–4. ويَفرض file-header-grep عند src/apothem/conformity/file_header_grep.py القسمَ §5. وكلاهما موصول بسلسلة خطّافات ما قبل الالتزام (pre-commit) في .pre-commit-config.yaml وبمهمة الجودة في CI عند .github/workflows/ci.yml.