Display colored squares in AsciiDoc: Practical guide
Published on 01 November 2025
Introduction
When writing technical documentation, particularly for style guides or user interface specifications, it is common to need to display color palettes. AsciiDoc, although very powerful for documentation, does not provide a native syntax for displaying color samples. This article explores the problem and proposes an elegant solution based on HTML injection.
The problem
Context of use
Imagine you are documenting the CSS variables of a web application theme. You need to:
-
List the hexadecimal color codes
-
Display a visual preview of each color
-
Maintain the readability of the source document
-
Ensure compatibility with static site generators like JBake
@startuml
left to right direction
skinparam packageStyle rectangle
actor "Technical Writer" as writer
actor "Reader" as reader
rectangle "AsciiDoc Documentation" {
usecase "Document color palette" as UC1
usecase "Display hexadecimal code" as UC2
usecase "View color" as UC3
usecase "Generate static site" as UC4
usecase "Consult documentation" as UC5
}
writer --> UC1
UC1 ..> UC2 : include
UC1 ..> UC3 : include
UC1 --> UC4
UC4 --> UC5
UC5 <-- reader
@enduml
Possible approaches
Several solutions can be considered to display colors in an AsciiDoc document:
@startuml
skinparam componentStyle rectangle
package "Possible solutions" {
component "Unicode characters" as unicode
component "External images" as images
component "Custom CSS roles" as css
component "HTML injection" as html
}
package "Evaluation criteria" {
component "Simplicity" as simple
component "Portability" as portable
component "Personalization" as custom
component "Maintenance" 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
Option 1: Unicode characters
The use of Unicode characters as`■`(■) is simple but limited:
* ■ --accent-color: #7952b3 (violet Bootstrap)Limitations : No control over the color, depends on the system font.
Option 2 : External images
Create PNG or SVG images for each color :
* image:colors/violet.svg[width=16] --accent-color: #7952b3Limitations : Heavy maintenance, proliferation of files, no automatic synchronization.
Option 3 : Custom CSS roles
Define CSS classes and apply them via AsciiDoc roles:
* [.color-violet]##■## --accent-color: #7952b3Limitations : Requires an external style sheet, prior definition of all possible colors.
Option 4 : HTML injection (selected solution)
Use the macro``to inject HTML with inline styles:
* 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)The solution: HTML injection with
Operating principle
The macro``AsciiDoc allows inserting raw content that will not be interpreted by the AsciiDoc processor. This lets us inject HTML directly with inline CSS styles.
@startuml participant "Document\nAsciiDoc" as doc participant "Processor\nAsciiDoc" as processor participant "pass:[] macro" as pass participant "final\nHTML" 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
Implementation
Here is the HTML structure to inject:
<span style="display:inline-block;
width:1em;
height:1em;
background:#7952b3;
vertical-align:middle;
margin-right:0.5em">
</span>Explanation of CSS properties
| Property | Function |
|---|---|
|
Allows setting width/height while staying in the inline flow |
|
Size of the square relative to the font size (responsive) |
|
The color to display (variable according to your needs) |
|
Align the square with the adjacent text |
|
Spacing between the square and the text |
Complete example
Here is an example documenting a theme palette:
== 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)Producing the following rendering:
Light Theme
-
--bg-primary:`#f8f9fa`(off-white)
-
--text-primary:`#212529`(very dark black)
-
--accent-color:`#7952b3`(violet Bootstrap)
-
--accent-hover:`#61428f`(darker violet)
-
--card-bg:`#ffffff`(white)
Optimizations and best practices
Manage the light colors
For very light colors (white, very light gray), add a border to make them visible on a white background:
<span style="display:inline-block;width:1em;height:1em;
background:#ffffff;border:1px solid #ccc;
vertical-align:middle;margin-right:0.5em"></span>The gray border`border:1px solid #ccc`) allows to outline the white square on a white background.
Adjust the size of the squares
You can adjust the size of the squares according to your needs:
* 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éThe use of the unit`em`ensures that the squares adapt to the font size.
Create variants
For specific needs, you can create different shapes:
Colored circle
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#7952b3;border-radius:50%;vertical-align:middle;margin-right:0.5em"></span>] Cercle violetSquare with colored border
* 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 violetteSolution architecture
@startuml
package "Documentation 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
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
Advantages and limitations
Advantages
-
�✓ Autonomy: No dependence on external files
-
�✓ Portability : Works with all AsciiDoc processors
-
�✓ Synchronization : The color code is directly in the HTML
-
�✓ Flexibility : Complete style customization
-
✓ Maintenance : Simple modification of the hexadecimal code
-
✓ JBake Compatibility : Works perfectly with static site generators
Limitations
-
✗ Verbosity : Repetitive HTML code in the AsciiDoc source
-
✗ Source readability: The source document is less streamlined.
-
✗ Accessibility : No native alt text (to add manually)
Accessibility improvement
To make the squares accessible to screen readers:
* 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)The attributes`role="img"` et `aria-label`allow assistive technologies to understand and describe visual content.
Concrete example: Documentation of themes
Here is a complete example documenting several topics:
= 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)Conclusion
HTML injection via the macro``AsciiDoc offers an elegant and pragmatic solution for displaying color samples in technical documentation. Although slightly verbose, this approach ensures maximum portability and simplified maintenance.
This technique requires no external configuration, no additional stylesheet, and works immediately with JBake and all standard AsciiDoc processors.
Once you have created your first colored square, simply copy-paste the HTML code and modify the hexadecimal code to quickly create a full palette.
This technique can be extended to other use cases requiring custom visual rendering: icons, badges, simple charts, or any visual element requiring precise style control.
Resources
Article published on 2025-11-01