اصطلاحات Markdown

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

---

1. النكهةCopy Anchor Link

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

2. تسلسل العناوينCopy Anchor Link

عنوان H1 واحد لكل ملف. وتنزل العناوين اللاحقة تدريجيًا (H2 → H3 → H4) دون تخطّي أي مستوى. العناوين بحالة الجملة؛ لا أحرف كبيرة بالكامل (ALL-CAPS)، ولا حرف كبير في أول كل كلمة (Title Case Across Every Word). يحمل H1 العنوان الرئيسي للمستند. وفي صفحة موقع الوثائق يُعرَض الحقل title في البيانات الأمامية بوصفه H1 ويكون مرساة الصفحة في تنقّل موقع الوثائق، لذا يبدأ متن الصفحة من H2.

3. كتل الشيفرةCopy Anchor Link

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

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

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

يَحُلّ المدقّق link-check مسارات جذر الموقع هذه /docs/... — والصيغة /<locale>/docs/... للغات غير الافتراضية في حزمة اللغات — مقابل مجموعة الصفحات الموجودة على القرص تحت site/content/docs/: يقابل /docs/a/b الملف site/content/docs/a/b.mdx أو فهرس المجلد site/content/docs/a/b/index.mdx، وتقابل صيغة اللغة ما تحت الشجرة الفرعية site/content/docs/<locale>/. والرابط إلى مسار محذوف أو مُعاد تسميته لا يُحَلّ إلى أيٍّ من الملفين، ويُبلَّغ عنه بوصفه مسارًا ميتًا (خطأ 404 يراه المستخدم) بواسطة link-check، وهو مُطابِق استشاري لا يُفشل التشغيل (انظر §6).

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

5. ترويسة التأليفCopy Anchor Link

يحمل كل مُنتَج Markdown (باستثناء ما هو مُعدَّد في src/apothem/schemas/header-exceptions.txt) ترويسة التأليف المرجعية، وهي السطر الوحيد SPDX-License-Identifier: MIT، بصيغة التعليق الخاصة بنوع ملفه وفق ترويسة التأليف: تعليق HTML في ملفات .md وتعليق {/* ... */} في ملفات .mdx. وعند غياب البيانات الأمامية يكون سطر الترويسة هو السطر 1. وعند وجود بيانات أمامية بصيغة YAML تبقى البيانات الأمامية عند البايت 0 ويأتي سطر الترويسة بعد --- الختامية.

6. المدقّقاتCopy Anchor Link

يُشغِّل خطّاف markdownlint في pre-commit المُعرَّف في .pre-commit-config.yaml الأداة markdownlint-cli بسياسة القواعد الموجودة في .markdownlint.json، ويفرض معظم القواعد الواردة في §§1–4. ويُشغِّل سير عمل Markdown Lint الخطّافَ نفسه في CI عند كل دفع إلى main وعند كل طلب سحب يعدّل ملفات Markdown، لذا يفحص CI بالإصدار الذي يثبّته الخطّاف. تُعطِّل السياسة MD013 (طول السطر)، وMD033 (HTML المُضمَّن)، وMD041 (العنوان في السطر الأول). وتُعطِّل أيضًا MD038، لأن اللاحقة المرجعية لتسمية الخيار (Recommended) تحتفظ بمسافتها البادئة داخل مقطع الشيفرة، وMD060، لأنه لا يوجد نمط لأعمدة الجداول يقبل الجداول ذات الخلايا المضغوطة وصفّ الفواصل المتلاصق |---| التي تستخدمها المدوّنة. تفحص MD024 العناوين الشقيقة فقط، لذا تجتاز الفحصَ عناوين Added وChanged وFixed وSecurity التي يكرّرها كل إصدار في CHANGELOG.md. وأسباب كل اختيار مدوَّنة بجانب الخطّاف. يتخطّى الخطّاف أشجار تجهيزات الاختبار tests/fixtures/، وtests/conformity/، وtests/conformity-scenarios/fixtures/، وtests/scripts/inject-header/fixtures/، التي تُحدِّد الاختباراتُ بايتاتِها. ويتخطّى أيضًا plugins/claude-code/، التي يولّدها python scripts/dev/assemble_plugin_tree.py من src/apothem/: إذ تصبح كل خطوة مُرقَّمة من خطوات الأمر ملفًا مستقلًا، فتبدأ القائمة في ملف الخطوة من رقم تلك الخطوة. أما مصادر src/apothem/ فتخضع للفحص، لذا تُصلَح أي نتيجة في محتوى الإضافة هناك ثم يُعاد توليد شجرة الإضافة.

يفحص file-header-grep في src/apothem/conformity/file_header_grep.py القسم §5. ويفحص المدقّق link-check في src/apothem/conformity/link_check.py انضباط حلّ الروابط في §4 — إذ يَحُلّ الروابط النسبية مقابل دليل الملف المصدر، ومسارات الموقع /docs/... (و/<locale>/docs/...) مقابل مجموعة صفحات site/content/docs/، ويُعلِّم كل رابط لا يُحَلّ إلى صفحة على القرص. وكلاهما مُطابِق استشاري يعمل عند كل عملية Write. ويعملان في خطّاف pre-commit المسمّى conformity-corpus-perwrite وفي مهمة corpus-perwrite-gate ضمن سير عمل Conformity في .github/workflows/conformity.yml، وفي الموضعين كليهما يُبلِغان عن النتائج دون إفشال التشغيل. أما الأمر python -m apothem.conformity.gate --all . --strict في مهمة الجودة ضمن CI في .github/workflows/ci.yml فلا يغطّي إلا المدقّقات المستقلّة، لذا لا يُشغِّل أيًّا منهما.