Markdown: صيغة الروابط في Markdown والروابط المرجعية

الروابط هي العمود الفقري للإنترنت — في Markdown، صيغة واحدة تربط مستندك بالعالم بأسره.

1. ما ستتعلمه

• صيغة الروابط المضمنة والروابط المرجعية
• استخدام الروابط النسبية في مشاريع GitHub
• الروابط التلقائية وروابط البريد الإلكتروني
• التنقل داخل المستند بروابط التثبيت
• أفضل ممارسات الروابط وتحسين SEO

2. قصة حقيقية لمهندس توثيق

(1) نقطة الألم: الروابط المعطلة تترك المستخدمين تائهين

إيما هي مهندسة توثيق في شركة SaaS. اكتشفت أن حوالي 15% من الروابط في مستندات المساعدة كانت معطلة — بعضها لأن أسماء الملفات تغيرت، وأخرى لأن المواقع الخارجية انتقلت. أبلغ المستخدمون أن "النقر على الروابط يؤدي إلى صفحات 404". الأسوأ من ذلك، أن بعض الروابط كانت متناثرة عبر عشرات ملفات Markdown، واستغرق إصلاحها أيامًا.

(2) الحل: استخدام الروابط النسبية والروابط المرجعية

وضعت إيما معايير للروابط: جميع الروابط الداخلية تستخدم مسارات نسبية (مستقلة عن النطاق)، والروابط المستخدمة بشكل متكرر تُعرف في قسم مرجعي أسفل كل مستند (تغيير واحد ينطبق في كل مكان). كما كتبت برنامجًا نصيًا لفحص جميع الروابط بشكل دوري للتأكد من صلاحيتها. بعد ثلاثة أشهر، انخفض معدل تعطل الروابط من 15% إلى 0.5%.

3. الروابط المضمنة

الروابط المضمنة هي تنسيق الروابط الأكثر شيوعًا في Markdown، بصيغة بديهية:

[نص العرض](URL)

[زيارة GitHub](https://github.com)

(1) إضافة سمة عنوان

يمكنك إضافة سمة عنوان اختيارية بعد URL (تُعرض عند التمرير):

[Google](https://google.com "زيارة بحث Google")

[��وثيق MDN](https://developer.mozilla.org "توثيق شامل لتقنيات الويب")

▶ مثال: أنواع مختلفة من الروابط الخارجية

- [Google](https://google.com) — محرك بحث
- [GitHub](https://github.com "أكبر منصة استضافة أكواد في العالم") — استضافة الأكواد
- [توثيق MDN](https://developer.mozilla.org) — توثيق تقنيات الويب

(2) ثلاث طرق لتعريف الرو��بط المرجعية

الطريقة 1 (الأكثر شيوعًا، مع أقواس):
[google]: https://google.com

الطريقة 2 (مختصرة بدون أقواس):
Google: https://google.com

الطريقة 3 (معرف رابط ضمني، تطابق تلقائي):
[Google][]
...

[Google]: https://google.com

▶ مثال: استخدام كامل للروابط المرجعية

## موارد موصى بها

لتطوير الويب، راجع [MDN][] و [W3Schools][].
لاستضافة الأكواد، جرب [GitHub][]؛ للأسئلة والأجوبة، زر [Stack Overflow][].

## المراجع

- توثيق CSS في [MDN][] شامل
- [Stack Overflow][] يحتوي على الكثير من أسئلة وأجوبة الواجهة الأمامية

[MDN]: https://developer.mozilla.org/ar/
[W3Schools]: https://www.w3schools.com/
[GitHub]: https://github.com
[Stack Overflow]: https://stackoverflow.com/

5. الروابط النسبية

في مشاريع GitHub أو المستندات المحلية، استخدم المسارات النسبية للربط بملفات أخرى داخل نفس المشروع:

توثيق المشروع:

دليل التثبيت → installation.md
مرجع API �� api/overview.md
الأسئلة الشائعة → faq.md
القسم السابق → chapter-1/intro.md

▶ مثال: بنية الروابط في مشروع GitHub

مشروع رائع

بداية سريعة: راجع docs/installation.md
دليل المساه��ة: راجع CONTRIBUTING.md
المشاريع ذات الصلة: المكتبة الأساسية (packages/core/README.md)
                   أداة CLI (packages/cli/README.md)

6. الروابط التلقائية وروابط البريد الإلكتروني

(1) الروابط التلقائية

غلف عنوان URL أو عنوان بريد إلكترون�� بـ <>، وسيقوم Markdown تلقائيًا بإنشاء رابط:

<https://example.com>
<user@example.com>

(2) تعطيل الروابط التلقائية

في بعض الحالات تريد عرض URL دون جعله قابلاً للنقر — استخدم تنسيق التعليمات البرمجية أو التخطي:

`https://example.com` (يُعرض كتعليمات برمجية، غير قابل للنقر)

أو:

\*\*https://example.com\*\* يعرض URL كنص عادي

▶ مثال: رابط تلقائي مقابل URL نص عادي

رابط تلقائي: <https://www.google.com>
نص عادي (بدون رابط تلقائي): https://www.google.com
رابط مع نص: [زيارة Google](https://www.google.com)

7. روابط التثبيت (التنقل داخل الصفحة)

تتيح روابط التثبيت للمستخدمين النقر للانتقال إلى موقع محدد في نفس الصفحة:

## جدول المحتويات

- [المقدمة](#1-المقدمة)
- [التثبيت](#2-التثبيت)
- [التكوين](#3-التكوين)

---

## 1. المقدمة
...
انتقل إلى [العودة للأعلى](#جدول-المحتويات)

▶ مثال: جدول محتويات بروابط تثبيت

# درس Python

## جدول المحتويات

- [تثبيت Python](#1-تثبيت-python)
- [البرنامج الأول](#2-البرنامج-الأول)
- [الأسئلة الشائعة](#أسئلة-شائعة)

---

## 1. تثبيت Python

...

## 2. البرنامج الأول

...

## ❓ أسئلة شائعة

...

8. مثال كامل: شبكة روابط مستند

# مسار تعلم تطوير الويب

## أساسيات الواجهة الأمامية

| التقنية | التوثيق | الوصف |
|:-----|:-----|:-----|
| HTML | [MDN HTML][mdn-html] | بنية الويب |
| CSS | [MDN CSS][mdn-css] | تنسيق الويب |
| JS | [MDN JS][mdn-js] | التفاعلية |

## مشاريع عملية

راجع [قالب المشروع][repo] لبدء موقعك الإلكتروني الأول.

## محتوى ذو صلة

- راجع [ملاحظات داخلية](notes/frontend-roadmap)
- انضم إلى [منتدى المجتمع][forum]
- اتصل: <author@example.com>

[mdn-html]: https://developer.mozilla.org/ar/docs/Web/HTML
[mdn-css]: https://developer.mozilla.org/ar/docs/Web/CSS
[mdn-js]: https://developer.mozilla.org/ar/docs/Web/JavaScript
[repo]: https://github.com/example/web-starter
[forum]: https://community.example.com

النتيجة المتوقعة: صفحة توثيق منظمة بشكل جيد تجمع بين الروابط المضمنة والروابط المرجعية وروابط الجداول وروابط البريد الإلكتروني في شبكة موارد تعلم كاملة.

❓ أسئلة شائعة

📖 ملخص

• الروابط المضمنة: [نص](url)، الأكثر شيوعًا وبديهية
• الروابط المرجعية: [نص][id] + [id]: url، إدارة مركزية
• الروابط النسبية: استخدم المسارات النسبية داخل نفس المشروع، صديقة للترحيل
• الروابط التلقائية: <url> أو <بريد> تنشئ روابط قابلة للنقر تلقائيًا
• روابط التثبيت: #عنوان ينتقل إلى موق�� محدد في الصفحة
• اجعل نص الرابط وصفيًا لتحسين إمكانية الوصول و SEO

📝 تمارين

1. أساسي: اكتب مقالاً قصيرًا باستخدام الروابط المضمن�� مع 3 مراجع خارجية على الأقل (مثلاً، أوصِ بأكثر 3 أدوات تستخدمها عبر الإنترنت).

2. متوسط: أعد كتابة التمرين أعلاه باستخدام الروابط المرجعية. ثم أنشئ مشروع GitHub قصيرًا واستخدم الروابط النسبي�� لتوجيه المستخدمين من README.md إلى الصفحات الفرعية تحت docs/.

3. متقدم: اكتب مستند "مركز موارد التعلم" الذي يجمع بين الروابط المضمنة والروابط المرجعية (5 على الأقل) وروابط التثبيت للتنقل بجدول المحتويات ورابط بريد إلكتروني تلقائي <user@example.com> في الأسفل.

فريق Web-Tutorial التقني

منصة دروس برمجية يديرها عدة مطورين. كل درس يتم كتابته ومراجعته بواسطة مطورين متخصصين في المجال. نعمل على ضمان دقة وموثوقية المحتوى — إذا لاحظت أي مشكلة، فيرجى إخبارنا.

من نحن