قواعد الشيفرة

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

الكود السطري

الصيغة الأساسية

استخدم علامة backtick ` لإحاطة الكود:

markdown

هذا مثال على `كود سطري`.
استخدام دالة `console.log()` لإخراج المعلومات.

نتيجة العرض:

هذا مثال على كود سطري. استخدام دالة console.log() لإخراج المعلومات.

كود يحتوي على علامات backtick

عندما يحتوي الكود نفسه على علامة backtick، استخدم علامتين:

markdown

``استخدام دالة `console.log()` ``

نتيجة العرض:

استخدام دالة `console.log()`

التعامل مع عدة علامات backtick

markdown

```كود يحتوي على عدة علامات backtick `` ` ``` هنا```

نتيجة العرض:

كود يحتوي على عدة علامات backtick `` ` هنا```

كتل الشيفرة

كتلة كود بمسافة بادئة

استخدم 4 مسافات أو علامة Tab واحدة للتداخل:

markdown

    function hello() {
        console.log("Hello, World!");
    }

نتيجة العرض:

function hello() {
    console.log("Hello, World!");
}

كتلة كود محاطة

استخدم ثلاث علامات backtick ``` أو علامات تيلدا ~~~ لإحاطة الكود:

markdown

```
function hello() {
    console.log("Hello, World!");
}
```

نتيجة العرض:

function hello() {
    console.log("Hello, World!");
}

تحديد لغة البرمجة

حدد اسم اللغة بعد ``` في البداية لتفعيل تمييز بناء الكود:

markdown

```javascript
function hello(name) {
    console.log(`Hello, ${name}!`);
}
```

نتيجة العرض:

javascript

function hello(name) {
    console.log(`Hello, ${name}!`);
}

أمثلة لغات البرمجة الشائعة

JavaScript

markdown

```javascript
// مثال دالة غير متزامنة
async function fetchData(url) {
    try {
        const response = await fetch(url);
        const data = await response.json();
        return data;
    } catch (error) {
        console.error('Error:', error);
    }
}
```

نتيجة العرض:

javascript

// مثال دالة غير متزامنة
async function fetchData(url) {
    try {
        const response = await fetch(url);
        const data = await response.json();
        return data;
    } catch (error) {
        console.error('Error:', error);
    }
}

Python

markdown

```python
# مثال تعريف الفئة
class Calculator:
    def __init__(self):
        self.result = 0
    
    def add(self, x, y):
        return x + y
    
    def multiply(self, x, y):
        return x * y

# مثال الاستخدام
calc = Calculator()
print(calc.add(5, 3))
```

نتيجة العرض:

python

# مثال تعريف الفئة
class Calculator:
    def __init__(self):
        self.result = 0
    
    def add(self, x, y):
        return x + y
    
    def multiply(self, x, y):
        return x * y

# مثال الاستخدام
calc = Calculator()
print(calc.add(5, 3))

HTML

markdown

```html
<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <title>صفحة مثال</title>
</head>
<body>
    <h1>مرحباً بك في Markdown</h1>
    <p>هذه فقرة مثال.</p>
</body>
</html>
```

نتيجة العرض:

html

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <title>صفحة مثال</title>
</head>
<body>
    <h1>مرحباً بك في Markdown</h1>
    <p>هذه فقرة مثال.</p>
</body>
</html>

CSS

markdown

```css
/* مثال تخطيط متجاوب */
.container {
    max-width: 1200px;
    margin: 0 auto;
    padding: 0 20px;
}

@media (max-width: 768px) {
    .container {
        padding: 0 10px;
    }
}

.button {
    background-color: #007bff;
    color: white;
    border: none;
    padding: 10px 20px;
    border-radius: 4px;
    cursor: pointer;
}

.button:hover {
    background-color: #0056b3;
}
```

نتيجة العرض:

css

/* مثال تخطيط متجاوب */
.container {
    max-width: 1200px;
    margin: 0 auto;
    padding: 0 20px;
}

@media (max-width: 768px) {
    .container {
        padding: 0 10px;
    }
}

.button {
    background-color: #007bff;
    color: white;
    border: none;
    padding: 10px 20px;
    border-radius: 4px;
    cursor: pointer;
}

.button:hover {
    background-color: #0056b3;
}

Bash/Shell

markdown

```bash
#!/bin/bash

# مثال سكريبت: معالجة ملفات مجمعة
for file in *.txt; do
    if [ -f "$file" ]; then
        echo "Processing $file"
        cp "$file" "backup_$file"
    fi
done

# تعريف الدالة
function check_dependencies() {
    command -v git >/dev/null 2>&1 || {
        echo "Git is required but not installed."
        exit 1
    }
}

check_dependencies
echo "All dependencies satisfied."
```

نتيجة العرض:

bash

#!/bin/bash

# مثال سكريبت: معالجة ملفات مجمعة
for file in *.txt; do
    if [ -f "$file" ]; then
        echo "Processing $file"
        cp "$file" "backup_$file"
    fi
done

# تعريف الدالة
function check_dependencies() {
    command -v git >/dev/null 2>&1 || {
        echo "Git is required but not installed."
        exit 1
    }
}

check_dependencies
echo "All dependencies satisfied."

JSON

markdown

```json
{
  "name": "markdown-tutorial",
  "version": "1.0.0",
  "description": "برنامج تعليمي Markdown بالعربية",
  "main": "index.js",
  "scripts": {
    "dev": "vitepress dev docs",
    "build": "vitepress build docs",
    "preview": "vitepress preview docs"
  },
  "dependencies": {
    "vitepress": "^1.0.0"
  },
  "author": "Your Name",
  "license": "MIT"
}
```

نتيجة العرض:

json

{
  "name": "markdown-tutorial",
  "version": "1.0.0",
  "description": "برنامج تعليمي Markdown بالعربية",
  "main": "index.js",
  "scripts": {
    "dev": "vitepress dev docs",
    "build": "vitepress build docs",
    "preview": "vitepress preview docs"
  },
  "dependencies": {
    "vitepress": "^1.0.0"
  },
  "author": "Your Name",
  "license": "MIT"
}

وظائف كتلة الكود المتقدمة

عرض أرقام الأسطر

تدعم بعض معالجات Markdown عرض أرقام الأسطر:

markdown

```javascript {1}
// هذا هو السطر الأول
function example() {
    console.log("Hello");
}
```

تمييز الأسطر

تمييز أسطر محددة:

markdown

```javascript {2-3}
function example() {
    console.log("هذا السطر مميز");  // مميز
    return true;               // مميز
}
```

عرض اسم الملف

عرض اسم ملف الكود:

markdown

```javascript title="app.js"
const express = require('express');
const app = express();

app.get('/', (req, res) => {
    res.send('Hello World!');
});
```

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

1. عدد علامات backtick غير متطابق

markdown

❌ خطأ:
```javascript
function hello() {
    console.log("Hello");
}
``  ← عدد علامات backtick غير متطابق

✅ صحيح:
```javascript
function hello() {
    console.log("Hello");
}
```

2. المسافة البادئة غير متسقة

markdown

❌ خطأ: كتلة كود بمسافة بادئة
    السطر الأول (4 مسافات)
  السطر الثاني (مسافتان)  ← المسافة البادئة غير متسقة

✅ صحيح: كتلة كود بمسافة بادئة
    السطر الأول (4 مسافات)
    السطر الثاني (4 مسافات)

3. اسم اللغة خاطئ

markdown

❌ خطأ:
```js  ← يجب أن يكون javascript
function hello() {}
```

✅ صحيح:
```javascript
function hello() {}
```

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

معرفات اللغات الشائعة:

اللغة	المعرف	مثال
JavaScript	`javascript`, `js`	`function(){}`
Python	`python`, `py`	`def function():`
Java	`java`	`public class{}`
C++	`cpp`, `c++`	`#include <iostream>`
C#	`csharp`, `cs`	`public class{}`
Go	`go`	`func main(){}`
Rust	`rust`, `rs`	`fn main(){}`
TypeScript	`typescript`, `ts`	`interface{}`
PHP	`php`	`<?php`
Ruby	`ruby`, `rb`	`def method`
SQL	`sql`	`SELECT * FROM`
HTML	`html`	`<div></div>`
CSS	`css`	`.class{}`
XML	`xml`	`<root></root>`
YAML	`yaml`, `yml`	`key: value`
Markdown	`markdown`, `md`	`# Title`
Bash	`bash`, `sh`	`#!/bin/bash`
PowerShell	`powershell`, `ps1`	`Get-Process`
Dockerfile	`dockerfile`	`FROM ubuntu`

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

1. اختيار تنسيق الكود المناسب

markdown

✅ مُوصى به: كود قصير بصيغة سطرية
استخدام طريقة `Array.map()` لمعالجة المصفوفات.

✅ مُوصى به: كود طويل بكتلة كود
function processArray(arr) {
    return arr.map(item => item * 2);
}

2. إضافة تعليقات مناسبة

markdown

✅ مُوصى به: يتضمن تعليقات توضيحية
```javascript
// حساب متوسط عناصر المصفوفة
function calculateAverage(numbers) {
    const sum = numbers.reduce((acc, num) => acc + num, 0);
    return sum / numbers.length;
}
```

3. استخدام معرف اللغة الصحيح

markdown

✅ مُوصى به: معرف لغة واضح
```typescript
interface User {
    id: number;
    name: string;
}
```

❌ غير مُوصى به: معرف لغة غامض
```text
interface User {
    id: number;
    name: string;
}
```

4. الحفاظ على الكود بسيطاً

markdown

✅ مُوصى به: عرض المنطق الأساسي
```javascript
// مصادقة المستخدم
function authenticate(token) {
    return validateToken(token);
}
```

❌ غير مُوصى به: يتضمن تفاصيل زائدة
```javascript
// هذا كود طويل جداً، يتضمن الكثير من التفاصيل غير ذات الصلة...
```

إخراج HTML

تحويل كود Markdown إلى HTML:

markdown

`كود سطري`

يتحول إلى:

html

<code>كود سطري</code>

كتلة الكود:

markdown

```javascript
function hello() {}
```

يتحول إلى:

html

<pre><code class="language-javascript">
function hello() {}
</code></pre>

أمثلة عملية

وثائق API

markdown

## تسجيل دخول المستخدم

إرسال طلب POST إلى `/api/login`:

```bash
curl -X POST https://api.example.com/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "password123"
  }'
```

مثال الاستجابة:

```json
{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 1,
    "email": "user@example.com",
    "name": "أحمد محمد"
  }
}
```

مثال ملف التكوين

markdown

## تكوين المشروع

إنشاء ملف `config.json`:

```json
{
  "database": {
    "host": "localhost",
    "port": 5432,
    "name": "myapp"
  },
  "server": {
    "port": 3000,
    "host": "0.0.0.0"
  }
}
```

تحديث سكريبتات `package.json`:

```json
{
  "scripts": {
    "start": "node server.js",
    "dev": "nodemon server.js",
    "test": "jest"
  }
}
```

دليل التثبيت

markdown

## تكوين البيئة

1. تثبيت Node.js:

```bash
# macOS (استخدام Homebrew)
brew install node

# Ubuntu/Debian
sudo apt update
sudo apt install nodejs npm

# Windows (استخدام Chocolatey)
choco install nodejs
```

2. التحقق من التثبيت:

```bash
node --version
npm --version
```

3. تهيئة المشروع:

```bash
mkdir my-project
cd my-project
npm init -y
```

قواعد ذات صلة

كتل الشيفرة المحاطة - ميزات الشيفرة الموسعة
قواعد التأكيد - تنسيقات النص
قواعد الروابط - إنشاء الروابط
محارف الهروب - التعامل مع المحارف الخاصة

التمارين

حاول إنشاء المحتوى التالي:

مجموعة أمثلة كود تحتوي على لغات برمجة متعددة
برنامج تعليمي لاستخدام API يتضمن كود الطلبات والاستجابات
دليل تثبيت يتضمن أوامر سطر الأوامر لأنظمة مختلفة
قالب ملف تكوين يتضمن شروحات تعليقات مفصلة

قواعد الشيفرة ​

الكود السطري ​

الصيغة الأساسية ​

كود يحتوي على علامات backtick ​

التعامل مع عدة علامات backtick ​

كتل الشيفرة ​

كتلة كود بمسافة بادئة ​

كتلة كود محاطة ​

تحديد لغة البرمجة ​

أمثلة لغات البرمجة الشائعة ​

JavaScript ​

Python ​

HTML ​

CSS ​

Bash/Shell ​

JSON ​

وظائف كتلة الكود المتقدمة ​

عرض أرقام الأسطر ​

تمييز الأسطر ​

عرض اسم الملف ​

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

1. عدد علامات backtick غير متطابق ​

2. المسافة البادئة غير متسقة ​

3. اسم اللغة خاطئ ​

قائمة اللغات المدعومة ​

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

1. اختيار تنسيق الكود المناسب ​

2. إضافة تعليقات مناسبة ​

3. استخدام معرف اللغة الصحيح ​

4. الحفاظ على الكود بسيطاً ​

إخراج HTML ​

أمثلة عملية ​

وثائق API ​

مثال ملف التكوين ​

دليل التثبيت ​

قواعد ذات صلة ​

التمارين ​

قواعد الشيفرة

الكود السطري

الصيغة الأساسية

كود يحتوي على علامات backtick

التعامل مع عدة علامات backtick

كتل الشيفرة

كتلة كود بمسافة بادئة

كتلة كود محاطة

تحديد لغة البرمجة

أمثلة لغات البرمجة الشائعة

JavaScript

Python

HTML

CSS

Bash/Shell

JSON

وظائف كتلة الكود المتقدمة

عرض أرقام الأسطر

تمييز الأسطر

عرض اسم الملف

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

1. عدد علامات backtick غير متطابق

2. المسافة البادئة غير متسقة

3. اسم اللغة خاطئ

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

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

1. اختيار تنسيق الكود المناسب

2. إضافة تعليقات مناسبة

3. استخدام معرف اللغة الصحيح

4. الحفاظ على الكود بسيطاً

إخراج HTML

أمثلة عملية

وثائق API

مثال ملف التكوين

دليل التثبيت

قواعد ذات صلة

التمارين