كتيب مساعد للكود المُكتوب بلغة ماركداون - أمثلة على كيفية استخدامه

هنا أقوم بمراجعة خيارات كود بلوك في ماركداون.

كود بلوك في ماركداون

كود بلوك في ماركداون هو طريقة لعرض الكود أو النص المُنسق مسبقًا داخل وثائق ماركداون، مع الحفاظ على التنسيق وتمكين تلوين النصوص البرمجية عند الحاجة. هناك نوعان رئيسيان من تنسيق الكود في ماركداون: كود مدمج وكود بلوك.

أنواع كود بلوك في ماركداون

الاختلافات الرئيسية

• كود مدمج يستخدم مكروهات فردية (`) ويستخدم للكود القصير داخل الجمل.
• كود بلوك مُسند يستخدم أربع مسافات أو تاب في بداية كل سطر. لا يدعم تلوين النصوص البرمجية، وهو نادر الاستخدام في ماركداون الحديث.
• كود بلوك مُحاط يستخدم مكروهات ثلاثية (```) أو موجات (~~~) قبل وبعد الكود. هذا هو الطريقة المفضلة، خاصة على منصات مثل GitHub، لأن:
  • هو أسهل في القراءة والكتابة.
  • يمكنك تحديد لغة البرمجة مباشرة بعد المكروهات المفتوحة لتلوين النصوص البرمجية.
  • يحافظ على التنسيق ويدعم الكود متعدد الأسطر.

مثال لبلوك مُحاط مع تلوين النصوص البرمجية:

عندما نملك النص التالي المنسق بماركداون:

```python
def hello():
    print("Hello, world!")
```

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

def hello():
    print("Hello, world!")

أفضل الممارسات لاستخدام كود بلوك في ماركداون

• استخدم بلوك مُحاط (ثلاث مكروهات) للكود متعدد الأسطر لضمان الوضوح والتوافق عبر المنصات.
• حدد لغة البرمجة بعد المكروهات المفتوحة لتلوين النصوص البرمجية (مثلاً ``````python).
• استخدم كود مدمج للكود القصير أو الأوامر داخل النص.
• تجنب بلوك مُسند ما لم يكن مطلوبًا للتوافق مع الإصدارات القديمة، لأنه لا يدعم تلوين النصوص البرمجية ويمكن أن يكون أقل وضوحًا.
• ضع سطرًا فارغًا قبل وبعد بلوك مُحاط لتحسين الوضوح في النصوص الماركداونية الخام.

الميزات الخاصة

• تدعم بعض المنصات معرفات لغات إضافية مثل diff لعرض التغييرات في الكود، مما يمكن من تلوين الأسطر المُضافة أو المحذوفة في مراجعات الكود.
• لعرض مكروهات داخل بلوك كود، احاط الكود بكمية أكبر من المكروهات (مثلاً أربع مكروهات لعرض ثلاث مكروهات).

الخلاصة

استخدم بلوك مُحاط مع معرفة لغة للحصول على أفضل وضوح وتلوين نصوص برمجية. احتفظ بـ كود مدمج للكود القصير، وتجنب بلوك مُسند ما لم يكن مطلوبًا للتوافق.

تلوين النصوص البرمجية باستخدام diff

لـ استخدام تلوين النصوص البرمجية باستخدام diff في بلوك كود ماركداون، اتبع الخطوات التالية:

• استخدم بلوك مُحاط مع ثلاث مكروهات (```) لبدء ونهاية الكود.
• حدد diff كمعرف لغة مباشرة بعد المكروهات المفتوحة. هذا يُمكن من تلوين التغييرات، مشابهًا لما تراه في رسائل التزام Git أو طلبات السحب.

مثال:

- سطر قديم سيتم حذفه
+ سطر جديد سيتم إضافته
 سطر غير مُتغير

• السطر الذي يبدأ بـ - سيتم تلوينه كحذف (عادةً باللون الأحمر).
• السطر الذي يبدأ بـ + سيتم تلوينه كإضافة (عادةً باللون الأخضر).
• السطر الذي لا يحتوي على مقدمة لن يتم تلوينه بشكل خاص.

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

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

نصيحة:
هذه الطريقة مدعومة على نطاق واسع على منصات مثل GitHub وGitLab ومُعرضات ماركداون كثيرة، مما يجعلها خيارًا موثوقًا لمشاركة التغييرات بصريًا.

اللغات المدعومة

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

الحدود المحيطة ببلوكات الكود نفسها لا تحدد مجموعة محددة من اللغات البرمجية المدعومة بشكل رسمي. بدلًا من ذلك، تعتمد قائمة اللغات المدعومة على محرك ماركداون أو المنصة التي تستخدمها (مثل GitHub، GitLab، VS Code، Typora، Quarto، إلخ).

اللغات الشائعة المدعومة على المنصات الرئيسية (مثل GitHub، VS Code، Bitbucket، Docusaurus، وReadMe) تشمل:

• الويب والبرمجة: javascript (js)، typescript (ts)، html، css، json، xml، yaml، shell/bash (sh، bash، shell، zsh)
• البرمجة: python (py)، java، c، c++، c#، php، ruby، go، rust، scala، swift، kotlin، objective-c
• البيانات والطلبات: sql، r، matlab
• التنسيق والتكوين: markdown، ini، toml، dockerfile، makefile
• الخاصة: diff، mermaid، geojson، topojson، stl (للمخططات والتصورات على GitHub)
• الآخرين: jsx، tsx، perl، lua، julia، dart، groovy، powershell، vb، elixir، erlang، fortran، haskell، lisp، scheme، وغيرها الكثير

كيفية تحديد لغة: استخدم اسم اللغة مباشرة بعد المكروهات الثلاثية المفتوحة:

```python
def hello():
    print("Hello, world!")
```

اللغات التالية مدعومة على معظم محركات ماركداون:

ملاحظة: يمكن أن تختلف المعرفة الفعلية (مثلاً js مقابل javascript). معظم المحركات تتجاهل حالة أسماء اللغات.

كيفية العثور على القائمة الكاملة للغات المدعومة:

• GitHub: يستخدم Linguist لتلوين النصوص، ويدعم مئات اللغات.
• VS Code ومحركات الويب: يستخدم highlight.js أو Pygments - راجع وثائقهم للحصول على قائمة شاملة.
• Bitbucket: يشير إلى modes CodeMirror ومحولات Pygments.

نقاط مهمة:

• تدعم معظم المنصات جميع اللغات البرمجية والبرمجة والتنسيق الرئيسية.
• بعض المنصات تدعم أيضًا تنسيقات الرسوم والبيانات (مثل mermaid، geojson).
• معرفة اللغة عادةً غير حساسة للحالة، ولكن يجب أن تكون في الحالة الصغيرة للتوافق الأفضل.
• إذا استخدمت معرفة لغة غير مدعومة، سيتم عرض بلوك الكود كنص عادي.

تحديد اسم الملف في بلوك كود ماركداون

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

1. اسم الملف في ملصق بلوك الكود (اللغة الميتا)

بعض محركات ماركداون (مثل بعض مولدات المواقع الثابتة، أدوات الوثائق، والمنصات المدونة) تدعم لغة ميتا حيث تضيف اسم الملف بعد اللغة، مفصولة بفاصلة:

```js:app.js
console.log("Hello, world!");
```

هذا سيعرض اسم الملف (مثلاً app.js) أعلاه أو بجانب بلوك الكود، حسب المحرك.
ولكن هذا الموقع’ محرك هوجو لا يدعم ذلك:

console.log("Hello, world!");

ملاحظة: هذا غير مدعوم على جميع المنصات (مثلاً markdown نكهة GitHub لا تدعم هذه الميزة حاليًا).

2. عنوان أو كود مدمج يحتوي اسم الملف

لضمان التوافق العالمي (بما في ذلك GitHub، Stack Overflow، ومحركات ماركداون كثيرة)، ضع اسم الملف أعلاه لبلوك الكود، باستخدام عنوان أو كود مدمج مُبرز:

**`app.js`**

```
console.log("Hello, world!");
```

أو:

#### `app.js`

```
console.log("Hello, world!");
```

هذا يربط اسم الملف ببلوك الكود بصريًا وي تعمل في كل مكان.

3. اسم الملف كتعليق داخل الكود

بشكل بديل، يمكنك إدراج اسم الملف كتعليق داخل بلوك الكود نفسه:

```
// app.js
console.log("Hello, world!");
```

هذا مفيد خصوصًا إذا كنت ترغب في جعل اسم الملف مرئيًا عند نسخ الكود.

الخلاصة والممارسات المثلى

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

روابط مفيدة

• شيتسيت ماركداون - الهياكل والأوامر الأكثر فائدة
• شيتسيت هوجو
• شيتسيت باش - الأوامر الأكثر فائدة
• شيتسيت لاتيك
• الthemes الأكثر شعبية لهوجو
• https://www.markdownguide.org/extended-syntax/
• https://docs.readme.com/rdmd/docs/code-blocks