Mostrar cuadrados coloreados en AsciiDoc : Guía práctica
Publié le 01 November 2025
Introducción
Durante la redacción de documentación técnica, especialmente para guías de estilo o especificaciones de interfaz de usuario, es frecuente tener que mostrar paletas de colores. AsciiDoc, aunque muy potente para la documentación, no ofrece una sintaxis nativa para mostrar muestras de color. Este artículo explora el problema y propone una solución elegante basada en la inyección HTML.
La problemática
Contexto de uso
Imagina que estás documentando las variables CSS de un tema de una aplicación web. Necesitas:
-
Listar los códigos de color hexadecimales
-
Mostrar una vista previa visual de cada color
-
Mantener la legibilidad del documento fuente
-
Garantizar la compatibilidad con los generadores de sitios estáticos como JBake
Los enfoques posibles
Se pueden considerar varias soluciones para mostrar colores en un documento AsciiDoc:
Opción 1 : Caracteres Unicode
El uso de caracteres Unicode como`■`(■) es simple pero limitada :
* ■ --accent-color: #7952b3 (violet Bootstrap)Limitations : No hay control sobre el color, depende de la fuente del sistema.
Opción 2: Imágenes externas
Crear imágenes PNG o SVG para cada color :
* image:colors/violet.svg[width=16] --accent-color: #7952b3Limitaciones: Mantenimiento pesado, multiplicación de archivos, falta de sincronización automática.
Opción 3: Roles CSS personalizados
Definir clases CSS y aplicarlos mediante roles AsciiDoc :
* [.color-violet]##■## --accent-color: #7952b3Limitaciones : Necesita una hoja de estilo externa, definición previa de todos los colores posibles.
Opción 4: Inyección HTML (solución adoptada)
Utilizar la macro``para inyectar HTML con estilos en línea :
* 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)La solución : Inyección HTML con
Principio de funcionamiento
La macro``d’AsciiDoc permite insertar contenido sin procesar que no será interpretado por el procesador AsciiDoc. Esto nos permite inyectar directamente HTML con estilos CSS en línea.
Failed to generate image: PlantUML preprocessing failed: [From <input> (line 2) ] @startuml participant "Documento ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml participant "Documento AsciiDoc" as doc participant "Procesador AsciiDoc" as processor participant "pass:[] macro" as pass participant "HTML final" 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
Implementación
He aquí la estructura HTML para inyectar:
<span style="display:inline-block;
width:1em;
height:1em;
background:#7952b3;
vertical-align:middle;
margin-right:0.5em">
</span>Explicación de las propiedades CSS
| Propiedad | Función |
|---|---|
|
Permite definir ancho/alto manteniéndose en el flujo en línea |
|
Tamaño del cuadrado relativo al tamaño de fuente (responsive) |
|
El color a mostrar (variable según sus necesidades) |
|
Alinea el cuadrado con el texto adyacente |
|
Espaciado entre el cuadrado y el texto |
Ejemplo completo
Este es un ejemplo que documenta una paleta de tema :
== 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én produce el siguiente render:
Tema Claro
-
--bg-primary:`#f8f9fa`(blanco roto)
-
--text-primary:`#212529`(negro muy oscuro)
-
--accent-color:`#7952b3`(violeta Bootstrap)
-
--accent-hover:`#61428f`(violeta más oscuro)
-
--card-bg:`#ffffff`(blanco)
Optimizaciones y buenas prácticas
Administrar los colores claros
Para los colores muy claros (blanco, gris muy claro), añada un borde para que sean visibles sobre fondo blanco:
<span style="display:inline-block;width:1em;height:1em;
background:#ffffff;border:1px solid #ccc;
vertical-align:middle;margin-right:0.5em"></span>El borde gris (border:1px solid #ccc) permite delimitar el cuadrado blanco sobre un fondo blanco.
Adaptar el tamaño de los cuadrados
Puedes ajustar el tamaño de los cuadrados según tus necesidades:
* 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éEl uso de la unidad`em`Garantiza que los cuadrados se adapten al tamaño de la fuente.
Crear variantes
Para necesidades específicas, puede crear diferentes formas:
Círculo coloreado
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#7952b3;border-radius:50%;vertical-align:middle;margin-right:0.5em"></span>] Cercle violetCuadrado con borde coloreado
* 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 violetteArquitectura de la solución
Ventajas y limitaciones
Ventajas
-
�✓ Autonomía : Sin dependencia de archivos externos
-
�✓ Portabilidad : Funciona con todos los procesadores AsciiDoc
-
�✓ Sincronización : El código de color está directamente en el HTML
-
�✓ Flexibilidad : Personalización completa del estilo
-
�✓ Mantenimiento : Modificación simple del código hexadecimal
-
�✓ Compatibilidad JBake : Funciona perfectamente con los generadores de sitios estáticos
Limitaciones
-
�✗ Verbosidad : Código HTML repetitivo en el código fuente AsciiDoc
-
�✗ Legibilidad de la fuente : El documento fuente está menos depurado
-
Accesibilidad : No hay texto alternativo nativo (por añadir manualmente)
Mejora de la accesibilidad
Para hacer accesibles los cuadrados a los lectores de pantalla:
* 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)Los atributos`role="img"` et `aria-label`permiten a las tecnologías de asistencia comprender y describir el contenido visual.
Ejemplo concreto : Documentación de temas
Este es un ejemplo completo que documenta varios temas:
= 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)Conclusión
La inyección HTML a través de la macro``d’AsciiDoc ofrece una solución elegante y pragmática para mostrar muestras de color en la documentación técnica. Aunque sea ligeramente verbosa, este enfoque garantiza una portabilidad máxima y un mantenimiento simplificado.
Esta técnica no requiere ninguna configuración externa, ninguna hoja de estilo adicional, y funciona inmediatamente con JBake y todos los procesadores AsciiDoc estándar.
Una vez que haya creado su primer cuadrado de color, basta con copiar y pegar el código HTML y modificar el código hexadecimal para crear rápidamente una paleta completa.
Esta técnica puede extenderse a otros casos de uso que requieran un renderizado visual personalizado: íconos, insignias, gráficos simples o cualquier elemento visual que requiera un control preciso del estilo.
Recursos
Artículo publicado el 2025-11-01