Menampilkan kotak berwarna dalam AsciiDoc : Panduan Praktis

Pendahuluan

Saat menyusun dokumentasi teknis, terutama untuk panduan gaya atau spesifikasi antarmuka pengguna, seringkali diperlukan untuk menampilkan palet warna. AsciiDoc, meski sangat kuat untuk dokumentasi, tidak menyediakan sintaksis bawaan untuk menampilkan sampel warna. Artikel ini mengeksplorasi masalah dan menawarkan solusi yang elegan berbasis injeksi HTML.

Masalah

Konteks penggunaan

Bayangkan bahwa Anda mendokumentasikan variabel CSS dari tema aplikasi web. Anda membutuhkan :

Daftar kode warna heksadesimal
Menampilkan pratinjau visual setiap warna
Mempertahankan keterbacaan dokumen sumber
Memastikan kompatibilitas dengan generator situs statis seperti JBake

@startuml
left to right direction
skinparam packageStyle rectangle

actor "Penulis Teknis" as writer
actor "Pembaca" as reader

rectangle "Dokumentasi AsciiDoc" {
  usecase "dokumentasikan palet warna" as UC1
  usecase "Tampilkan kode heksadesimal" as UC2
  usecase "Lihat warna" as UC3
  usecase "Menghasilkan situs statis" as UC4
  usecase "Melihat dokumentasi" as UC5
}

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

Pendekatan yang mungkin

Beberapa solusi dapat dipertimbangkan untuk menampilkan warna dalam dokumen AsciiDoc :

@startuml
skinparam componentStyle rectangle

package "Solusi mungkin" {
  component "Karakter Unicode" as unicode
  component "Gambar eksternal" as images
  component "Peran CSS khusus" as css
  component "Injeksi HTML" as html
}

package "Kriteria evaluasi" {
  component "kesederhanaan" as simple
  component "portabilitas" as portable
  component "Personalisasi" as custom
  component "Pemeliharaan" 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

Pilihan 1 : Karakter Unicode

Penggunaan karakter Unicode seperti`■`(■) adalah sederhana tetapi terbatas:

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

Keterbatasan : Tidak ada kontrol atas warna, bergantung pada font sistem.

Opsi 2 : Gambar Eksternal

Buat gambar PNG atau SVG untuk setiap warna:

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

Keterbatasan : Pemeliharaan yang berat, perbantasan file, tidak ada sinkronisasi otomatis.

Opsi 3 : Peran CSS Kustom

Menentukan kelas CSS dan menerapkannya melalui peran AsciiDoc :

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

Keterbatasan : Memerlukan lembar gaya eksternal, definisi sebelumnya semua warna yang mungkin.

Opsi 4 : Injeksi HTML (solusi yang dipilih)

Menggunakan makro``untuk menyisipkan HTML dengan gaya 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)

Solusi : Injeksi HTML dengan

Prinsip kerja

makro``d’AsciiDoc memungkinkan untuk menyisipkan konten mentah yang tidak akan ditafsirkan oleh prosesor AsciiDoc. Hal ini memungkinkan kita untuk langsung menyisipkan HTML dengan gaya CSS inline.

@startuml
participant "Dokumen
AsciiDoc" as doc
participant "Prosesor\nAsciiDoc" as processor
participant "pass:[] macro" as pass
participant "HTML
akhir" 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

Implementasi

Berikut struktur HTML untuk disisipkan:

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

Penjelasan properti CSS

Properti fungsi

Properti	fungsi
`display:inline-block`	Memungkinkan pengaturan lebar/tinggi sambil tetap berada dalam alur inline
`width:1em; height:1em`	Ukuran persegi relatif terhadap ukuran font (responsif)
`background:#7952b3`	Warna yang ditampilkan (variabel sesuai kebutuhan Anda)
`vertical-align:middle`	Ratakan persegi dengan teks yang bersebelahan
`margin-right:0.5em`	Jarak antara kotak dan teks

display:inline-block

Memungkinkan pengaturan lebar/tinggi sambil tetap berada dalam alur inline

width:1em; height:1em

Ukuran persegi relatif terhadap ukuran font (responsif)

background:#7952b3

Warna yang ditampilkan (variabel sesuai kebutuhan Anda)

vertical-align:middle

Ratakan persegi dengan teks yang bersebelahan

margin-right:0.5em

Jarak antara kotak dan teks

Contoh lengkap

Berikut adalah contoh yang mendokumentasikan palet tema :

== 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)

Yang menghasilkan rendering berikut:

Tema Terang

--bg-primary:`#f8f9fa`(putih krem)
--text-primary:`#212529`(hitam sangat gelap)
--accent-color:`#7952b3`(ungu Bootstrap)
--accent-hover:`#61428f`(ungu lebih gelap)
--card-bg:`#ffffff`(putih)

Optimisasi dan praktik terbaik

Mengelola warna terang

Untuk warna-warni yang sangat terang (putih, abu-abu sangat terang), tambahkan garis tepi agar terlihat pada latar belakang putih:

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

batas kelabu`border:1px solid #ccc`) memungkinkan untuk membatasi kotak putih di latar belakang putih.

Mengatur ukuran persegi

Anda dapat menyesuaikan ukuran kotak sesuai kebutuhan Anda :

* 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é

Penggunaan satuan`em`memastikan bahwa kotak menyesuaikan ukuran dengan ukuran huruf

Membuat varian

Untuk kebutuhan spesifik, Anda dapat membuat bentuk-bentuk yang berbeda:

lingkaran berwarna

* 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

Persegi dengan batas berwarna

* 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

Arsitektur solusi

@startuml
package "Alur kerja dokumentasi" {
  [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

Manfaat dan batasan

kelebihan

✓ Kemandirian : Tidak ada ketergantungan pada file eksternal
✓ Portabilitas : Berfungsi dengan semua prosesor AsciiDoc
✓ Synchronisation : Kode warnanya berada langsung di HTML
✓ Fleksibilitas : Penyesuaian lengkap gaya
✓ Maintenance : Modifikasi sederhana kode heksadesimal
✓ Kompatibilitas JBake : Berfungsi dengan sempurna dengan generator situs statis

Keterbatasan

✗ Verbosity : Repetitive HTML code in the AsciiDoc source
✗ Keterbacaan sumber : Dokumen sumber kurang rapi
✗ Aksesibilitas : Tidak ada teks alternatif bawaan (yang harus ditambahkan secara manual)

Peningkatan aksesibilitas

Untuk membuat kotak dapat diakses oleh pembaca layar :

* 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)

Atribut`role="img"` et `aria-label`Memungkinkan teknologi asistif untuk memahami dan menggambarkan konten visual.

Contoh konkret: Dokumentasi tema

Berikut contoh lengkap yang mendokumentasikan beberapa tema:

= 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)

Kesimpulan

Injeksi HTML melalui makro``d’AsciiDoc menawarkan solusi yang elegan dan pragmatis untuk menampilkan sampel warna dalam dokumentasi teknis. Meskipun sedikit bertele-tele, pendekatan ini menjamin portabilitas maksimal dan pemeliharaan yang disederhanakan.

Teknik ini tidak memerlukan konfigurasi eksternal, tidak memerlukan lembar gaya tambahan, dan berfungsi segera dengan JBake dan semua prosesor AsciiDoc standar.

Setelah Anda membuat kotak berwarna pertama Anda, cukup menyalin dan menempelkan kode HTML dan mengubah kode heksadesimal untuk dengan cepat membuat palet lengkap.

Teknik ini dapat diperluas ke kasus penggunaan lain yang memerlukan rendering visual khusus: ikon, badge, grafik sederhana, atau elemen visual apa pun yang memerlukan kontrol gaya yang tepat.

Sumber daya

Artikel dipublikasikan pada 2025-11-01