Farbige Quadrate in AsciiDoc anzeigen: Praktischer Leitfaden

Einleitung

Bei der Erstellung technischer Dokumentation, beispielsweise für Stilhandbücher oder UI-Spezifikationen, ist es häufig erforderlich, Farbpaletten anzuzeigen. AsciiDoc, obwohl sehr mächtig für Dokumentation, bietet keine native Syntax zur Anzeige von Farbmustern. Dieser Artikel untersucht das Problem und schlägt eine elegante Lösung auf Basis von HTML-Injection vor.

Die Problematik

Anwendungskontext

Stellen Sie sich vor, Sie dokumentieren die CSS-Variablen eines Webanwendungs-Themas. Sie benötigen :

Liste die hexadezimalen Farbcodes
Einen visuellen Überblick über jede Farbe anzeigen
Maintenir la lisibilité du document source
Sicherstellen der Kompatibilität mit statischen Site-Generatoren wie JBake

@startuml
left to right direction
skinparam packageStyle rectangle

actor "Technischer Redakteur" as writer
actor "Leser" as reader

rectangle "AsciiDoc-Dokumentation" {
  usecase "Farbpalette dokumentieren" as UC1
  usecase "Hexadezimalcode anzeigen" as UC2
  usecase "Farbe visualisieren" as UC3
  usecase "Statische Seite generieren" as UC4
  usecase "Dokumentation einsehen" as UC5
}

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

Mögliche Ansätze

Es gibt mehrere Lösungen, die in Betracht gezogen werden können, um Farben in einem AsciiDoc-Dokument anzuzeigen:

@startuml
skinparam componentStyle rectangle

package "Mögliche Lösungen" {
  component "Unicode-Zeichen" as unicode
  component "Externe Bilder" as images
  component "Benutzerdefinierte CSS-Rollen" as css
  component "HTML-Injection" as html
}

package "Bewertungskriterien" {
  component "Einfachheit" as simple
  component "Portabilität" as portable
  component "Personalisierung" as custom
  component "Wartung" 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
Empfohlene Lösung
end note
@enduml

Option 1 : Unicode-Zeichen

Die Verwendung von Unicode-Zeichen wie`■`(■) ist einfach aber begrenzt :

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

Einschränkungen: Keine Kontrolle über die Farbe, hängt von der Systemschriftart ab.

Option 2: Externe Bilder

Erstellen Sie PNG- oder SVG-Bilder für jede Farbe:

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

Limitations : Schwerwartung, Vermehrung der Dateien, keine automatische Synchronisation.

Option 3: Benutzerdefinierte CSS-Rollen

Definiere CSS-Klassen und wende sie über AsciiDoc-Rollen an:

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

Limitations : Erfordert ein externes Stylesheet, vorherige Definition aller möglichen Farben.

Option 4: HTML-Injection (gewählte Lösung)

Die Makro verwenden``Um HTML mit Inline-Stilen einzufügen :

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

Die Lösung: HTML-Injektion mit

Funktionsprinzip

Das Makro``d’AsciiDoc erlaubt das Einfügen von rohem Inhalt, der nicht vom AsciiDoc-Prozessor interpretiert wird. Dadurch können wir direkt HTML mit Inline-CSS-Stilen einfügen.

@startuml
participant "Dokument\nAsciiDoc" as doc
participant "Prozessor\nAsciiDoc" as processor
participant "`pass:[]` Makro" 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

Implementierung

Hier ist die HTML-Struktur, die eingefügt werden soll:

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

Erklärung der CSS-Eigenschaften

Eigentum Funktion

Eigentum	Funktion
`display:inline-block`	Ermöglicht das Definieren von width/height, während es im inline-Fluss bleibt
`width:1em; height:1em`	Quadratgröße relativ zur Schriftgröße (responsive)
`background:#7952b3`	Die anzuzeigende Farbe (variabel je nach Ihren Bedürfnissen)
`vertical-align:middle`	Richte das Quadrat mit dem angrenzenden Text aus
`margin-right:0.5em`	Abstand zwischen dem Quadrat und dem Text

display:inline-block

Ermöglicht das Definieren von width/height, während es im inline-Fluss bleibt

width:1em; height:1em

Quadratgröße relativ zur Schriftgröße (responsive)

background:#7952b3

Die anzuzeigende Farbe (variabel je nach Ihren Bedürfnissen)

vertical-align:middle

Richte das Quadrat mit dem angrenzenden Text aus

margin-right:0.5em

Abstand zwischen dem Quadrat und dem Text

Vollständiges Beispiel

Hier ist ein Beispiel, das eine Themenpalette dokumentiert :

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

Wer erzeugt die folgende Ausgabe :

Helles Thema

--bg-primary:`#f8f9fa`(weiß gebrochen)
--text-primary:`#212529`(sehr dunkles Schwarz)
--accent-color:`#7952b3`(violet Bootstrap)
import sys

sys.stdout.write(sys.stdin.read())#61428f(dunkleres Violett)

--card-bg:`#ffffff`(weiß)

Optimierungen und bewährte Praktiken

Helle Farben verwalten

Für sehr helle Farben (weiß, sehr helles Grau) füge einen Rahmen hinzu, damit sie auf weißem Hintergrund sichtbar sind:

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

Die graue Grenze`border:1px solid #ccc`) ermöglicht das Begrenzen des weißen Quadrats auf einem weißen Hintergrund.

Die Größe der Quadrate anpassen

Sie können die Größe der Quadrate nach Ihren Bedürfnissen anpassen :

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

Die Verwendung der Einheit`em`garantiert, dass die Quadrate sich an die Schriftgröße anpassen.

Varianten erstellen

Für spezielle Anforderungen können Sie verschiedene Formen erstellen:

farbiger Kreis

* 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

Quadrat mit farbigem Rand

@startuml
package "Dokumentations-Workflow" {
  [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
Enthält die Tags
`pass:[]` mit inline HTML
end note

note right of jbake
Bewahre das HTML
in pass:[]
end note

note right of browser
Wende die Styles an
inline CSS
end note
@enduml

Architektur der Lösung

@startuml
package "Dokumentationsworkflow" {
  [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

Vorteile und Grenzen

Vorteile

�✓ Autonomie : Keine Abhängigkeit von externen Dateien
✓ Portabilität : Funktioniert mit allen AsciiDoc-Prozessoren
✓ Synchronisation : Der Farbcode ist direkt im HTML
�✓ Flexibilität : Vollständige Personalisierung des Stils
�✓ Wartung : Einfache Änderung des hexadezimalen Codes
�✓ JBake-Kompatibilität : Funktioniert perfekt mit statischen Site-Generatoren

Einschränkungen

✗ Ausführlichkeit : Wiederholender HTML-Code im AsciiDoc-Quellcode
✗ Lisibilité source : Le document source est moins épuré
�✗ Barrierefreiheit : Kein nativer Alternativtext (manuell hinzufügen)

Verbesserung der Zugänglichkeit

Um die Quadrate für Bildschirmlesegeräte zugänglich zu machen :

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

Die Attribute`role="img"` et `aria-label`Sie ermöglichen assistiven Technologien, visuelle Inhalte zu verstehen und zu beschreiben.

Konkretes Beispiel: Dokumentation von Themen

Hier ist ein vollständiges Beispiel, das mehrere Themen dokumentiert :

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

Fazit

Die HTML‑Injektion über das Makro``d’AsciiDoc bietet eine elegante und pragmatische Lösung zur Anzeige von Farbmustern in der technischen Dokumentation. Obwohl etwas umständlich, gewährleistet dieser Ansatz maximale Portabilität und vereinfachte Wartung.

Diese Technik erfordert keine externe Konfiguration, kein zusätzliches Stylesheet und funktioniert sofort mit JBake und allen Standard-AsciiDoc-Prozessoren.

Sobald du dein erstes farbiges Quadrat erstellt hast, musst du nur den HTML-Code kopieren und einfügen und den Hexadezimalcode ändern, um schnell eine vollständige Farbpalette zu erstellen.

Diese Technik kann auf andere Anwendungsfälle erweitert werden, die ein benutzerdefiniertes visuelles Rendering erfordern: Symbole, Abzeichen, einfache Diagramme oder jedes visuelle Element, das eine präzise Stilkontrolle erfordert.