AsciiDoc : یادگیری و تسلط بر سینتکس برای مستندسازی مؤثر
منتشر شده در 20 June 2025
مقدمه
AsciiDoc یک زبان علامت‌گذاری سبک است که برای نوشتن اسناد فنی ساختاریافته، مقالات، کتاب‌ها یا حتی ارائه‌ها طراحی شده است. این زبان به دلیل خوانایی، غنای دستوری و توانایی تولید فرمت‌های مختلف (HTML, PDF, DocBook و غیره) متمایز است. در این مقاله، به بررسی سنتکس اساسی AsciiDoc می‌پردازیم و پیشنهادهایی برای یادگیری سریع آن ارائه می‌دهیم.
AsciiDoc چیست؟
AsciiDoc یک زبان توصیف اسناد است که شبیه به Markdown است اما قدرتمندتر. این زبان امکان ساختاردهی مؤثر متن‌ها، عناوین، فهرست‌ها، جداول، بلوک‌های کد و موارد دیگر را فراهم می‌کند. تنوع آن گزینش محبوبی برای مستندسازی پروژه‌های منبع باز، نوشتن کتاب‌ها و انتشار وب می‌شود.
چرا AsciiDoc را انتخاب کنیم؟
-
دستور واضح و بدهی
-
پشتیبانی بومی از ساختارهای پیچیده (جداول، یادداشت‌ها، هشدارها، و غیره).
-
تولید چندفرمت (HTML, PDF, ePub, DocBook…)
-
ادغام آسان با سازندگان سایت‌های استاتیک مانند JBake یا Antora.
-
شخصی‌سازی پیشرفته با ویژگی‌ها و افزونه‌ها.
نمودار مورد استفاده (Use Case)
یک نمودار مورد استفاده امکان نمایش تعاملات اصلی بین کاربران و سیستم را می‌دهد. در اینجا یک مثال ساده برای یک سیستم مستند آورده می‌شود:
@startuml :Utilisateur: --> (Rédiger documentation) :Utilisateur: --> (Générer PDF) :Utilisateur: --> (Publier sur site web) (Rédiger documentation) ..> (Générer PDF) : inclut @enduml
نمودار نقش ذهنی
نقشهٔ ذهنی (نقشهٔ ذهنی) ایده‌آل برای بررسی مفاهیم مرتبط با AsciiDoc و روابط آن‌ها است:
@startmindmap * AsciiDoc ** Syntaxe *** Titres *** Listes *** Blocs de code *** Tableaux ** Extensions *** PlantUML *** MathJax ** Export *** HTML *** PDF *** EPUB @endmindmap
نمودار جریان ( جریان )
یک نمودار جریان می‌تواند فرآیند تولید یک مستند AsciiDoc را توصیف کند:
@startuml start :Écrire fichier .adoc; :Ajouter images et diagrammes; if (Valider la syntaxe ?) then (oui) :Générer HTML/PDF; :Publier ou partager; else (non) :Corriger erreurs; :back to start; endif stop @enduml
ساختار اصلی یک فایل AsciiDoc
یک فایل AsciiDoc معمولاً با یک عنوان، ویژگی‌های اختیاری و سپس محتوای ساخت‌یافته شروع می‌شود. یک مثال کمینه :
= Titre Principal
Auteur
2024-09-03
:toc:
:icons: font
Votre contenu commence ici...سینتکس اساسی
عنوان‌ها و بخش‌ها
AsciiDoc از چندین سطح عنوان پشتیبانی می‌کند :
= 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}.مورد استفاده‌های رایج
-
مستندات پروژه open source (README، راهنمای تکنیکی) - نوشتن کتاب‌ها و کتاب‌های الکترونیکی - تولید خودکار سایت‌های استاتیک (JBake, Antora) - ارائه‌های فنی
آداب عمل
-
از عناوین یکنواخت و یک فهرست خودکار (:toc:) استفاده کنید. - اولویت دهید از اخطارات برای جلب توجه به نکات کلیدی استفاده کنید. - فایل‌های خود را برای تسهیل نگهداری سازماندهی کنید. - از بلوک‌های کد مشروح برای مثال‌سازی استفاده کنید.
نتیجه
AsciiDoc ابزاری قدرتمند و قابل دسترسی برای نوشتن هرگونه مستند فنی یا مقاله ساختاریافته است. سینتکس غنی آن، همراه با تولید چند فرمت، به عنوان یک همیار مورد علاقه برای توسعه‌دهندگان و نویسندگانی که به‌دقت کار می‌کنند، محسوب می‌شود. AsciiDoc را در پروژه‌ی آینده خود امتحان کنید و تفاوت را ببینید!
برای پیشرفت بیشتر
-
مستندات رسمی : https://asciidoc.org - Asciidoctor: https://asciidoctor.org - JBake و AsciiDoc : https://jbake.org/docs/2.6.4/#asciidoc_support
تجربات و نکات خود را در نظرات به اشتراک بگذارید!