Gekleurde vierkantjes weergeven in AsciiDoc: Praktische gids

Inleiding

Tijdens het opstellen van technische documentatie, bijvoorbeeld voor stijlgidsen of specificaties voor de gebruikersinterface, is het vaak nodig om kleurpaletten weer te geven. AsciiDoc, hoewel zeer krachtig voor documentatie, biedt geen native syntaxis om kleurstalen weer te geven. Dit artikel onderzoekt de problematiek en stelt een elegante oplossing voor op basis van HTML-injectie.

De problematiek

Gebruikskontekst

Stel je voor dat je de CSS-variabelen van een webapplicatiethema documenteert. Je hebt nodig:

Lijst de hexadecimale kleurcodes
Toon een visueel voorbeeld van elke kleur
De leesbaarheid van het brondocument behouden
Zorg voor compatibiliteit met statische sitegenerators zoals JBake

@startuml
left to right direction
skinparam packageStyle rectangle

actor "Technisch Schrijver" as writer
actor "Lezer" as reader

rectangle "AsciiDoc Documentatie" {
  usecase "Kleurenpalet documenteren" as UC1
  usecase "Hexadecimale code weergeven" as UC2
  usecase "Kleur visualiseren" as UC3
  usecase "Statische site genereren" as UC4
  usecase "Documentatie raadplegen" as UC5
}

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

De mogelijke benaderingen

Meerdere oplossingen kunnen worden overwogen om kleuren weer te geven in een AsciiDoc-document:

@startuml
skinparam componentStyle rectangle

package "Mogelijke oplossingen" {
  component "Unicode-tekens" as unicode
  component "Externe afbeeldingen" as images
  component "Aangepaste CSS-rollen" as css
  component "HTML-injectie" as html
}

package "Evaluatiecriteria" {
  component "Eenvoud" as simple
  component "Portabiliteit" as portable
  component "Aanpasbaarheid" as custom
  component "Onderhoud" 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
Aanbevolen oplossing
end note
@enduml

Optie 1: Unicodekarakters

Het gebruik van Unicode-tekens zoals`■`(■) is eenvoudig maar beperkt:

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

Limitations : Geen controle over de kleur, hangt af van het systeemlettertype.

Optie 2: Externe afbeeldingen

Maak PNG- of SVG-afbeeldingen voor elke kleur :

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

Beperkingen: Zwaar onderhoud, vermenigvuldiging van bestanden, geen automatische synchronisatie.

Option 3: Aangepaste CSS-rollen

Definieer CSS-klassen en pas ze toe via AsciiDoc-rollen :

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

Limitaties : Vereist een extern stijlblad, vooraf gedefinieerde alle mogelijke kleuren.

Optie 4: HTML-injectie (gekozen oplossing)

Gebruik de macro``om HTML in te voegen met inline-stijlen:

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

De oplossing: HTML-injectie met

Werkingsprincipe

De macro``AsciiDoc staat het invoegen van ruwe inhoud toe die niet zal worden geïnterpreteerd door de AsciiDoc-processor. Dit stelt ons in staat om rechtstreeks HTML in te voegen met inline CSS-stijlen.

@startuml
participant "Document\nAsciiDoc" as doc
participant "Processor\nAsciiDoc" as processor
participant "pass:[] macro" as pass
participant "HTML\nfinal" 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

Implementatie

Dit is de HTML-structuur om in te voegen :

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

Uitleg van de CSS-eigenschappen

Eigendom Functie

Eigendom	Functie
`display:inline-block`	Maakt het mogelijk om width/height in te stellen terwijl het in de inline-flow blijft
`width:1em; height:1em`	Grootte van het vierkant ten opzichte van de lettergrootte (responsief)
`background:#7952b3`	De kleur om weer te geven (variabel volgens uw behoeften).
`vertical-align:middle`	Lijn het vierkant uit met de aangrenzende tekst
`margin-right:0.5em`	Afstand tussen het vierkant en de tekst

display:inline-block

Maakt het mogelijk om width/height in te stellen terwijl het in de inline-flow blijft

width:1em; height:1em

Grootte van het vierkant ten opzichte van de lettergrootte (responsief)

background:#7952b3

De kleur om weer te geven (variabel volgens uw behoeften).

vertical-align:middle

Lijn het vierkant uit met de aangrenzende tekst

margin-right:0.5em

Afstand tussen het vierkant en de tekst

volledig voorbeeld

Hier is een voorbeeld dat een themapalet documenteert:

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

Wie de volgende weergave produceert:

Thema Licht

--bg-primary:`#f8f9fa`(gebroken wit)
--text-primary:`#212529`(zeer donker zwart)
--accent-color:`#7952b3`(violet Bootstrap)
--accent-hover:`#61428f`(donkerder violet)
--card-bg:`#ffffff`(wit)

Optimalisaties en goede praktijken

Beheren de lichte kleuren

Voor zeer lichte kleuren (wit, zeer licht grijs), voeg een rand toe om ze zichtbaar te maken op een witte achtergrond :

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

De grijze rand (border:1px solid #ccc) maakt het mogelijk om het witte vierkant op een witte achtergrond af te bakenen.

De grootte van de vierkanten aanpassen

U kunt de grootte van de vierkanten aanpassen aan uw behoeften:

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

Het gebruik van de eenheid`em`zorgt ervoor dat de vierkanten zich aanpassen aan de lettergrootte

Varianten maken

Voor specifieke behoeften kunt u verschillende vormen maken:

gekleurde cirkel

* 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

Vierkant met gekleurde rand

* 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

Architectuur van de oplossing

@startuml
package "Documentatieworkflow" {
  [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
Bevat de tags
`pass:[]` met inline HTML
end note

note right of jbake
Bewaar de HTML
in pass:[]
end note

note right of browser
Pas de stijlen toe
inline CSS
end note
@enduml

Voordelen en beperkingen

Voordelen

✓ Autonomie : Geen afhankelijkheid van externe bestanden
✓ Portabiliteit : Werkt met alle AsciiDoc-processors
✓ Synchronisation : De kleurcode staat direct in de HTML
✓ Flexibiliteit : Volledige aanpassing van de stijl
✓ Onderhoud: Eenvoudige wijziging van de hexadecimale code
✓ JBake-compatibiliteit : Werkt perfect met statische sitegenerators

Beperkingen

✗ Verbositeit : Herhaalde HTML-code in de AsciiDoc-bron
Bronlezbaarheid : Het brondocument is minder gestroomlijnd
✗ Accessibilité : Geen natieve alternatieve tekst (handmatig toe te voegen)

Verbetering van de toegankelijkheid

Om de vierkanten toegankelijk te maken voor schermlezers :

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

De attributen`role="img"` et `aria-label`stellen assistieve technologieën in staat om visuele inhoud te begrijpen en te beschrijven

Concreet voorbeeld: Themadocumentatie

Hier is een compleet voorbeeld dat meerdere thema’s documenteert :

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

Conclusie

De HTML-injectie via de macro``d’AsciiDoc biedt een elegante en pragmatische oplossing voor het weergeven van kleurstalen in de technische documentatie. Hoewel iets omslachtig, garandeert deze aanpak maximale draagbaarheid en vereenvoudigd onderhoud.

Deze techniek vereist geen externe configuratie, geen aanvullende stylesheet, en werkt onmiddellijk met JBake en alle standaard AsciiDoc-processors.

Zodra je je eerste gekleurde vierkant hebt gemaakt, hoef je alleen de HTML-code te kopiëren en te plakken en de hexadecimale code aan te passen om snel een volledig kleurpalet te maken.

Deze techniek kan worden uitgebreid naar andere use-cases die aangepaste visuele weergave vereisen: pictogrammen, badges, eenvoudige grafieken, of elk visueel element dat een nauwkeurige stijlcontrole vereist.

Bronnen

Artikel gepubliceerd op 2025-11-01

Gerelateerde artikelen

HyperFrames-Gradle : AsciiDoc omzetten naar een MP4-video
31 May 2026

Audit van mijn LLM‑consumptie : SQLite, OpenCode, Ollama Cloud, en waarom mijn pro‑abonnement de wereldwijde markt opschudt
18 May 2026

De architectuur « Onafhankelijke plugin + consumentenroot »: Waarom worden mijn Gradle-builds geduplicerd?
14 May 2026

De Knowledge Graph als aanbevelingsmotor : hoe ik de chronologische gerelateerde artikelen heb doodgemaakt
12 May 2026

Schakel JavaScript in om de commentaren aangedreven door Disqus.