Приказати бојане квдруге у AsciiDoc: Практичан водич
Објављено 01 November 2025
Увод
Pri izradi tehničke dokumentacije, posebno za vodiče po stilu ili specifikacije korisničkog interfejsa, često je potrebno prikazati palete boja. AsciiDoc, iako je vrlo moćan za dokumentaciju, ne nudi native sintaksu za prikaz uzoraka boja. Ovaj članak istražuje problematiku i predlaže elegantno rešenje zasnovano na HTML injekciji.
проблематика
Контекст употребе
Pretpostavimo da dokumentirate CSS promenljive teme web aplikacije. Treba vam :
-
Излистати хексадецималне кодове боја
-
Prikazati vizuelni pregled svake boje
-
Задржавати читаљивост изворног документа
-
Osigurati kompatibilnost sa generatorima statičkih sajtova kao što je JBake
@startuml
left to right direction
skinparam packageStyle rectangle
actor "Tehnički pisac" as writer
actor "Čitač" 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
Mogući pristupi
Размишља се о неколико решења за приказивање боја у документу AsciiDoc:
@startuml
skinparam componentStyle rectangle
package "Могућа решения" {
component "Unicode znakovi" as unicode
component "Spoljne slike" as images
component "Персонализоване улоге CSS" as css
component "Injekcija HTML" as html
}
package "Kriteriji vrednovanja" {
component "Простота" as simple
component "Преносливост" as portable
component "персонализација" as custom
component "Održavanje" 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
Опција 1 : Юникод карактери
Koristenje Unicode karaktera kao`■`(■) je jednostavna ali ograničena :
* ■ --accent-color: #7952b3 (violet Bootstrap)Ograničenja : Nema kontrole nad bojom, zavisi od sistema fonta.
Опција 2 : спољне слике
Kreirajte PNG ili SVG slike za svaku boju:
* image:colors/violet.svg[width=16] --accent-color: #7952b3Limitations : Teško održavanje, množenje fajlova, nema automatske sinhronizacije.
Opcija 3 : prilagođene CSS uloge
Definisati CSS klase i primenjivati ih putem AsciiDoc uloga:
* [.color-violet]##■## --accent-color: #7952b3Ograničenja : Zahtijeva vanjski stil, prethodno definisanje svih mogućih boja.
Опција 4 : убацивање HTML (одбрано решење)
Користити макрос``за убацивање HTML-а са стилови у линији :
* 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 инжекција са
princip radnje
Makro``AsciiDoc omogućava uvođenje sirovog sadržaja koji neće biti interpretiran AsciiDoc procesorom. To nam omogućava direktno ubacivanje HTML sa inline CSS stilovima.
@startuml participant "Документ\nAsciiDoc" as doc participant "Процесор AsciiDoc" as processor participant "pass:[] macro" as pass participant "HTML konačno" 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
Implementacija
Evo HTML strukture za ubaciti :
<span style="display:inline-block;
width:1em;
height:1em;
background:#7952b3;
vertical-align:middle;
margin-right:0.5em">
</span>Објашњење својстава CSS
| Svojstvo | funkcija |
|---|---|
|
Omogućava definiranje širine/visine, ostajući u inline toku |
|
Veličina kvadrata relativna prema veličini fonta (responsive) |
|
Boja koja se prikazuje (varijabilna prema vašim potrebama) |
|
Упореди квадрат са суседим текстом |
|
Razmak između kvadrata i teksta |
Комплетни пример
Ovo je primer koji dokumentuje paletu teme:
== 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)Ko daje sledeći izlaz :
svetla tema
-
--bg-primary:`#f8f9fa`(ebež)
-
lozinka:[<span style="display:inline-block;width:1em;height:1em;background:#212529;vertical-align:middle;margin-right:0.5em"></span>] --text-primary:`#212529`(vrlo tamno crno)
-
--accent-color:`#7952b3`(ljubičasta Bootstrap)
-
--accent-hover:`#61428f`(tamniji ljubičast)
-
--card-bg:`#ffffff`(бел)
Optimizacije i najbolje prakse
upravljaj svetle boje
Za veoma svetle boje (bele, veoma svetle sive), dodajte rub za da budu vidljivi na beloj pozadini :
<span style="display:inline-block;width:1em;height:1em;
background:#ffffff;border:1px solid #ccc;
vertical-align:middle;margin-right:0.5em"></span>Siva ruba (border:1px solid #ccc) омогућава обележивање белог квадрата на белој подложи.
Prilagodi veličinu kvadrata
Možete prilagoditi veličinu kvadrata po vašim potrebama:
* 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éKorišćenje jedinice`em`Гарантује да се квадрати прилагођавају величини фонта.
Kreirati varijante
Za specifične potrebe, možete da kreirate različite oblike :
obojen krug
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#7952b3;border-radius:50%;vertical-align:middle;margin-right:0.5em"></span>] Cercle violetKvadrat sa obojenom rubom
* 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 "Radni tok dokumentacije" {
[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
Prednosti i ograničenja
Предности
-
✓ Autonomija : Nema ovisnosti o vanjskim datotekama
-
Преносност : Radi sa svim procesorima AsciiDoc
-
Синхронизација : Boijski kod je непосредno u HTML
-
✓ Fleksibilnost : Potpuna prilagođavanje stila
-
✓ Održavanje : Jednostavna izmena heksadekadarnog koda
-
✓ Судирање JBake : Сасвим ради са генераторима статичних сајтова
Ograničenja
-
visložitost : Ponavljajući HTML kod u izvoru AsciiDoc
-
✗ Izvorna čitljivost : Izvorni dokument je manje obrađen
-
Приступност : Ниједан нативни алтернативни текст (да додате ручно)
Unapređenje pristupačnosti
Da bi kvadrati bili dostupni čitaocima ekrana:
* 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)Atributi`role="img"` et `aria-label`omogućavaju tehnologijama podrške da razumeju i opišu vizuelni sadržaj.
Konkreatan primer: Dokumentacija tema
Ovo je kompletan primer dokumentujući više 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)Zaključak
HTML injekcija kroz makro``AsciiDoc nudi elegantno i praktično rešenje za prikaz uzoraka boje u tehničkoj dokumentaciji. Iako je malo rečniva, ovaj pristup osigurava maksimalnu prenosivu i pojednostavljeno održavanje.
Ova tehnika ne zahteva nikakvu spoljušnju konfiguraciju, nikakvu dodatnu stilsku listu, i odmah radi sa JBake-om i svim standardnim procesorima AsciiDoc-a.
Jednak, nakon što ste napravili svoj prvi obojen kvadrat, dovoljno je kopirati i zalijepiti HTML kod i promeniti heksadekadni kod da biste brzo stvorili kompletnu paletu.
Ova technika se može proširiti na druge slučajeve upotrebe koji zahtevaju prilagođeno vizuelno renderovanje: ikonice, odličke, jednostavni grafikoni, ili svaki vizuelni element koji zahteva preciznu kontrolu stila.
Resursi
Članak objavljen 2025-11-01