القوائم التعريفية

القوائم التعريفية هي توسعة في Markdown لإنشاء مصطلحات وتعريفاتها، مفيدة للقواميس والشرح والمعاملات.

القواعد الأساسية

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

تتكون الصيغة الأساسية من مصطلح يليه تعريف يبدأ بنقطتين في السطر التالي:

مصطلح
: محتوى التعريف

نتيجة العرض:

مصطلح : محتوى التعريف

عدة مصطلحات وتعريفات

Markdown
: لغة ترميز خفيفة الوزن
: أنشأها John Gruber عام 2004

HTML
: لغة ترميز النص الفائق
: المعيار لإنشاء صفحات الويب

نتيجة العرض:

Markdown : 一种轻量级标记语言 : 由 John Gruber 创建于 2004 年

HTML : 超文本标记语言 : 用于创建网页的标准标记语言

استخدامات متقدمة

تعريفات متعددة الأسطر

定义内容可以包含多行，后续行需要缩进：

مصطلح
: هذه هي السطر الأول من التعريف
  هذا هو السطر الثاني، مع إزاحة بمسافة واحدة على الأقل
  
  هذا فقرة جديدة، مع إزاحة ومسافة سطر فارغ قبلها

نتيجة العرض:

术语 : 这是第一行定义内容 这是第二行，需要缩进至少一个空格

这是新段落，需要缩进至少一个空格并且前面有空行

استخدام عناصر Markdown أخرى داخل التعريف

定义内容中可以使用其他 Markdown 元素，如链接、强调、代码等：

قواعد Markdown
: **Markdown** تدعم صيغ تنسيق متعددة:
  - *مائل* و **عريض**
  - [روابط](https://www.markdownlang.com)
  - `شيفرة ضمن السطر`
  - > اقتباس كتلي
  - قوائم وعناصر أخرى

نتيجة العرض:

Markdown 语法 : Markdown 支持多种文本格式化：

• 斜体 和 粗体
• 链接
• 行内代码

• 引用块

• 列表和其他元素

قوائم تعريفية متداخلة

在某些 Markdown 实现中，可以创建嵌套的定义列表：

مصطلح خارجي
: تعريف خارجي

  مصطلح داخلي
  : تعريف داخلي
  : تعريف داخلي آخر

نتيجة العرض (في المنصات المدعومة):

外层术语 : 外层定义

内层术语 : 内层定义 : 另一个内层定义

التوافق وفروقات التنفيذ

دعم المنصات المختلفة

منصة/أداة	دعم القوائم التعريفية	صياغة خاصة	دعم التداخل
GitHub Markdown	❌	-	-
GitLab Markdown	✅	标准	✅
Jekyll（kramdown）	✅	标准	✅
Hugo	✅	标准	✅
CommonMark	❌	-	-
VitePress	✅	标准	✅
Pandoc	✅	标准	✅

ناتج HTML

تحوّل أغلب المعالجات القوائم التعريفية إلى عناصر HTML <dl>, <dt>, <dd>:

<dl>
  <dt>术语</dt>
  <dd>定义内容</dd>
  
  <dt>另一个术语</dt>
  <dd>另一个定义</dd>
</dl>

صيغ مختلفة

某些处理器可能需要不同的语法变体：

<!-- الصياغة القياسية -->
مصطلح
: تعريف

<!-- صيغة مضغوطة (لبعض المعالجات) -->
مصطلح: تعريف

<!-- صيغة بمسافات إضافية (لبعض المعالجات) -->
مصطلح
  : تعريف

سيناريوهات الاستخدام

معجم مصطلحات

مناسبة جداً لجداول المصطلحات:

## قاموس مصطلحات البرمجة

API
: واجهة برمجية لمجموعة قواعد تتيح لتطبيقات البرمجيات التواصل.

إطار عمل
: مكتبات توفر بنية موحدة لتطوير التطبيقات.

Git
: نظام تحكم بالإصدارات موزّع لتتبع تغيّرات المشروع.

IDE
: بيئة تطوير متكاملة تضم محرر شيفرة وأدوات تطوير.

نتيجة العرض:

编程术语表

API : 应用程序编程接口，一组允许不同软件应用程序相互通信的规则。

框架 : 为应用程序开发提供标准化结构的软件库。

Git : 一种分布式版本控制系统，用于跟踪项目开发过程中的变化。

IDE : 集成开发环境，包含代码编辑器和各种开发工具的软件应用程序。

توثيق API

تُستخدم في توثيق API لشرح المعاملات أو الخيارات:

## معلمات الطلب

user_id
: **إلزامي** - معرّف المستخدم الفريد.
: النوع: `integer`

name
: **اختياري** - اسم العرض للمستخدم.
: النوع: `string`
: القيمة الافتراضية: `null`

status
: **اختياري** - حالة المستخدم.
: النوع: `string`
: القيم المسموحة: `active`, `inactive`, `suspended`
: القيمة الافتراضية: `active`

نتيجة العرض:

请求参数

user_id : 必填 - 用户的唯一标识符。 : 类型: integer

name : 可选 - 用户的显示名称。 : 类型: string : 默认值: null

status : 可选 - 用户状态。 : 类型: string : 允许的值: active, inactive, suspended : 默认值: active

إيضاح الإعدادات

كما تناسب شرح خيارات الإعداد:

## خيارات الإعداد

debug
: تفعيل/تعطيل وضع التصحيح.
: النوع: `boolean`
: القيمة الافتراضية: `false`
: مثال: `debug: true`

log_level
: درجة تفصيل السجلّات.
: النوع: `string`
: القيم: `error`, `warn`, `info`, `debug`
: الافتراضي: `info`
: مثال: `log_level: debug`

max_connections
: أقصى عدد اتصالات متزامنة.
: النوع: `integer`
: الافتراضي: `100`
: مثال: `max_connections: 500`

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

اتساق التنسيق

✅ 推荐做法：

1. **保持术语与定义的一致风格**：
   - 术语使用简洁的名词或短语
   - 定义以句子格式，首字母大写，句末加句号
   - 对于多行定义，保持一致的缩进

2. **合理分组**：
   - 相关术语放在一起
   - 使用标题分隔不同类别的定义列表

3. **对于技术术语**：
   - 包括类型信息
   - 添加示例
   - 标明必填或可选

❌ 避免做法：

1. 术语过长，超过一行
2. 术语中使用大段格式化文本
3. 缺少明确的分类
4. 定义中包含不相关信息

بدائل ممكنة

على المنصات غير الداعمة يمكن محاكاة ذلك بصيغ أخرى:

<!-- 使用粗体和缩进 -->
**مصطلح**
  محتوى التعريف

**مصطلح آخر**
  تعريف آخر

<!-- 使用表格 -->
| المصطلح | التعريف |
|------|------|
| API | واجهة برمجية |
| IDE | بيئة تطوير متكاملة |

<!-- 使用标题和段落 -->
### مصطلح
محتوى التعريف

### مصطلح آخر
تعريف آخر

أمثلة تطبيقية

وثائق برمجيات

## 系统要求

操作系统
: **Windows**: Windows 10 或更高版本
: **macOS**: macOS 10.14 (Mojave) 或更高版本
: **Linux**: Ubuntu 18.04+、Debian 10+、CentOS 7+

硬件
: **处理器**: 四核 2.0 GHz 或更快
: **内存**: 最少 8GB RAM，推荐 16GB
: **存储**: 至少 10GB 可用空间，SSD 存储

网络
: 宽带互联网连接 (最少 10 Mbps)
: 允许以下端口的出站连接：80、443、22

وثائق أكاديمية

## 研究术语

数据集
: 用于分析或评估的数据集合。
: 本研究使用了从公共存储库获取的样本 (n=1000)。

变量
: **自变量**: 研究者操控的输入因素。
  在本研究中，自变量是环境温度。
  
: **因变量**: 研究中被测量的输出因素。
  在本研究中，因变量是处理速度。
  
: **控制变量**: 在实验中保持不变的因素。
  在本研究中包括湿度和处理器负载。

显著性水平
: 统计分析中用于决定结果是否有意义的概率阈值。
: 本研究采用 p < 0.05 作为显著性标准。

حلول للمشكلات الشائعة

القائمة التعريفية لا تظهر

إن لم تظهر القوائم التعريفية بشكل صحيح:

1. 检查平台是否支持定义列表语法
2. 确保术语和定义之间没有空行
3. 验证冒号前面是否有合适的空格（某些处理器可能有具体要求）
4. 尝试增加缩进或更改语法变体

مشاكل في القوائم المتداخلة

قد تواجه القوائم المتداخلة مشاكل في بعض المعالجات:

1. 增加缩进层级（例如，内层术语使用4或8个空格）
2. 确保每层之间有适当的空行
3. 如果持续出现问题，考虑使用其他结构（如常规列表）

مشكلات في التنسيق

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

1. 检查是否为所有段落和元素保持了正确的缩进
2. 确保块级元素（如代码块、列表）在定义中有正确的空行分隔
3. 尝试增加缩进量

قواعد ذات صلة

• القوائم - قواعد القوائم الأساسية
• الجداول - عرض البيانات في بنية جدولية
• كتل الشيفرة المحاطة - كتل الشيفرة

工具和插件

• markdown-it-deflist: دعم القوائم التعريفية لـ markdown-it
• kramdown: معالج يدعم القوائم التعريفية
• remark-definition-list: إضافة remark للقوائم التعريفية

---

القوائم التعريفية توسعة قوية مناسبة لوثائق المصطلحات والمعاملات والإعدادات؛ ورغم أن الدعم ليس عاماً، إلا أنها تمنح بنية واضحة تسهّل فهم المعلومات.