Writer's Guide

تتضمن الأقسام التالية كل ما تحتاجه حول تعديل (editing) وتنسيق (formatting) المحتوى في هذا الموقع. تأكد من البحث قليلاً قبل البدء بتعديلاتك أو إضافاتك. أحيانا أصعب جزء هو العثور على المكان الصحيح للمحتوى وتحديد ما إذا كان موجودا مسبقا أو لا

الخطوات

1. تحقق من الـ issue (المشكلة) المرتبطة إذا كان المقال يحتوي على رابط له.
2. اضغط على edit (التعديل) وقم بالتوسع في الهيكلية (structure).
3. افتح PR (Pull Request) بالتغييرات.

YAML Frontmatter

يحتوي كل مقال على قسم صغير في الأعلى مكتوب بصيغة YAML Frontmatter:

---
title: My Article
group: My Sub-Section
sort: 3
contributors:
  - [github username]
related:
  - title: Title of Related Article
    url: [url of related article]
---

لنقم بتحليل هذه النقاط:

• title: اسم أو عنوان المقال.
• group: اسم القسم الفرعي (sub-section).
• sort: ترتيب المقال داخل القسم الرئيسي، أو داخل القسم الفرعي (في حال وجوده).
• contributors: قائمة بأسماء مستخدمي GitHub (GitHub usernames) الذين ساهموا في هذا المقال.
• related: أي قراءات ذات صلة أو أمثلة مفيدة.

يرجى ملاحظة أن حقل related سيقوم بتوليد قسم "قراءات إضافية" (Further Reading) في أسفل الصفحة، بينما سيقوم حقل contributors بتوليد قسم "المساهمون" (Contributors) أسفله مباشرةً. إذا قمت بتعديل مقال وترغب في الحصول على تقدير لجهدك، فلا تتردد في إضافة اسم مستخدم GitHub الخاص بك إلى قائمة الـ contributors.

هيكلية المقال (Article Structure)

1. مقدمة موجزة (Brief Introduction): - فقرة أو فقرتان تمنح القارئ فكرة أساسية عن "ماذا" و"لماذا".
2. مخطط بقية المحتوى (Outline Remaining Content): - توضيح لكيفية عرض وتقديم المحتوى.
3. المحتوى الرئيسي (Main Content): - تقديم الشرح والمعلومات التي وعدت بتقديمها.
4. الخاتمة (Conclusion): - تلخيص ما تم شرحه وإعادة تذكير بأهم النقاط.

التنسيق والكتابة (Typesetting)

• يمكن كتابة كلمة Webpack بحرف W كبير (Capital) في بداية الجملة. (source)
• يتم وضع الـ loaders داخل علامات اقتباس مائلة (backticks) وتُكتب بأسلوب kebab-cased: css-loader, ts-loader, …
• يتم وضع الـ plugins داخل علامات اقتباس مائلة (backticks) وتُكتب بأسلوب camel-cased: BannerPlugin, NpmInstallWebpackPlugin, …
• استخدم "webpack 2" للإشارة إلى إصدار معين من webpack (تجنب كتابتها هكذا: "webpack v2").
• استخدم المصطلحات ES5 و ES2015 و ES2016... للإشارة إلى معايير ECMAScript تجنب استخدام (ES6, ES7).

التنسيق (Formatting)

الكود (Code) :

Syntax: ```js … ```

function foo() {
  return "bar";
}

foo();

علامات الاقتباس (Quotation)

استخدم علامات الاقتباس المفردة (single quotes) في قصاصات البرمجية (code snippets) وملفات المشروع (مثل .jsx و .scss وغيرها):

- import webpack from "webpack";
+ import webpack from 'webpack';

وكذلك داخل علامات الاقتباس المائلة المضمنة (inline backticks):

صحيح (correct)

اجعل القيمة 'index.md'...

غير صحيح (incorrect)

اجعل القيمة "index.md"...

القوائم (Lists)

• Boo
• Foo
• Zoo

يجب أن يتم ترتيب القوائم أبجديا (alphabetically).

الجداول (Tables)

يجب أيضاً ترتيب الجداول أبجديا (alphabetically).

خصائص الإعدادات (Configuration Properties)

يجب أيضا ترتيب خصائص الإعدادات (configuration) أبجديا:

• devServer.compress
• devServer.hot
• devServer.static

الاقتباسات (Quotes)

الاقتباس المضمن (Blockquote)

Syntax: >

This is a blockquote.

Tip

Syntax: T>

Syntax: W>

Syntax: ?>

الافتراضات والبساطة (Assumptions and simplicity)

لا تضع افتراضات مسبقة عند كتابة التوثيق.

- You might already know how to optimize bundle for production...
+ As we've learned in [production guide](/guides/production/)...

من فضلك لا تفترض أن الأمور بسيطة. تجنب استخدام كلمات مثل 'فقط' ,'ببساطة'.

- Simply run command...
+ Run the `command-name` command...

قيم الإعدادات الافتراضية وأنواعها (Configuration defaults and types)

احرص دائماً على توفير الأنواع (types) والقيم الافتراضية (defaults) لجميع خيارات التوثيق، وذلك للحفاظ على سهولة الوصول للتوثيق وجودة كتابته. نقوم بإضافة الأنواع والقيم الافتراضية مباشرة بعد عنوان الخيار الموثّق:

configuration.example.option

string = 'none'

حيث تعني = 'none' أن القيمة الافتراضية لهذا الخيار المحدد هي 'none'.

string = 'none': 'none' | 'development' | 'production'

حيث تقوم الصيغة : 'none' | 'development' | 'production' بسرد قيم الأنواع المحتملة، وفي هذه الحالة، هناك ثلاث سلاسل نصية (strings) مقبولة: 'none' و 'development' و 'production'.

استخدم مسافة (space) بين الأنواع لسرد جميع الأنواع المتاحة للخيار المحدد:

string = 'none': 'none' | 'development' | 'production' boolean

لإيضاح وجود مصفوفة (array)، استخدم الأقواس المربعة (square brackets):

string [string]

إذا كانت المصفوفة (array) تسمح بأنواع متعددة، استخدم الفاصلة:

string [string, RegExp, function(arg) => string]

لإيضاح وجود دالة (function)، قم أيضاً بسرد الوسائط (arguments) عندما تكون متاحة:

function (compilation, module, path) => boolean

حيث تسرد الصيغة (compilation, module, path) الوسائط التي ستتلقاها الدالة الممررة، وتعني الصيغة => boolean أن القيمة المرجعة (return value) من الدالة يجب أن تكون من نوع boolean.

لتحديد الـ Plugin كنوع قيمة متاح للخيار، استخدم اسم الـ Plugin بأسلوب الـ camel case:

MinimizerPlugin [MinimizerPlugin]

وهذا يعني أن الخيار يتوقع نسخة واحدة (instance) أو بضع نسخ من MinimizerPlugin.

لتحديد رقم، استخدم number:

number = 15: 5, 15, 30

لتحديد (object) استخدم object:

object = { prop1 string = 'none': 'none' | 'development' | 'production', prop2 boolean = false, prop3 function (module) => string }

عندما يمكن لمفتاح الكائن (object's key) أن يقبل أنواعاً متعددة، استخدم الرمز | لسردها. إليك مثالاً يمكن أن تكون فيه الخاصية prop1 عبارة عن سلسلة نصية (string) ومصفوفة من السلاسل النصية (array of strings) في آن واحد:

object = { prop1 string = 'none': 'none' | 'development' | 'production' | [string]}

يسمح لنا هذا الأسلوب بعرض القيم الافتراضية والتعداد (enumeration) وغيرها من المعلومات.

عندما يمتلك خيار معين قيمًا افتراضية مختلفة بناءً على نمط التشغيل (mode)، استخدم جدول القيم الافتراضية بدلاً من كتابة الصيغة المضمنة = value:

configuration.example.option

string: 'natural' | 'named' | 'deterministic'

تعتمد القيمة الافتراضية لـ configuration.example.option على نمط التشغيل (mode):

إذا كان الخيار يحتوي على قيمة افتراضية من نوع بولين (boolean) تختلف بناء على نمط التشغيل (mode):

configuration.example.flag

boolean

تعتمد القيمة الافتراضية لـ configuration.example.flag على نمط التشغيل (mode):

إذا كان الـ (object's key) ديناميكيا ومحددا من قبل المستخدم (user-defined)، استخدم <key> لوصفه:

object = { <key> string }

القوائم المختصرة للخيارات وأنواعها (Options shortlists and their typing)

في بعض الأحيان نرغب في وصف خصائص معينة للكائنات (objects) والدوال (functions) داخل قوائم عند انطباق ذلك، قم بإضافة النوع (typing) مباشرة إلى القائمة التي تسرد فيها هذه الخصائص:

• madeUp (boolean = true): وصف مختصر
• shortText (string = 'i am text'): وصف مختصر آخر

يمكنك العثور على مثال في قسم الخيارات (options section) في صفحة EvalSourceMapDevToolPlugin.

إضافة الروابط (Adding links)

يرجى استخدام روابط URL نسبية (مثل /concepts/mode/) لربط المحتوى الخاص بنا بدلا من استخدام روابط URL مطلقة (مثل https://webpack.js.org/concepts/mode/).