AsciiDoc : اكتشف أتقن الصياغة للحصول على توثيق فعال
Publié le 20 June 2025
مقدمة
أسكيودوك هو لغة ترميز خفيفة تم تصميمها لكتابة مستندات تقنية منظمة، ومقالات، وكتب، أو حتى عروض تقديمية. يتميز بقراءته، وغناه النحوي، وقدرته على إنشاء تنسيقات مختلفة (HTML، PDF، DocBook، إلخ). في هذه المقالة، سنستكشف الصياغة الأساسية لأسكيودوك ونقترح نصائح للبدء بسرعة.
ما هو AsciiDoc؟
AsciiDoc هو لغة لوصف المستندات، مشابهة لـ Markdown ولكنها أكثر قوة. يسمح بتنظيم فعّال للنصوص، العناوين، القوائم، الجداول، كتل الشيفرة، وأكثر بكثير. تنوعه يجعله خيارًا شائعًا لتوثيق مشاريع المصدر المفتوح، وتأليف الكتب، والنشر على الويب.
لماذا تختار AsciiDoc ?
-
صياغة قابلة للقراءة وبديهية.
-
دعم أصلي للهياكل المعقدة (الجداول، الملاحظات، التحذيرات، إلخ).
-
توليد متعدد الصيغ (HTML، PDF، ePub، DocBook…).
-
تكامل سهل مع مولدات المواقع الثابتة مثل JBake أو Antora.
-
التخصيص المتقدم مع السمات والإضافات.
رسم بياني لحالة الاستخدام (Use Case)
يُظهر رسم بياني لحالات الاستخدام التفاعلات الرئيسية بين المستخدمين والنظام. إليك مثالًا بسيطًا لنظام توثيق :
رسم خريطة ذهنية
خريطة الذهن (خريطة عقلية) مثالية لاستكشاف المفاهيم ذات الصلة بـ AsciiDoc وعلاقاتها:
مخطط Flow(تدفق)
يسمح مخطط تدفق بوصف عملية توليد مستند AsciiDoc:
بنية أساسية لملف AsciiDoc
عادةً ما يبدأ ملف AsciiDoc بعنوان، ثم سمات اختيارية، ثم المحتوى المنظم. إليك مثالاً أدنى:
= Titre Principal
Auteur
2024-09-03
:toc:
:icons: font
Votre contenu commence ici...الصيغة الأساسية
العناوين والأقسام
أسكيديود يدعم عدة مستويات من العناوين :
= Titre de niveau 1
== Titre de niveau 2
=== Titre de niveau 3
==== Titre de niveau 4نص بالخط العريض والمائل والمتساوي العرض
*gras* _italique_ `monospace`قوائم نقطية ومُرقّمة
* Élément 1
* Élément 2
. Premier
. Deuxième
. Troisièmeالروابط والصور
Lien standard : https://asciidoc.org[AsciiDoc]
Image : image::images/logo.png[AsciiDoc Logo]كتل الكود
[source,python]def hello(): print("مرحبًا AsciiDoc !")
جداول
|===
| Colonne 1 | Colonne 2
| Valeur A
| Valeur B
| Valeur C
| Valeur D
|===ملاحظات وتحذيرات
يقدم AsciiDoc كتلاً من المعلومات المرئية:
NOTE: Ceci est une note importante.
TIP: Conseil utile pour l’utilisateur.
WARNING: Attention à ce point.استخدام السمات والمتغيرات
السمات المخصصة تسمح بإعادة استخدام القيم أو تكوين السلوكيات :
:project-name: AsciiDoc Explorer
Le projet s’appelle {project-name}.حالات الاستخدام الشائعة
-
توثيق مشروع مفتوح المصدر (README، أدلة تقنية) - التأليف والكتب الإلكترونية - إنشاء تلقائي لمواقع الويب الثابتة (JBake, Antora) - العروض التقنية
الممارسات الجيدة
-
استخدم عناوين متسقة وجدول محتويات آلي (:toc:). - يفضَّل استخدام التحذيرات لجذب الانتباه إلى النقاط الرئيسية. نظم ملفاتك لتسهيل الصيانة. - استفد من كتل الشفرة المَعَلّقة لتوضيح الأمثلة.
الاستنتاج
AsciiDoc أداة قوية وسهلة الوصول لكتابة أي وثيقة تقنية أو مقال منظم. تركيبتها الغنية، المجمّعة مع إنشاء متعدد الصيغ، تجعلها حليفًا مثاليًا للمطورين والكتاب المطالبين. جرب AsciiDoc في مشروعك القادم واكتشف الفرق!
للمضي قدمًا
-
الوثائق الرسمية : https://asciidoc.org - Asciidoctor: https://asciidoctor.org - JBake و AsciiDoc : https://jbake.org/docs/2.6.4/#asciidoc_support
شارك تجاربك ونصائحك في التعليق !