قواعد الروابط

الروابط عنصر أساسي لربط المحتوى في Markdown. إتقان الصيغ المختلفة يجعل وثيقتك أكثر ترابطاً وفائدة.

الصياغة الأساسية للروابط

رابط مضمن (Inline)

أنشئ رابطاً بصيغة [نص الرابط](URL):

هذا رابط إلى [Google](https://www.google.com).
زر [GitHub](https://github.com) للاطلاع على المشاريع مفتوحة المصدر.

نتيجة العرض:

هذا رابط إلى Google. زر GitHub للاطلاع على المشاريع مفتوحة المصدر.

رابط بعنوان (Title)

أضف عنواناً بعد URL ليظهر عند تمرير الفأرة:

هذا [رابط بعنوان](https://www.example.com "عنوان الرابط").

نتيجة العرض:

هذا رابط بعنوان.

الروابط المرجعية (Reference)

رابط مرجعي أساسي

افصل تعريف الرابط عن موضع استخدامه:

هذا [رابط مرجعي][1].
وهذا [رابط مرجعي آخر][link-name].

[1]: https://www.example.com
[link-name]: https://www.google.com "بحث Google"

نتيجة العرض:

هذا رابط مرجعي. وهذا رابط مرجعي آخر.

وسم ضمني

يُستخدم نص الرابط نفسه كوسم التعريف:

زر [Google][] لإجراء بحث.
اطلع على مشاريع [GitHub][].

[Google]: https://www.google.com
[GitHub]: https://github.com

نتيجة العرض:

زر Google لإجراء بحث. اطلع على مشاريع GitHub.

الروابط التلقائية

URL تلقائي

اكتب URL ضمن أقواس مثلثة:

<https://www.example.com>
<https://github.com/user/repo>

نتيجة العرض:

https://www.example.comhttps://github.com/user/repo

بريد إلكتروني تلقائي

تواصل معي: <user@example.com>
الدعم الفني: <support@company.com>

نتيجة العرض:

تواصل معي: user@example.com الدعم الفني: support@company.com

روابط داخلية

روابط إلى عناوين (Anchors)

اربط إلى عناوين ضمن نفس الصفحة:

انتقل إلى [الصياغة الأساسية للروابط](#الصياغة-الأساسية-للروابط)
شاهد [أفضل الممارسات](#أفضل-الممارسات)

نتيجة العرض:

انتقل إلى الصياغة الأساسية للروابط شاهد أفضل الممارسات

روابط بمسارات نسبية

اربط إلى ملفات أخرى:

اطلع على [قواعد العناوين](headings.md)
عودة إلى [الصفحة الرئيسية](../index.md)

روابط خاصة

صورة كرابط

لفّ الصورة داخل رابط:

[![نص بديل](image.png)](https://www.example.com)

روابط تنزيل

اربط إلى ملفات للتنزيل:

حمّل [دليل المستخدم](files/manual.pdf)
احصل على [شيفرة المثال](examples/demo.zip)

تنسيق نص الرابط

نص رابط منسّق

هذا [**رابط عريض**](https://www.example.com)
وهذا [*رابط مائل*](https://www.example.com)
وهذا [`رابط بنمط الشيفرة`](https://www.example.com)

نتيجة العرض:

هذا رابط عريض وهذا رابط مائل وهذا رابط بنمط الشيفرة

نص رابط متعدد الأسطر

هذا [نص رابط طويل،
قد يحتاج إلى التفاف أسطر](https://www.example.com)

أخطاء شائعة وحلول

1) أقواس غير متطابقة

❌ خطأ:
[نص الرابط(https://www.example.com)  ← قوس أيمن مفقود

✅ صحيح:
[نص الرابط](https://www.example.com)

2) مشاكل الفراغات

❌ خطأ:
[ نص الرابط ]( https://www.example.com )  ← فراغات غير ضرورية

✅ صحيح:
[نص الرابط](https://www.example.com)

3) ترميز URL

بالنسبة للروابط التي تحتوي محارف خاصة:

❌ قد يسبب مشكلة:
[بحث](https://www.google.com/search?q=markdown)

✅ أكثر أماناً:
[بحث](https://www.google.com/search?q=markdown)
أو استخدم مرجعاً:
[بحث][google-search]

[google-search]: https://www.google.com/search?q=markdown

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

1) استخدم نصاً وصفياً للرابط

✅ مُوصى به: نص وصفي
اطلع على [توثيق صياغة Markdown الرسمي](https://daringfireball.net/projects/markdown/syntax)

❌ غير مُوصى: نص عام
انقر [هنا](https://daringfireball.net/projects/markdown/syntax) لعرض التوثيق

2) الروابط المرجعية للوثائق الطويلة

✅ مُوصى به: استخدم الروابط المرجعية في الوثائق الطويلة
في بحثنا، رجعنا إلى [عمل Smith وآخرين][smith2020]،
[نظرية Jones][jones2019] و[أحدث تقرير صناعي][industry2021].

[smith2020]: https://www.markdownlang.com/smith-2020-paper
[jones2019]: https://www.markdownlang.com/jones-theory
[industry2021]: https://www.markdownlang.com/industry-report-2021

3) حافظ على بساطة URL

✅ مُوصى به: استخدم روابط قصيرة أو نطاقاً مخصصاً
[الصفحة الرئيسية للمشروع](https://myproject.com)

✅ مقبول: استخدم مرجعاً للروابط الطويلة
انظر [تقرير التحليل المفصل][detailed-report]

[detailed-report]: https://company.com/reports/2023/detailed-analysis-q4-performance-metrics

التحقق من الروابط

فحص صلاحية الروابط

تحقق دورياً من الروابط في الوثائق:

<!-- يُفضّل توثيق حالة الروابط بالتعليقات -->
[Active Link](https://www.google.com) <!-- ✓ 2023-01-15 -->
[Deprecated Link](https://old-site.com) <!-- ⚠️ قد لا يعمل -->

أدوات مساعدة

• linkchecker - أداة سطر أوامر لفحص الروابط
• markdown-link-check - فحص الروابط في Markdown عبر Node.js
• ملحق VS Code - فحص فوري أثناء التحرير

مخرجات HTML

تحويل روابط Markdown إلى HTML:

[نص الرابط](https://www.example.com "عنوان")

تتحول إلى:

<a href="https://www.example.com" title="عنوان">نص الرابط</a>

حيل متقدمة

1) روابط شرطية

قرّر ديناميكياً إضافة الرابط بحسب السياق:

في بيئة التطوير، زر [الخادم المحلي](http://localhost:3000)
في بيئة الإنتاج، زر [الخادم العام](https://production.example.com)

2) تجميع الروابط

نظّم الروابط ذات الصلة في مجموعات:

<!-- موارد رسمية -->
[الموقع الرسمي][official]
[التوثيق][docs]
[المدونة][blog]

<!-- موارد المجتمع -->
[مستودع GitHub][github]
[منتدى النقاش][forum]
[مدوّنة المجتمع][community]

[official]: https://www.markdownlang.com
[docs]: https://docs.example.com
[blog]: https://blog.example.com
[github]: https://github.com/example/project
[forum]: https://forum.example.com
[community]: https://community.example.com

3) روابط تعدد اللغات

اعرض الوثائق: [English](README.md) | [العربية](README-ar.md) | [日本語](README-ja.md)

أمثلة عملية

قائمة تنقّل

## تنقّل سريع

**دليل البدء**
- [ما هو Markdown](what-is-markdown.md)
- [تثبيت المحرر](install-editor.md)
- [أول وثيقة](first-document.md)

**مرجع الصياغة**
- [القواعد الأساسية](basic-syntax.md)
- [القواعد الموسعة](extended-syntax.md)
- [أفضل الممارسات](best-practices.md)

**روابط الموارد**
- [الموقع الرسمي](https://daringfireball.net/projects/markdown/)
- [محرر على الإنترنت](https://dillinger.io/)
- [مدقق الصياغة](https://markdownlint.github.io/)

المراجع

## المراجع

يعتمد هذا المستند على المصادر التالية:

1. [Markdown Syntax][markdown-syntax] - John Gruber
2. [CommonMark][commonmark] - معيار Markdown
3. [GitHub Flavored Markdown][gfm] - صياغة GitHub الموسعة
4. [Markdown Guide][markdown-guide] - مورد تعلّم شامل

[markdown-syntax]: https://daringfireball.net/projects/markdown/syntax
[commonmark]: https://commonmark.org/
[gfm]: https://github.github.com/gfm/
[markdown-guide]: https://www.markdownguide.org/

أدوات موصى بها

## أدوات موصى بها

### المحررات
- [Typora](https://typora.io/) - محرر WYSIWYG
- [Mark Text](https://marktext.app/) - مجاني ومفتوح المصدر
- [VS Code](https://code.visualstudio.com/) + ملحقات Markdown

### أدوات على الإنترنت
- [Dillinger](https://dillinger.io/) - محرر على المتصفح
- [StackEdit](https://stackedit.io/) - محرر غني بالميزات
- [Markdown to HTML](https://markdowntohtml.com/) - تحويل الصيغ

### مولدات مواقع ثابتة
- [VitePress](https://vitepress.dev/) - بيئة Vue
- [Docusaurus](https://docusaurus.io/) - بيئة React
- [GitBook](https://gitbook.com/) - منصة توثيق

قواعد ذات صلة

• قواعد الصور - إدراج الصور
• قواعد الاقتباس - نصوص مقتبسة
• قواعد الشيفرة - تنسيق الشيفرة
• روابط تلقائية - ميزات الروابط

تمارين

جرّب إنشاء الأنواع التالية من الروابط:

1. قائمة موارد تحتوي عدة روابط خارجية
2. وثيقة تقنية تستخدم روابط مرجعية
3. مستند طويل مع تنقّل داخلي
4. صفحة تواصل تحتوي روابط بريد وموقع ويب