在 AsciiDoc 中显示彩色方块：实用指南
Publié le 01 November 2025
介绍
在编写技术文档时，特别是样式指南或用户界面规范，常常需要显示调色板。AsciiDoc 虽然在文档方面非常强大，但没有提供原生语法来展示颜色样本。本文探讨了这一问题，并提出了一种基于 HTML 注入的优雅解决方案。
问题
使用上下文
想象一下，你正在记录一个 Web 应用程序主题的 CSS 变量。你需要：
-
列出十六进制颜色代码
-
显示每种颜色的视觉预览
-
保持源文档的可读性
-
确保与JBake等静态站点生成器兼容
可能的方法
可以考虑多种方案在 AsciiDoc 文档中显示颜色：
选项 1 : Unicode 字符
使用Unicode字符作为`■`(■) 简单但有限：
* ■ --accent-color: #7952b3 (violet Bootstrap)限制 : 无法控制颜色，依赖系统字体。
选项2：外部图像
为每种颜色创建 PNG 或 SVG 图像：
* image:colors/violet.svg[width=16] --accent-color: #7952b3限制 : 维护繁重，文件增多，没有自动同步。
选项 3 : 自定义 CSS 角色
定义 CSS 类并通过 AsciiDoc 角色应用它们：
* [.color-violet]##■## --accent-color: #7952b3Limitations : 需要外部样式表，预先定义所有可能的颜色。
选项 4 : HTML注入（已采纳的解决方案）
使用宏``用于注入带有内联样式的HTML：
* 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)解决方案：HTML 注入，带有
工作原理
宏``AsciiDoc的功能允许插入不会被AsciiDoc处理器解释的原始内容。这使我们能够直接注入带有内联CSS样式的HTML。
Failed to generate image: PlantUML preprocessing failed: [From <input> (line 2) ] @startuml participant "文档 ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml participant "文档 AsciiDoc" as doc participant "处理器 AsciiDoc" as processor participant "pass:[] 宏" as pass participant "HTML 最终" 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
实现
这是要注入的HTML结构：
<span style="display:inline-block;
width:1em;
height:1em;
background:#7952b3;
vertical-align:middle;
margin-right:0.5em">
</span>CSS属性的解释
| 属性 | 功能 |
|---|---|
|
�允许设置 width/height 同时保持在行内流中 |
|
方块的大小相对于字体的大小（响应式） |
|
要显示的颜色（根据您的需求可变） |
|
将方块与相邻文本对齐 |
|
正方形与文本之间的间距 |
完整示例
以下是一个记录主题调色板的示例：
== 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)谁生成以下渲染：
亮色主题
-
--bg-primary:`#f8f9fa`(米白色)
-
--text-primary:`#212529`（极深的黑色）
-
--accent-color:`#7952b3`(紫色 Bootstrap)
-
--accent-hover:`#61428f`( 更深的紫色 )
-
--card-bg:`#ffffff`(白色)
优化与最佳实践
管理浅色
对于非常浅的颜色（白色，非常浅的灰色），添加一个边框以使其在白色背景上可见：
<span style="display:inline-block;width:1em;height:1em;
background:#ffffff;border:1px solid #ccc;
vertical-align:middle;margin-right:0.5em"></span>灰色边框 (border:1px solid #ccc) 允许在白色背景上勾勒出白色方框。
调整方块的大小
您可以根据需要调整方块的大小：
* 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é单元的使用`em`确保正方形适应字体大小。
创建变体
对于特定需求，您可以创建不同的形式：
彩色圆
* 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带有彩色边框的正方形
* 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解决方案架构
�优势和局限
优势
-
自主性：不依赖于外部文件
-
�✓ 可移植性 : 可与所有 AsciiDoc 处理器一起工作
-
✓ 同步 : 颜色代码直接位于 HTML 中
-
�✓ Flexibilité : 完全自定义样式
-
✓ 维护 : 十六进制代码的简单修改
-
✓ JBake 兼容性 : 与静态站点生成器完美配合
限制
-
�✗ 冗长 : AsciiDoc 源文件中的重复 HTML 代码
-
✗ 源文档可读性 : 源文档较不精简
-
✗ Accessibilité : 没有原生的替代文本（需要手动添加）
改善无障碍
为了让方块对屏幕阅读器可访问：
* 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)属性`role="img"` et `aria-label`使辅助技术能够理解和描述视觉内容。
具体示例：主题文档
这里有一个完整的示例，记录了多个主题：
= 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)结论
HTML注入通过宏``AsciiDoc 提供了一种优雅且实用的解决方案，用于在技术文档中显示颜色样本。尽管这种方法略显冗长，但它确保了最大程度的可移植性和简化的维护。
此技术不需要任何外部配置，也不需要额外的样式表，并且可以在 JBake 和所有标准的 AsciiDoc 处理器上立即使用。
一旦您创建了第一个彩色方块，只需复制粘贴 HTML 代码并修改十六进制代码，即可快速创建完整的调色板。
该技术可扩展至需要自定义视觉渲染的其他使用场景：图标、徽章、简单图表，或所有需要精确控制样式的视觉元素。
资源
文章发表于 2025-11-01