Afficher des carrés colorés dans AsciiDoc : Guide pratique

Publié le 01 November 2025

1. Introduction

Lors de la rédaction de documentation technique, notamment pour des guides de style ou des spécifications d’interface utilisateur, il est fréquent de devoir afficher des palettes de couleurs. AsciiDoc, bien que très puissant pour la documentation, ne propose pas de syntaxe native pour afficher des échantillons de couleur. Cet article explore la problématique et propose une solution élégante basée sur l’injection HTML.

2. La problématique

2.1. Contexte d’utilisation

Imaginons que vous documentez les variables CSS d’un thème d’application web. Vous avez besoin de :

  1. Lister les codes couleurs hexadécimaux

  2. Afficher un aperçu visuel de chaque couleur

  3. Maintenir la lisibilité du document source

  4. Assurer la compatibilité avec les générateurs de sites statiques comme JBake

use case diagram

2.2. Les approches possibles

Plusieurs solutions peuvent être envisagées pour afficher des couleurs dans un document AsciiDoc :

component diagram

2.2.1. Option 1 : Caractères Unicode

L’utilisation de caractères Unicode comme ■ (■) est simple mais limitée :

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

Limitations : Pas de contrôle sur la couleur, dépend de la police système.

2.2.2. Option 2 : Images externes

Créer des images PNG ou SVG pour chaque couleur :

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

Limitations : Maintenance lourde, multiplication des fichiers, pas de synchronisation automatique.

2.2.3. Option 3 : Rôles CSS personnalisés

Définir des classes CSS et les appliquer via des rôles AsciiDoc :

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

Limitations : Nécessite une feuille de style externe, définition préalable de toutes les couleurs possibles.

2.2.4. Option 4 : Injection HTML (solution retenue)

Utiliser la macro pour injecter du HTML avec styles 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)

3. La solution : Injection HTML avec

3.1. Principe de fonctionnement

La macro d’AsciiDoc permet d’insérer du contenu brut qui ne sera pas interprété par le processeur AsciiDoc. Cela nous permet d’injecter directement du HTML avec des styles CSS inline.

sequence diagram

3.2. Implémentation

Voici la structure HTML à injecter :

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

3.2.1. Explication des propriétés CSS

Propriété Fonction

display:inline-block

Permet de définir width/height tout en restant dans le flux inline

width:1em; height:1em

Taille du carré relative à la taille de police (responsive)

background:#7952b3

La couleur à afficher (variable selon vos besoins)

vertical-align:middle

Aligne le carré avec le texte adjacent

margin-right:0.5em

Espacement entre le carré et le texte

3.3. Exemple complet

Voici un exemple documentant une palette de thème :

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

Qui produit le rendu suivant :

Thème Clair

  • --bg-primary: #f8f9fa (blanc cassé)

  • --text-primary: #212529 (noir très foncé)

  • --accent-color: #7952b3 (violet Bootstrap)

  • --accent-hover: #61428f (violet plus foncé)

  • --card-bg: #ffffff (blanc)

4. Optimisations et bonnes pratiques

4.1. Gérer les couleurs claires

Pour les couleurs très claires (blanc, gris très clair), ajoutez une bordure pour les rendre visibles sur fond blanc :

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

La bordure grise (border:1px solid #ccc) permet de délimiter le carré blanc sur un fond blanc.

4.2. Adapter la taille des carrés

Vous pouvez ajuster la taille des carrés selon vos besoins :

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

L’utilisation de l’unité em garantit que les carrés s’adaptent à la taille de la police.

4.3. Créer des variantes

Pour des besoins spécifiques, vous pouvez créer différentes formes :

4.3.1. Cercle coloré

* 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

4.3.2. Carré avec bordure colorée

* 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

5. Architecture de la solution

architecture diagram

6. Avantages et limitations

6.1. Avantages

  • ✓ Autonomie : Pas de dépendance à des fichiers externes

  • ✓ Portabilité : Fonctionne avec tous les processeurs AsciiDoc

  • ✓ Synchronisation : Le code couleur est directement dans le HTML

  • ✓ Flexibilité : Personnalisation complète du style

  • ✓ Maintenance : Modification simple du code hexadécimal

  • ✓ Compatibilité JBake : Fonctionne parfaitement avec les générateurs de sites statiques

6.2. Limitations

  • ✗ Verbosité : Code HTML répétitif dans le source AsciiDoc

  • ✗ Lisibilité source : Le document source est moins épuré

  • ✗ Accessibilité : Pas de texte alternatif natif (à ajouter manuellement)

6.3. Amélioration de l’accessibilité

Pour rendre les carrés accessibles aux lecteurs d’écran :

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

Les attributs role="img" et aria-label permettent aux technologies d’assistance de comprendre et décrire le contenu visuel.

7. Exemple concret : Documentation de thèmes

Voici un exemple complet documentant plusieurs thèmes :

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

8. Conclusion

L’injection HTML via la macro d’AsciiDoc offre une solution élégante et pragmatique pour afficher des échantillons de couleur dans la documentation technique. Bien que légèrement verbeuse, cette approche garantit une portabilité maximale et une maintenance simplifiée.

Cette technique ne nécessite aucune configuration externe, aucune feuille de style additionnelle, et fonctionne immédiatement avec JBake et tous les processeurs AsciiDoc standard.

Une fois que vous avez créé votre premier carré coloré, il suffit de copier-coller le code HTML et de modifier le code hexadécimal pour créer rapidement une palette complète.

Cette technique peut être étendue à d’autres cas d’usage nécessitant du rendu visuel personnalisé : icônes, badges, graphiques simples, ou tout élément visuel nécessitant un contrôle précis du style.

9. Ressources

Article publié le 2025-11-01