Exibir quadrados coloridos no AsciiDoc: Guia prático
Publié le 01 November 2025
Introdução
Ao redigir documentação técnica, especialmente para guias de estilo ou especificações de interface do usuário, é comum precisar exibir paletas de cores. AsciiDoc, embora muito poderoso para documentação, não oferece sintaxe nativa para exibir amostras de cor. Este artigo explora o problema e propõe uma solução elegante baseada na injeção HTML.
A problemática
Contexto de uso
Imagine que você está documentando as variáveis CSS de um tema de aplicação web. Você precisa de :
-
Listar os códigos de cores hexadecimais
-
Mostrar um exemplo visual de cada cor
-
Manter a legibilidade do documento fonte
-
Garantir a compatibilidade com os geradores de sites estáticos como JBake
As abordagens possíveis
Várias soluções podem ser consideradas para exibir cores em um documento AsciiDoc :
Opção 1: Caracteres Unicode
O uso de caracteres Unicode como`■`(■) é simples, mas limitada:
* ■ --accent-color: #7952b3 (violet Bootstrap)Limitações : Sem controle sobre a cor, depende da fonte do sistema.
Opção 2: Imagens externas
Criar imagens PNG ou SVG para cada cor:
* image:colors/violet.svg[width=16] --accent-color: #7952b3Limitations : Manutenção pesada, multiplicação dos arquivos, não há sincronização automática.
Opção 3 : Papéis CSS personalizados
Definir classes CSS e aplicá-las por meio de papéis AsciiDoc:
* [.color-violet]##■## --accent-color: #7952b3Limitações : Necessita de uma folha de estilo externa, definição prévia de todas as cores possíveis.
Opção 4: Injeção HTML (solução retenida)
Utilizar a macro``para injetar HTML com estilos em linha :
* 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)A solução : Injeção de HTML com
Princípio de funcionamento
A macro``O AsciiDoc permite inserir conteúdo bruto que não será interpretado pelo processador AsciiDoc. Isso nos permite injetar diretamente HTML com estilos CSS inline.
Failed to generate image: PlantUML preprocessing failed: [From <input> (line 5) ] @startuml participant "Document\nAsciiDoc" as doc participant "Processador\nAsciiDoc" as processor participant "pass:[] macro" as pass participant "HTML ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml participant "Document\nAsciiDoc" as doc participant "Processador\nAsciiDoc" 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
Implementação
Aqui está a estrutura HTML para injetar:
<span style="display:inline-block;
width:1em;
height:1em;
background:#7952b3;
vertical-align:middle;
margin-right:0.5em">
</span>Explicação das propriedades CSS
| Propriedade | Função |
|---|---|
|
Permite definir width/height permanecendo no fluxo inline |
|
Tamanho do quadrado relativo ao tamanho da fonte (responsivo) |
|
A cor a ser exibida (variável de acordo com suas necessidades) |
|
Alinhe o quadrado com o texto adjacente |
|
Espaçamento entre o quadrado e o texto |
Exemplo completo
Este é um exemplo documentando uma 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)Quem produz a seguinte saída:
Tema Claro
-
--bg-primary:`#f8f9fa`(branco quebrado)
-
--text-primary:`#212529`(preto muito escuro)
-
--cor-de-destaque:`#7952b3`(violeta Bootstrap)
-
--accent-hover:`#61428f`(violeta mais escuro)
-
--card-bg:`#ffffff`(branco)
Optimizações e boas práticas
Gerir as cores claras
Para cores muito claras (branco, cinza muito claro), adicione uma borda para torná-las visíveis em fundo branco :
<span style="display:inline-block;width:1em;height:1em;
background:#ffffff;border:1px solid #ccc;
vertical-align:middle;margin-right:0.5em"></span>A borda cinza (border:1px solid #ccc) permite delimitar o quadrado branco sobre um fundo branco.
Ajustar o tamanho dos quadrados
Você pode ajustar o tamanho dos quadrados de acordo com suas necessidades:
* 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éO uso da unidade`em`garante que os quadrados se adaptem ao tamanho da fonte.
Criar variantes
Para necessidades específicas, você pode criar diferentes formas:
Círculo colorido
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#7952b3;border-radius:50%;vertical-align:middle;margin-right:0.5em"></span>] Cercle violetQuadrado com borda colorida
* 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 violetteArquitetura da solução
Vantagens e limitações
Vantagens
-
✓ Autonomia : Não há dependência de arquivos externos
-
�✓ Portabilidade : Funciona com todos os processadores AsciiDoc
-
✓ Sincronização : O código de cores está diretamente no HTML
-
✓ Flexibilidade : Personalização completa do estilo
-
✓ Manutenção : Modificação simples do código hexadecimal
-
✓ Compatibilidade JBake : Funciona perfeitamente com os geradores de sites estáticos
Limitações
-
✗ Verbosité : Código HTML repetitivo no código-fonte AsciiDoc
-
�✗ Legibilidade da fonte : O documento fonte é menos limpo
-
✗ Acessibilidade : Sem texto alternativo nativo (a ser adicionado manualmente)
Melhoria da acessibilidade
Para tornar os quadrados acessíveis aos leitores de tela:
* 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)Os atributos`role="img"` et `aria-label`Permitem que as tecnologias assistivas compreendam e descrevam o conteúdo visual.
Exemplo concreto: Documentação de temas
Aqui está um exemplo completo documentando vários 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)Conclusão
A injeção HTML via a macro``O AsciiDoc oferece uma solução elegante e pragmática para exibir amostras de cor na documentação técnica. Embora seja ligeiramente verbosa, essa abordagem garante uma portabilidade máxima e uma manutenção simplificada.
Esta técnica não requer nenhuma configuração externa, nenhuma folha de estilo adicional, e funciona imediatamente com JBake e todos os processadores AsciiDoc padrões.
Depois de você ter criado seu primeiro quadrado colorido, basta copiar e colar o código HTML e alterar o código hexadecimal para criar rapidamente uma paleta completa.
Esta técnica pode ser estendida a outros casos de uso que necessitam de renderização visual personalizada: ícones, badges, gráficos simples, ou todo elemento visual que necessita de um controle preciso do estilo.
Recursos
Artigo publicado em 2025-11-01