يتبع توثيق Obsidian إرشادات الأسلوب المدرجة في هذه الصفحة. تستند هذه الإرشادات إلى أفضل الممارسات في الصناعة، وتحديداً [دليل أسلوب توثيق مطوري Google](https://developers.google.com/style) و[دليل أسلوب Microsoft](https://learn.microsoft.com/en-us/style-guide/). للحالات غير المذكورة أدناه، يمكن الرجوع إلى تلك الأدلة الخارجية كمراجع ثانوية.
> [!tip]- المساهمة
> معظم التوثيق كان موجوداً قبل إنشاء دليل الأسلوب هذا.
>
> إذا وجدت أي مخالفات لدليل الأسلوب هذا، يُرجى [إنشاء مشكلة](https://github.com/obsidianmd/obsidian-docs/issues/new) وتقديم طلب سحب إلى [obsidianmd/obsidian-docs](https://github.com/obsidianmd/obsidian-docs).
## المصطلحات والقواعد اللغوية
### أسلوب اللغة
بالنسبة للتوثيق باللغة الإنجليزية، يُوصى باستخدام [الإنجليزية العالمية](https://docs.openedx.org/en/latest/documentors/references/doc_english_writing.html) لخدمة جمهورنا العالمي بشكل أفضل وللمساعدة في [[#الترجمات]]. وهذا يعني:
- تجنب التعبيرات الاصطلاحية والعبارات الخاصة بثقافة معينة
- استخدام الصيغة المبنية للمعلوم والجمل المباشرة
- تفضيل الكلمات البسيطة والشائعة على المصطلحات المعقدة
- الوضوح بدلاً من الضمنية
- بالنسبة لاتفاقيات الإملاء، استخدم الإنجليزية الأمريكية (مثل 'organize' وليس 'organise').
### المصطلحات
- يُفضّل استخدام "keyboard shortcut" بدلاً من "hotkey". استخدم Hotkey عند الإشارة إلى الميزة المحددة.
- يُفضّل استخدام "تطبيق Obsidian" على الهاتف المحمول، و"تطبيق Obsidian" على سطح المكتب.
- يُفضّل استخدام "sync" أو "syncing" بدلاً من "synchronise" أو "synchronising".
- يُفضّل استخدام "مصطلح البحث" بدلاً من "استعلام البحث".
- يُفضّل استخدام "عنوان" بدلاً من "ترويسة" عند الإشارة إلى نص يقدم قسماً.
- يُفضّل استخدام "maximum" بدلاً من "max" و"minimum" بدلاً من "min".
### أسماء المنتجات
تبدأ أسماء منتجات Obsidian بكلمة "Obsidian"، مثل "Obsidian Publish" و"Obsidian Sync".
إذا أصبحت الفقرة متكررة بشكل مفرط، يمكنك استخدام الصيغة المختصرة في الإشارات اللاحقة.
على سبيل المثال:
_للسماح بالتهيئة الخاصة بالجهاز، لا يقوم Obsidian Sync بمزامنة إعداداته الخاصة. تحتاج إلى تهيئة المزامنة لكل جهاز من أجهزتك._
### واجهة المستخدم والتفاعلات
- استخدم **الخط العريض** للإشارة إلى نص الأزرار
- يُفضّل استخدام "اختر" بدلاً من "انقر" أو "اضغط".
- بالنسبة للتعليمات الخاصة بالهاتف المحمول، يُقبل استخدام "اضغط" عند وصف تفاعلات اللمس حيث أن "النقر" غير متاح.
- يُفضّل استخدام "الشريط الجانبي" بدلاً من "الشريط الجانبي" (بمسافة).
- يُفضّل استخدام "نفّذ" بدلاً من "استدعِ" عند الإشارة إلى الأوامر أو الإجراءات.
عند الإشارة إلى تفاعلات متعددة في واجهة المستخدم بشكل متسلسل، استخدم الرمز → (U+2192). على سبيل المثال، "**[[الإعدادات]] → إضافات المجتمع**".
### الملاحظات والملفات والمجلدات
- استخدم "ملاحظة" عند الإشارة إلى ملف Markdown في الخزنة.
- استخدم "ملف" عند الإشارة إلى امتدادات ملفات أخرى غير Markdown.
- يُفضّل استخدام "اسم الملاحظة" بدلاً من "عنوان الملاحظة".
- يُفضّل استخدام "الملاحظة النشطة" بدلاً من "الملاحظة الحالية".
- يُفضّل استخدام "مجلد" بدلاً من "دليل".
- يُفضّل استخدام "نوع الملف" بدلاً من "تنسيق الملف"، إلا عند الإشارة تحديداً إلى تنسيق بيانات محتوى الملف.
عند التنقل بين الملاحظات، استخدم "افتح" إذا كانت الوجهة مخفية، و"انتقل" إذا كانت كلتا الملاحظتين المصدر والوجهة مفتوحتين في أقسام منفصلة.
### التوثيق المرجعي للإعدادات
عندما يكون ذلك ممكناً، يجب توثيق أي إعدادات داخل Obsidian باستخدام نص وصفي. تجنب توثيق إعداد محدد في مساعدة Obsidian إلا إذا:
- كان يتطلب معرفة أعمق حول كيفية ووقت استخدامه.
- كان يُساء استخدامه أو يُسأل عنه بشكل شائع.
- كان يغير تجربة المستخدم بشكل _جذري_.
فكّر في استخدام مربع تنبيه من نوع نصيحة إذا كنت تريد لفت الانتباه إلى إعداد محدد.
### المصطلحات الاتجاهية
ضع واصلة في المصطلحات الاتجاهية عند استخدامها كصفات. تجنب الواصلة عند استخدام الاتجاه كاسم.
**موصى به:**
- اختر **[[الإعدادات]]** في الزاوية السفلية-اليسرى.
- اختر **[[الإعدادات]]** في أسفل اليسار.
**غير موصى به:**
- اختر **[[الإعدادات]]** في الزاوية السفلية اليسرى.
- اختر **[[الإعدادات]]** في السفلية-اليسرى.
يُفضّل استخدام "العلوية-اليسرى" و"العلوية-اليمنى" بدلاً من "أعلى-اليسار" و"أعلى-اليمين".
لا تُشر إلى اتجاه عند الإشارة إلى الإعدادات. يعتمد موقع عنصر التحكم في الإعدادات على الجهاز.
**موصى به:**
- بجوار **اختر خزنة بعيدة**، اختر **اختيار**.
**غير موصى به:**
- على يمين **اختر خزنة بعيدة**، اختر **اختيار**.
عند وصف الاتجاه العمودي في عناصر واجهة المستخدم، استخدم "أعلى" و"أسفل" للعلاقات المكانية. تجنب "فوق" و"تحت" لأنها قد تكون غامضة في سياقات مختلفة.
**موصى به:**
- يظهر مربع البحث أعلى قائمة الملفات.
- تتوفر خيارات إضافية أدناه.
**غير موصى به:**
- مربع البحث يوجد فوق قائمة الملفات.
- المزيد من الخيارات تحت.
### التعليمات
استخدم صيغة الأمر لأسماء الأدلة وعناوين الأقسام والتعليمات خطوة بخطوة. صيغة الأمر موجزة وموجهة نحو العمل، مما يجعلها أكثر وضوحاً للمستخدمين الذين يتبعون التعليمات.
- يُفضّل "أعدّ" بدلاً من "إعداد"
- يُفضّل "انقل ملفاً" بدلاً من "نقل ملف"
- يُفضّل "استورد ملاحظاتك" بدلاً من "استيراد ملاحظاتك"
### حالة الأحرف في الجمل
يُفضّل *حالة الجملة* على *حالة العنوان* للعناوين والأزرار والعناوين. عند الإشارة إلى عناصر واجهة المستخدم، طابق دائماً حالة الأحرف الموجودة في الواجهة.
**موصى به:**
- كيف يخزن Obsidian البيانات
**غير موصى به:**
- كيف يخزن Obsidian البيانات (بأحرف كبيرة لكل كلمة)
### الأمثلة
يُفضّل استخدام أمثلة واقعية بدلاً من مصطلحات بلا معنى.
**موصى به:**
- `task:(call OR schedule)`
**غير موصى به:**
- `task:(foo OR bar)`
### أسماء المفاتيح واختصارات لوحة المفاتيح
عند الإشارة إلى مفاتيح لوحة المفاتيح والاختصارات، استخدم تنسيقاً متسقاً.
**أسماء المفاتيح الفردية:**
عند الإشارة إلى حرف على لوحة المفاتيح بالاسم، أضف الحرف بين قوسين مباشرة بعد الاسم.
**موصى به:**
- اضغط على مفتاح الواصلة (-) لإضافة شرطة.
- استخدم علامة الاستفهام (؟) للبحث.
**غير موصى به:**
- اضغط على مفتاح الواصلة لإضافة شرطة.
- استخدم ؟ للبحث.
- أضف `-` أمام الكلمة.
**اختصارات لوحة المفاتيح:**
نسّق اختصارات لوحة المفاتيح بدون مسافات حول علامة الجمع. عندما يختلف الاختصار بين أنظمة التشغيل، حدد كليهما.
**موصى به:**
- اضغط `Ctrl+Z` (ويندوز) أو `Command+Z` (ماك) للتراجع.
- اضغط `Escape` لإغلاق هذه النافذة.
- استخدم `Tab` للتنقل بين الحقول.
**غير موصى به:**
- اضغط `Cmd+Z` للتراجع.
- اضغط `Ctrl + Z` (بمسافات) للتراجع.
- اضغط `Ctrl/Cmd+Z` للتراجع.
للاختصارات المتطابقة عبر جميع المنصات، لا تحتاج إلى تحديد نظام التشغيل. إذا لم تكن متأكداً مما إذا كان الاختصار يختلف بين المنصات، حدد نظام التشغيل احتياطياً. عادةً ما يستخدم ويندوز ولينكس نفس الاختصارات.
### Markdown
استخدم أسطراً فارغة بين كتل Markdown:
**موصى به:**
```md
# عنوان 1
هذا قسم.
1. العنصر الأول
2. العنصر الثاني
3. العنصر الثالث
```
**غير موصى به:**
```md
# عنوان 1
هذا قسم.
1. العنصر الأول
2. العنصر الثاني
3. العنصر الثالث
```
**الشرطات الطويلة في القوائم:**
استخدم الشرطات الطويلة (—) لفصل المصطلحات العريضة عن أوصافها في القوائم النقطية. لا تستخدم الشرطات الطويلة في القوائم المتداخلة البسيطة التي تحتوي على روابط.
**موصى به:**
- **قائمة العرض** — إنشاء وتحرير وتبديل العروض.
- **حساب القيم** — إضافة الأسعار وحساب الإجماليات أو إجراء العمليات الحسابية.
**غير موصى به:**
- [[إنشاء قاعدة بيانات]] — تعلم كيفية إنشاء وتضمين قاعدة.
### الصور
استخدم "**العرض** × **الارتفاع** بكسل" لوصف أبعاد الصورة أو الشاشة.
**مثال:**
أبعاد الصورة الموصى بها: 1920 × 1080 بكسل.
## هيكل المعلومات
### أنواع مربعات التنبيه
استخدم مربعات التنبيه بشكل استراتيجي لتسليط الضوء على أنواع محددة من المعلومات:
**نصيحة** (`[!tip]-`) - نصائح عملية أو أفضل الممارسات التي تعزز سير عمل المستخدم. استخدمها للاختصارات أو الحلول البديلة أو المعلومات المفيدة غير الأساسية. تبدأ مربعات التنبيه هذه مطوية.
**معلومة** (`[!info]+`) - سياق إضافي أو معلومات خلفية أو توضيحات. استخدمها عندما تضيف المعلومات فهماً لكنها ليست مطلوبة لإكمال مهمة. تبدأ مربعات التنبيه هذه مفتوحة.
**تحذير** (`[!warning]+`) - تنبيهات مهمة تمنع فقدان البيانات أو الأخطاء أو العواقب غير المقصودة. استخدمها باعتدال للمواقف الخطرة فعلاً. يجب ألا تكون مربعات التنبيه هذه مطوية أبداً.
**مثال** (`[!example]-`) - ملاحظات جانبية عامة أو تفاصيل تكميلية. استخدمها للمعلومات الجانبية التي قد يجدها بعض المستخدمين ذات صلة. تبدأ مربعات التنبيه هذه مطوية.
**أمثلة:**
```md
> [!tip]- استخدم اختصارات لوحة المفاتيح
> يمكنك تسريع سير عملك بحفظ الاختصارات الأكثر استخداماً.
> [!info]+ هذه إضافة مدفوعة
> تتطلب هذه الميزة اشتراكاً مدفوعاً لاستخدامها.
> [!warning]+ لا يمكن التراجع عن هذا الإجراء
> حذف الخزنة دائم. فكّر في تصدير ملاحظاتك أولاً.
> [!example]- استخدام متقدم
> يمكنك أيضاً تهيئة هذا الإعداد عبر قائمة الرسم البياني.
```
### القوائم مقابل النثر
استخدم القوائم عند تقديم عناصر منفصلة لا تربطها علاقات تسلسلية أو سببية قوية. استخدم النثر والفقرات عندما تبني العناصر على بعضها البعض أو تتطلب شرحاً أو تستفيد من التدفق السردي.
**استخدم قائمة عند:**
- مجموعة من الميزات غير المرتبطة
- متطلبات التثبيت
- خيارات التهيئة
- خطوات استكشاف الأخطاء وإصلاحها
**استخدم النثر عند:**
- شرح كيفية عمل شيء ما
- سير العمل مع التبعيات
- النظرات العامة المفاهيمية
- الإرشادات التي تتطلب سياقاً
### الجداول
استخدم الجداول لمقارنة الميزات أو الإصدارات أو نقاط البيانات ذات الصلة حيث تساعد المحاذاة في الفهم. تجنب الجداول للقوائم البسيطة أو البيانات ذات العمود الواحد.
**حالة استخدام جيدة:**
| الميزة | الهاتف المحمول | سطح المكتب |
|---------|--------|---------|
| المزامنة | نعم | نعم |
| الإضافات | لا | نعم |
| السمات | محدودة | كاملة |
### الإحالات المرجعية
استخدم روابط الويكي الداخلية (`[[Note name]]`) بكثرة لمساعدة المستخدمين على التنقل في المواضيع ذات الصلة. ومع ذلك، تجنب الإفراط في الربط:
- لا تربط نفس المصطلح عدة مرات في صفحة واحدة
- اربط فقط عندما توفر الصفحة المُشار إليها سياقاً إضافياً مهماً
- استخدم نص رابط وصفي عند الحاجة: `[[Note name#القسم|نص وصفي]]`
**مثال:**
الإشارة الأولى: "تعرف على [[مقدمة عن Obsidian Sync|Obsidian Sync]] للحفاظ على تحديث خزنتك عبر الأجهزة."
الإشارة اللاحقة: "يمكنك تهيئة المزامنة لكل جهاز على حدة."
### المحتوى الخاص بالمنصة
عند توثيق ميزات تختلف بين المنصات، استخدم عناوين الأقسام لتنظيم المحتوى.
استخدم `سطح المكتب` و`الهاتف المحمول` كعناوين أقسام فرعية لفصل التعليمات أو الميزات الخاصة بكل منصة.
**موصى به:**
```md
## تخصيص الشريط الجانبي
### سطح المكتب
في إصدار سطح المكتب، يمكنك تخصيص الشريط الجانبي كالتالي:
- أعد ترتيب إجراءات الشريط الجانبي بالسحب والإفلات للأيقونات.
- لإخفاء إجراءات محددة، انقر بزر الماوس الأيمن على مساحة فارغة وألغِ تحديد الإجراءات التي تريد إخفاءها.
### الهاتف المحمول
في إصدار الهاتف المحمول، يمكنك تخصيص الشريط الجانبي من خلال الإعدادات:
1. افتح **[[الإعدادات]]**.
2. انتقل إلى **المظهر**.
3. اضغط على **إدارة** تحت **تهيئة الشريط**.
```
> [!info]+ متى تنشئ أقساماً منفصلة؟
> أنشئ أقساماً منفصلة فقط إذا اختلف المحتوى بشكل كبير. إذا كانت التعليمات متشابهة إلى حد كبير مع اختلافات طفيفة، استخدم ملاحظات مضمنة بدلاً من ذلك.
## الأيقونات والصور
أضف الأيقونات والصور عندما تسهّل شرح أمور يصعب وصفها بالكلمات، أو عندما تحتاج إلى إظهار أجزاء مهمة من تطبيق Obsidian. يمكنك حفظ الصور في مجلد `Attachments`.
- يجب أن تجعل الصورة النص المرافق لها أسهل في الفهم.
**مثال**: بمجرد التمكين، سيُنشئ مكوّن [[عداد الكلمات]] الإضافي إدخالاً جديداً في شريط الحالة السفلي.
![[Style-guide-zoomed-example.png#interface|300]]
- يجب أن تكون الصور بتنسيق `.png` أو `.svg`.
- إذا بدت الصورة كبيرة جداً في الملاحظة، صغّرها خارج Obsidian، أو اضبط أبعادها كما هو موضح في [[لوحة الأوامر#تضمين صورة في ملاحظة|تضمين صورة في ملاحظة]].
- في حالات نادرة، قد ترغب في وضع صور كبيرة أو معقدة بشكل خاص في [[القصاصات#مربعات التنبيه القابلة للطي|مربع تنبيه مطوي]].
- بالنسبة للنوافذ المنبثقة أو النوافذ الحوارية، يجب أن تُظهر الصورة نافذة تطبيق Obsidian بالكامل.
![[Style-guide-modal-example.png#interface]]
### الأيقونات
يمكن استخدام أيقونات [Lucide](https://lucide.dev/icons/) وأيقونات Obsidian المخصصة بجانب العناصر التفصيلية لتوفير تمثيل مرئي للميزة.
**مثال:** في الشريط الجانبي على اليسار، اختر **إنشاء لوحة بصرية جديدة** ![[lucide-layout-dashboard.svg#icon]] لإنشاء لوحة بصرية في نفس مجلد الملف النشط.
**إرشادات الأيقونات**
- خزّن الأيقونات في مجلد `Attachments/icons`.
- أضف البادئة `lucide-` قبل اسم أيقونة Lucide.
- أضف البادئة `obsidian-icon-` قبل اسم أيقونة Obsidian.
**مثال:** يجب تسمية أيقونة إنشاء لوحة بصرية جديدة بـ `lucide-layout-dashboard`.
- استخدم نسخة SVG من الأيقونات المتاحة.
- يجب أن يكون عرض الأيقونات `18` بكسل وارتفاعها `18` بكسل وعرض الخط `1.5`. يمكنك ضبط هذه الإعدادات في بيانات SVG.
> [!info]- ضبط الحجم وعرض الخط في SVG
> ```html
> <svg xmlns="http://www.w3.org/2000/svg" width="WIDTH" height="HEIGHT" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="STROKE-WIDTH" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-layout-dashboard"><rect width="7" height="9" x="3" y="3" rx="1"/><rect width="7" height="5" x="14" y="3" rx="1"/><rect width="7" height="9" x="14" y="12" rx="1"/><rect width="7" height="5" x="3" y="16" rx="1"/></svg>
>```
- استخدم مرساة `icon` في الصور المضمنة لتعديل المسافات حول الأيقونة بحيث تتماشى بدقة مع النص المحيط.
- يجب أن تكون الأيقونات محاطة بأقواس. ![[lucide-cog.svg#icon]]
**مثال**: `![[lucide-cog.svg#icon]]`
### علامات مرساة الصور
تتوفر علامات مرساة الصور لإضافة تغييرات تزيينية على الصور المضمنة.
> [!warning] تحذير المعاينة المباشرة
> لن تُعرض علامات مرساة الأيقونات بشكل صحيح في **المعاينة المباشرة**. استخدم **عرض القراءة** للتأكد من تطبيق علامة المرساة.
**أيقونة**
`![[lucide-menu.svg#icon]]`
تضمن علامة مرساة الأيقونة المحاذاة العمودية الصحيحة للأيقونات المستخدمة للإشارة إلى عناصر الواجهة.
أيقونة القائمة الأولى تستخدم علامة المرساة ![[lucide-menu.svg#icon]]، بينما أيقونة القائمة الثانية ( ![[lucide-menu.svg]] ) لا تستخدمها.
**واجهة**
`![[Vault picker.png#interface]]`
تضيف علامة مرساة الواجهة ظل صندوق تزييني حول الصورة. في الصورة الأولى، تم تطبيق علامة مرساة الواجهة.
![[Vault picker.png#interface]]
في المقابل، الصورة الثانية لا تحتوي على علامة مرساة الواجهة.
![[Vault picker.png]]
**إطار خارجي**
`![[Backlinks.png#outline]]`
تضيف علامة مرساة الإطار الخارجي حدوداً خفيفة حول الصورة. في الصورة الأولى، تم تطبيق علامة مرساة الإطار الخارجي.
> [!tip] لاحظ الزاوية السفلية اليسرى من الصورة لرؤية الفرق.
![[Backlinks.png#outline]]
الصورة الثانية لا تحتوي على علامة مرساة الإطار الخارجي.
![[Backlinks.png]]
### التحسين
تُبطئ الصور وقت تحميل الصفحة وتستهلك مساحة تخزين قيّمة في [[مقدمة عن Obsidian Publish|النشر]]. يسمح تحسين الصور بتقليل حجم الملف مع الحفاظ على السلامة البصرية للصورة.
يجب تحسين كل من الصور والأيقونات.
> [!info] أدوات تحسين الصور
> إليك بعض البرامج الموصى بها لتقليل حجم صورك.
> - **ويندوز:** [FileOptimizer](https://sourceforge.net/projects/nikkhokkho/)
> - **ماك:** [ImageOptim](https://imageoptim.com/)
> - **لينكس/يونكس** [Trimage](https://trimage.org)
>
> نوصي بمعدل تحسين يتراوح بين 65-75%.
## التخطيط
### الروابط المعطلة
قبل تقديم طلب السحب الخاص بك، يُرجى التحقق من أي روابط معطلة في توثيق الترجمة التي تعمل عليها وتصحيحها. يمكن أن تحدث الروابط المعطلة بشكل طبيعي مع مرور الوقت، لذا فإن التحقق من دقتها يساعد في الحفاظ على جودة التوثيق.
يمكنك التحقق من الروابط المعطلة باستخدام [[إضافات المجتمع]] أو الأدوات المتاحة في بيئة التطوير الخاصة بك.
### الأوصاف
يتم تحرير هذا التوثيق على GitHub واستضافته عبر الإنترنت من خلال [[مقدمة عن Obsidian Publish|Obsidian Publish]]، الذي يتضمن [[معاينات روابط وسائل التواصل الاجتماعي#الوصف|أوصافاً]] لبطاقات التواصل الاجتماعي وعناصر [[تحسين محركات البحث]] الأخرى.
إذا كانت الصفحة التي تعمل عليها لا تحتوي على [[صيغة التنسيق الأساسي|خاصية]] `description`، يُرجى إضافة واحدة. يجب أن يكون الوصف 150 حرفاً أو أقل ويقدم ملخصاً موضوعياً لمحتوى الصفحة.
**جيد**: تعلم إنشاء قوالب تلتقط وتنظم البيانات الوصفية لصفحات الويب تلقائياً باستخدام Web Clipper.
**يمكن تحسينه**: تعلم كيفية إنشاء قوالب تلتقط وتنظم البيانات الوصفية من صفحات الويب تلقائياً باستخدام Web Clipper.
### الاتجاهات
عند كتابة أو إعادة كتابة [[#التعليمات]] حول كيفية تنفيذ إجراء داخل التطبيق، تأكد من تضمين خطوات لكل من إصداري الهاتف المحمول وسطح المكتب.
إذا لم يكن لديك وصول إلى جهاز محمول أو جهاز سطح مكتب، يُرجى ذكر ذلك عند تقديم طلب السحب الخاص بك.
## الترجمات
ترجم كامل المحتوى عند إكمال الترجمة. يشمل ذلك على سبيل المثال لا الحصر:
- أسماء الملاحظات
- أسماء المجلدات
- الأسماء المستعارة
- أسماء المرفقات
- نصوص الروابط البديلة