نمایش مربع‌های رنگی در AsciiDoc: راهنمای کاربردی

منتشر شده در 01 November 2025

معرفی

در حین نوشتن مستندات فنی، به‌ویژه برای راهنمای سبک یا مشخصات رابط کاربری، معمولاً نیاز به نمایش 팔ـت‌های رنگی دارد. AsciiDoc، اگرچه برای مستندات بسیار قدرتمند است، سینتکس محلی برای نمایش نمونه‌های رنگی ندارد. این مقاله به بررسی این مشکل می‌پردازد و یک راه حل شیک مبتنی بر تزریق HTML پیشنهاد می‌دهد.

مشکل

سیاق استفاده

فرض کنید که شما متغیرهای CSS یک تم وب اپلیکیشن را مستند می‌کنید. شما نیاز دارید به:

  1. کدهای رنگ هگزادسیمال را فهرست کنید

  2. نمایش پیش‌نمایش بصری هر رنگ

  3. خواندنی مستند منبع را حفظ کنید

  4. ضمانت سازگاری با تولیدکنندگان سایت استاتیک مانند JBake

@startuml
left to right direction
skinparam packageStyle rectangle

actor "نویسنده فنی" as writer
actor "خواننده" as reader

rectangle "مستندات AsciiDoc" {
  usecase "پالت رنگ را مستندسازی کنید" as UC1
  usecase "نمایش کد هگزادسیمال" as UC2
  usecase "نمایش رنگ" as UC3
  usecase "ایجاد سایت ایستا" as UC4
  usecase "مستندات را مطالعه کنید" as UC5
}

writer --> UC1
UC1 ..> UC2 : include
UC1 ..> UC3 : include
UC1 --> UC4
UC4 --> UC5
UC5 <-- reader
@enduml

روش‌های ممکن

چندین راه‌حل می‌توانند برای نمایش رنگ‌ها در یک سند AsciiDoc در نظر گرفته شوند :

@startuml
skinparam componentStyle rectangle

package "حل‌های ممکن" {
  component "کاراکترهای یونیکد" as unicode
  component "تصاویر خارجی" as images
  component "نقش‌های CSS سفارشی" as css
  component "تزریق HTML" as html
}

package "معیارهای ارزیابی" {
  component "سادگی" as simple
  component "قابلیت حمل" as portable
  component "شخصی‌سازی" as custom
  component "نگهداری" as maintain
}

unicode -down-> simple : ✓
unicode -down-> portable : ✓
unicode -down-> custom : ✗

images -down-> simple : ✗
images -down-> portable : ✗
images -down-> custom : ✓

css -down-> simple : ~
css -down-> portable : ✗
css -down-> custom : ✓

html -down-> simple : ✓
html -down-> portable : ✓
html -down-> custom : ✓✓
html -down-> maintain : ✓

note right of html
  Solution recommandée
end note
@enduml

گزینهٔ ۱: کاراکترهای یونیکد

استفاده از کاراکترهای Unicode به عنوان`■`(■) ساده اما محدود است :

* ■ --accent-color: #7952b3 (violet Bootstrap)

Limitations : هیچ کنترل بر روی رنگ نیست، به فونت سیستم وابسته است.

گزینه 2 : تصاویر خارجی

تصاویر PNG یا SVG برای هر رنگ ایجاد کنید :

* image:colors/violet.svg[width=16] --accent-color: #7952b3

mحدودیت‌ها : نگهداری سنگین، تضاعف فایل‌ها، بدون همگام‌سازی خودکار.

Option 3 : نقش‌های CSS سفارشی

تعریف کلاس‌های CSS و اعمال آنها از طریق نقش‌های AsciiDoc :

* [.color-violet]##■## --accent-color: #7952b3

Limitations : نیاز به یک فایل استایل خارجی دارد، تعریف پیش‌فرض تمام رنگ‌های ممکن.

گزینه ۴: تزریق HTML (حل برگزیده)

استفاده از ماکرو``برای تزریق HTML با استایل‌های inline:

* pass:[<span style="display:inline-block;width:1em;height:1em;
background:#7952b3;vertical-align:middle;margin-right:0.5em"></span>]
--accent-color: #7952b3 (violet Bootstrap)

حل: تزریق HTML با

مبدأ عمل

ماکرو``AsciiDoc امکان درج محتوای خام را که توسط پردازشگر AsciiDoc تفسیر نمی‌شود، فراهم می‌کند. این به ما اجازه می‌دهد تا به‌صورت مستقیم HTML را با استایل‌های CSS درون‌خطی تزریق کنیم.

@startuml
participant "سند
AsciiDoc" as doc
participant "پردازنده
AsciiDoc" as processor
participant "pass:[] ماکرو" as pass
participant "HTML
نهایت" as html

doc -> processor : Analyse document
processor -> pass : Détecte pass:[]
pass -> processor : Retourne HTML brut
processor -> html : Insère sans transformation
html -> html : Navigateur applique styles
@enduml

پیاده‌سازی

این ساختار HTML برای تزریق :

<span style="display:inline-block;
             width:1em;
             height:1em;
             background:#7952b3;
             vertical-align:middle;
             margin-right:0.5em">
</span>

توضیح ویژگی‌های CSS

ملک تابع

display:inline-block

اجازه می‌دهد تا width/height را تنظیم کند، در حالی که در جریان inline مانده است.

width:1em; height:1em

اندازه مربع نسبت به اندازه قلم (responsive)

background:#7952b3

رنگی که باید نمایش داده شود (متغیر بر اساس نیازهای شما)

vertical-align:middle

مربع را با متن مجاور تراز کن

margin-right:0.5em

فاصله بین مربع و متن

مثال کامل

اینجا یک مثال مستندسازی یک پالت تم :

== Thème Clair

* pass:[<span style="display:inline-block;width:1em;height:1em;background:#f8f9fa;border:1px solid #ccc;vertical-align:middle;margin-right:0.5em"></span>] --bg-primary: `#f8f9fa` (blanc cassé)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#212529;vertical-align:middle;margin-right:0.5em"></span>] --text-primary: `#212529` (noir très foncé)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#7952b3;vertical-align:middle;margin-right:0.5em"></span>] --accent-color: `#7952b3` (violet Bootstrap)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#61428f;vertical-align:middle;margin-right:0.5em"></span>] --accent-hover: `#61428f` (violet plus foncé)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#ffffff;border:1px solid #ccc;vertical-align:middle;margin-right:0.5em"></span>] --card-bg: `#ffffff` (blanc)

کی این رندر را تولید می‌کند:

تم روشن

  • --bg-primary:`#f8f9fa`(سفید شکسته)

  • --text-primary:`#212529`(سیاه بسیار تیره)

  • --accent-color:`#7952b3`(بنفش Bootstrap)

  • --accent-hover:`#61428f`(بنفش تیره‌تر)

  • --card-bg:`#ffffff`(سفید)

بهینه‌سازی‌ها و بهترین روش‌ها

مدیریت رنگ‌های روشن

برای رنگ‌های بسیار روشن (سفید، خاکستری بسیار روشن)، یک حاشیه اضافه کنید تا در پس‌مانند سفید قابل مشاهده شوند:

<span style="display:inline-block;width:1em;height:1em;
background:#ffffff;border:1px solid #ccc;
vertical-align:middle;margin-right:0.5em"></span>

حاشیه خاکستری`border:1px solid #ccc`) اجازه می‌دهد تا مربع سفید را در زمینه سفید محدود کند.

اندازهٔ مربع‌ها را تنظیم کنید

می‌توانید اندازه مربع‌ها را بر اساس نیازهای خود تنظیم کنید:

* pass:[<span style="display:inline-block;width:1.5em;height:1.5em;background:#7952b3;vertical-align:middle;margin-right:0.5em"></span>] Grand carré
* pass:[<span style="display:inline-block;width:0.8em;height:0.8em;background:#7952b3;vertical-align:middle;margin-right:0.5em"></span>] Petit carré

استفاده از واحد`em`garantit que les carrés s’adaptent à la taille de la police. → (space)ضمین می‌کند که مربع‌ها به اندازه قلم تنظیم شوند.

ایجاد گزینه‌ها

برای نیازهای خاص، شما می‌توانید شکل‌های مختلفی ایجاد کنید :

دایره رنگین

* pass:[<span style="display:inline-block;width:1em;height:1em;background:#7952b3;border-radius:50%;vertical-align:middle;margin-right:0.5em"></span>] Cercle violet

مربع با حاشیه رنگی

* pass:[<span style="display:inline-block;width:1em;height:1em;background:#ffffff;border:3px solid #7952b3;vertical-align:middle;margin-right:0.5em"></span>] Bordure violette

معماری راه‌حل

@startuml
package "روند کاری مستندسازی" {
  [Document AsciiDoc\navec pass macro] as asciidoc
  [Processeur JBake] as jbake
  [Site HTML statique] as html
  [Navigateur Web] as browser
}

asciidoc --> jbake : 1. Compilation
jbake --> html : 2. Génération
html --> browser : 3. Affichage
browser --> browser : 4. Rendu CSS

note right of asciidoc
  Contient les balises
  pass:[] avec HTML inline
end note

note right of jbake
  Préserve le HTML
  dans pass:[]
end note

note right of browser
  Applique les styles
  inline CSS
end note
@enduml

مزایا و محدودیت‌ها

مزایا

  • خودکفایی : عدم وابستگی به فایل‌های خارجی

  • ✓ Portabilité : با همهٔ پردازش‌های AsciiDoc کار می‌کند

  • ✓ همگام‌سازی : کد رنگ مستقیماً در HTML است

  • ✓ انعطاف‌پذیری : سفارشی‌سازی کامل سبک

  • ✓ نگهداری : تغییر سادهٔ کد هگزادسیمال

  • ✓ Compatibilité JBake : به‌طور کامل با سازندegan سایت‌های استاتیک کار می‌کند

محدودیت‌ها

  • ✗ سخنگری : کد HTML تکراری در منبع AsciiDoc

  • ✗ خوانایی منبع : سند منبع کمتر تمیز است

  • ✗ دسترسی : متن جایگزین ذاتی ندارد (که باید به‌صورت دستی اضافه شود)

بهبود دسترسی‌پذیری

برای اینکه مربع‌ها برای خوانندگان صفحه قابل دسترسی باشند :

* pass:[<span role="img" aria-label="Couleur violet Bootstrap"
style="display:inline-block;width:1em;height:1em;background:#7952b3;
vertical-align:middle;margin-right:0.5em"></span>]
--accent-color: `#7952b3` (violet Bootstrap)

ویژگی‌ها`role="img"` et `aria-label`به فناوری‌های کمکی اجازه می‌دهند تا محتوای بصری را درک و توصیف کنند.

مثال واقعی: مستندات تم‌ها

در اینجا یک مثال کامل مستند چندین موضوع :

= Guide des couleurs de l'application

== Thème Clair (`:root`)

* pass:[<span style="display:inline-block;width:1em;height:1em;background:#f8f9fa;border:1px solid #ccc;vertical-align:middle;margin-right:0.5em"></span>] --bg-primary: `#f8f9fa` (blanc cassé)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#212529;vertical-align:middle;margin-right:0.5em"></span>] --text-primary: `#212529` (noir très foncé)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#7952b3;vertical-align:middle;margin-right:0.5em"></span>] --accent-color: `#7952b3` (violet Bootstrap)

== Thème Sombre (`[data-bs-theme="dark"]`)

* pass:[<span style="display:inline-block;width:1em;height:1em;background:#212529;vertical-align:middle;margin-right:0.5em"></span>] --bg-primary: `#212529` (noir très foncé)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#ffffff;border:1px solid #999;vertical-align:middle;margin-right:0.5em"></span>] --text-primary: `#ffffff` (blanc)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#0d6efd;vertical-align:middle;margin-right:0.5em"></span>] --accent-color: `#0d6efd` (bleu Bootstrap)

== Thème Contraste Élevé (`[data-bs-theme="high-contrast"]`)

* pass:[<span style="display:inline-block;width:1em;height:1em;background:#000000;vertical-align:middle;margin-right:0.5em"></span>] --bg-primary: `#000000` (noir)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#ffffff;border:1px solid #000;vertical-align:middle;margin-right:0.5em"></span>] --text-primary: `#ffffff` (blanc)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#00ff00;vertical-align:middle;margin-right:0.5em"></span>] --accent-color: `#00ff00` (vert vif)

نتیجه

تزریق HTML از طریق ماکرو``AsciiDoc یک راه‌حل شایسته و عملی برای نمایش نمونگ‌های رنگی در مستندات فنی ارائه می‌دهد. اگرچه کمی واژگانی است، این روش حداکثر قابل حمل و نگهداری ساده را تضمین می‌کند.

این تکنیک نیازمند هیچ تنظیم خارجی، هیچ استایل‌شیت اضافی نیست، و به‌سرعت با JBake و تمام پردازنده‌های استاندارد AsciiDoc کار می‌کند.

پس از ایجاد اولین مربع رنگی خود، کافی است کد HTML را کپی‑پیست کنید و کد هگزادسیمال را تغییر دهید تا به سرعت یک پالت کامل بسازید.

این تکنیک می‌تواند برای سایر موارد استفاده که نیاز به rendering بصری سفارشی دارند، گسترش یابد: آیکون‌ها،-badge‌ها، گرافیک‌های ساده یا هر عنصر بصری دیگری که نیاز به کنترل دقیق از سبک داشته باشد.

منابع

مقاله منتشر شده در 2025-11-01

مقالات مرتبط

HyperFrames-Gradle : تحويل AsciiDoc إلى فيديو MP4
31 May 2026
بررسی مصرف من LLM : SQLite, OpenCode, Ollama Cloud، و چرا اشتراک حرفه‌ای من بازار جهانی را شکسته است
18 May 2026
Architecture « افزونه مستقل + ریه مصرف‌کننده »: چرا ساخت‌های Gradle من تکرار می‌شوند؟
14 May 2026
گراف دانش به عنوان موتور توصیه: چگونه من «مقالات مرتبط» زمانی را حذف کردم
12 May 2026