معرفات العناوين

معرفات العناوين هي توسعة في Markdown تسمح بإضافة مُعرِّفات مخصّصة للعناوين لروابط دقيقة وتنظيم هيكل الوثيقة.

القواعد الأساسية

إضافة معرف للعنوان

يُضاف المعرف باستخدام أقواس معقوفة بعد نص العنوان:

## عنواني {#custom-id}

نتيجة العرض:

مخرجات HTML تضيف هذا المعرف إلى عنصر العنوان:

<h2 id="custom-id">عنواني</h2>

معرفات لمستويات متعددة من العناوين

يمكن إضافة معرف مخصص لكل مستوى من العناوين:

# مستوى أول {#first-level}

## مستوى ثانٍ {#second-level}

### مستوى ثالث {#third-level}

#### مستوى رابع {#fourth-level}

سيناريوهات الاستخدام

إنشاء روابط مرساة

بوجود معرف مخصص، يمكنك إنشاء روابط إلى أقسام محددة داخل المستند:

[الانتقال إلى عنواني](#custom-id)

...محتوى آخر...

## عنواني {#custom-id}

نتيجة العرض:

سيأخذ الرابط القارئ مباشرة إلى العنوان ذي custom-id.

ربط خارجي إلى جزء محدد من المستند

المعرفات المخصصة تُسهّل الربط من مستندات خارجية إلى أقسام بعينها:

[رابط إلى قسم محدد في مستند آخر](other-doc.html#specific-section)

مشاركة روابط إلى أقسام محددة

يمكن مشاركة عنوان مرفق بمعرف عبر رابط URL يشير إلى قسم بعينه:

https://www.markdownlang.com/documentation.html#installation-guide

استخدامات متقدمة

معرفات لعناوين متعددة الكلمات

عندما يحتوي العنوان على عدة كلمات، يُفضّل وصلها بشرطة:

## دليل التثبيت والإعداد {#installation-and-configuration}

توليد الفهرس ومعرفات العناوين

تُولّد العديد من معالجات Markdown معرفات تلقائياً من نص العنوان. باستخدام معرفات مخصّصة تبقى روابط الفهرس ثابتة رغم تغيّر النص:

## دليل البدء {#getting-started}

حتى لو غيّرت نص العنوان لاحقاً، سيظل الرابط صالحاً لأن المعرف ثابت.

الدولية والمحارف غير اللاتينية

للعناوين غير الإنجليزية، تكون المعرفات المخصّصة مفيدة لتوفير مُعرِّف لاتيني ثابت:

## تعليمات التثبيت {#installation}

## كيفية الاستخدام {#usage}

## الأسئلة الشائعة {#faq}

التوافق وفروقات التنفيذ

دعم المنصات المختلفة

منصة/أداة	دعم معرف العنوان	الصياغة
GitHub Markdown	✅	{#id}
GitLab Markdown	✅	{#id}
Jekyll（kramdown）	✅	{:#id} 或 {#id}
Hugo	✅	{#id}
CommonMark	❌	不支持
VitePress	✅	{#id}
Pandoc	✅	{#id}

قواعد توليد المعرفات تلقائياً

عند عدم توفير معرف مخصص، تُولّد معظم المعالجات معرفاً تلقائياً من نص العنوان:

1. تحويل إلى أحرف صغيرة
2. حذف/استبدال المحارف الخاصة
3. استبدال الفراغات بشرطات
4. إزالة الشرطات المتتالية
5. ضمان فريدية المعرف (قد يضاف لاحقة رقمية)

على سبيل المثال:

العنوان	المعرّف المتولّد
## Getting Started	#getting-started
## FAQ & Help	#faq-help
## 快速入门	#快速入门 أو #section-1 (يختلف حسب المنصة)

أفضل الممارسات

معايير تسمية معرفات العناوين

✅ ممارسات موصى بها:

1. **استخدم معرفات وصفية موجزة**:
   - `{#installation}`
   - `{#api-reference}`
   - `{#troubleshooting}`

2. **حافظ على نمط تسمية موحّد**:
   - أحرف صغيرة فقط
   - شرطات للفصل بين الكلمات
   - تجنّب underscore أو CamelCase

3. **ثبّت المعرف**:
   - تجنّب تغييره كثيراً
   - أبقه ثابتاً عند تغيير نص العنوان

❌ تجنّب:

1. محارف خاصة (`!@#$%^&*()`)
2. معرفات غير وصفية (`{#section1}`)
3. معرفات طويلة جداً
4. فراغات أو ترقيم داخل المعرّف

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

في المستندات الكبيرة يُنصح بمعرفات معيارية للأقسام لتسهيل التنقل:

# وثائق المنتج {#product-docs}

## المقدمة {#introduction}

## التثبيت {#installation}

### تثبيت Windows {#installation-windows}

### تثبيت macOS {#installation-macos}

### تثبيت Linux {#installation-linux}

## الإعداد {#configuration}

## مرجع API {#api-reference}

## الأسئلة الشائعة {#faq}

أمثلة تطبيقية

معرفات العناوين في الوثائق التقنية

تفيد معرفات العناوين في الوثائق التقنية للربط المباشر إلى أقسام بعينها:

# وثائق API {#api-documentation}

## المصادقة {#authentication}

### الحصول على مفتاح API {#get-api-key}

### مصادقة OAuth {#oauth}

## النهايات {#endpoints}

### نهايات المستخدم {#endpoints-users}

### نهايات المنتج {#endpoints-products}

معرفات العناوين في الأوراق الأكاديمية

في الأوراق الأكاديمية يمكن استخدام المعرفات لصنع اقتباسات وروابط متقاطعة:

# 研究方法 {#methodology}

كما تُظهر [نتائج البحث](#results)، أدّت منهجيتنا جيداً عبر حالات عدة.

...

# 研究结果 {#results}

يعرض هذا القسم نتائج التجارب المذكورة في [منهجية البحث](#methodology).

حلول للمشكلات الشائعة

المعرف لا يعمل

إن لم يعمل معرّف العنوان:

1. 检查平台是否支持自定义标题 ID
2. 确认语法是否正确（通常是 {#id}）
3. 验证 ID 中是否包含无效字符
4. 尝试使用不同的 Markdown 处理器

تعارض في المعرفات

إذا تكرر المعرف نفسه داخل المستند فقد يؤدي لسلوك روابط غير متوقع:

## مشكلة {#issue} <!-- المعرّف الأول -->

...

## مشكلات شائعة {#issue} <!-- مكرر وقد يسبب تعارضاً -->

حل لتجنّب التعارض:

## وصف المشكلة {#issue-description}

...

## مشكلات شائعة {#common-issues}

الفراغات والمحارف الخاصة

تتعامل بعض المعالجات بشكل مختلف مع الفراغات والمحارف الخاصة داخل المعرف:

<!-- قد تكون إشكالية على بعض المنصات -->
## إعدادات متقدمة {#advanced settings}

<!-- أكثر أماناً -->
## إعدادات متقدمة {#advanced-settings}

قواعد ذات صلة

• الروابط - قواعد الروابط الأساسية
• الفهرس - توليد جدول محتويات تلقائي
• الحواشي السفلية - إضافة مراجع وإيضاحات

أدوات وإضافات

توليد فهرس تلقائياً

يمكن لأدوات عديدة توليد فهرس تلقائياً اعتماداً على العناوين ومعرفاتها:

[[toc]]

# الفصل الأول {#chapter-1}

## 1.1 القسم {#section-1-1}

# الفصل الثاني {#chapter-2}

标题 ID 检查工具

• markdownlint: 可配置为检查标题 ID 的一致性
• remark-lint: 提供标题 ID 的检查和自动修复
• markdown-toc: 自动生成带有链接的目录

---

معرفات العناوين أداة مهمة لرفع قابلية الاستخدام والوصولية في وثائق Markdown. باستخدام معرفات معيارية يمكنك إنشاء بنية روابط ثابتة تسهّل التنقل والاقتباس وتجعل الوثيقة أكثر احترافية وسهولة.