Отображение цветных квадратов в AsciiDoc: практическое руководство

Введение

При написании технической документации, в частности для руководств по стилю или спецификаций пользовательского интерфейса, часто требуется отображать палитры цветов. AsciiDoc, хотя и очень мощный для документации, не предоставляет собственного синтаксиса для отображения образцов цвета. Эта статья рассматривает проблему и предлагает элегантное решение, основанное на внедрении HTML.

Проблематика

Контекст использования

Представьте, что вы документируете переменные CSS темы веб-приложения. Вам нужно:

Перечислить шестнадцатеричные цветовые коды
Показать визуальный предварительный просмотр каждого цвета
Поддерживать читаемость исходного документа
Обеспечить совместимость с генераторами статических сайтов, такими как JBake

@startuml
left to right direction
skinparam packageStyle rectangle

actor "Технический писатель" as writer
actor "Читатель" as reader

rectangle "Документация AsciiDoc" {
  usecase "Документировать палитру цветов" as UC1
  usecase "Показать шестнадцатеричный код" as UC2
  usecase "Визуализировать цвет" as UC3
  usecase "Сгенерировать статический сайт" as UC4
  usecase "Просмотреть документацию" as UC5
}

writer --> UC1
UC1 ..> UC2 : include
UC1 ..> UC3 : include
UC1 --> UC4
UC4 --> UC5
UC5 <-- reader
@enduml

Возможные подходы

Существует несколько решений, которые могут быть рассмотрены для отображения цветов в документе AsciiDoc :

@startuml
skinparam componentStyle rectangle

package "Возможные решения" {
  component "Символы Unicode" as unicode
  component "Внешние изображения" as images
  component "Пользовательские CSS-роли" as css
  component "HTML-инъекция" as html
}

package "Критерии оценки" {
  component "Простота" as simple
  component "Портируемость" as portable
  component "Персонализация" as custom
  component "Обслуживание" 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
Рекомендуемое решение
end note
@enduml

Вариант 1: Юникодные символы

Использование символов 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: #7952b3

Ограничения : Требуется внешняя таблица стилей, предварительное определение всех возможных цветов.

Вариант 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 с

Принцип работы

Макрос``d’AsciiDoc позволяет вставлять сырое содержимое, которое не будет интерпретироваться процессором AsciiDoc. Это позволяет нам непосредственно внедрять HTML со встроенными стилями CSS.

@startuml
participant "Документ\nAsciiDoc" as doc
participant "Процессор\nAsciiDoc" as processor
participant "макрос `pass:[]`" as pass
participant "HTML\nфинальный" 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

Свойство Функция

Свойство	Функция
`display:inline-block`	Позволяет задать ширину/высоту, оставаясь в строчном потоке
`width:1em; height:1em`	Размер квадрата относительно размера шрифта (адаптивный)
`background:#7952b3`	Цвет для отображения (переменная в зависимости от ваших потребностей)
`vertical-align:middle`	Выровняй квадрат с соседним текстом
`margin-right:0.5em`	Расстояние между квадратом и текстом

display:inline-block

Позволяет задать ширину/высоту, оставаясь в строчном потоке

width:1em; height:1em

Размер квадрата относительно размера шрифта (адаптивный)

background:#7952b3

Цвет для отображения (переменная в зависимости от ваших потребностей)

vertical-align:middle

Выровняй квадрат с соседним текстом

margin-right:0.5em

Расстояние между квадратом и текстом

Полный пример

Вот пример, документирующий палитру темы:

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

Архитектура решения

@startuml
package "Рабочий процесс документации" {
  [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
Содержит теги
`pass:[]` с инлайновым HTML
end note

note right of jbake
Сохраняй HTML
в pass:[]
end note

note right of browser
Примените стили
inline CSS
end note
@enduml

Преимущества и ограничения

преимущества

✓ Autonomie : Нет зависимости от внешних файлов
✓ Переносимость : Работает со всеми процессорами AsciiDoc
✓ Синхронизация : Цветовой код непосредственно в HTML
✓ Гибкость : Полная настройка стиля
✓ Maintenance : Простое изменение шестнадцатеричного кода
✓ Совместимость с JBake : Идеально работает с генераторами статических сайтов

Ограничения

✗ многословие : Повторяющийся HTML-код в исходном AsciiDoc
Читаемость источника : Исходный документ менее очищен
✗ Доступность : Нет нативного альтернативного текста (добавляется вручную)

Улучшение доступности

Чтобы сделать квадраты доступными для скринридеров:

* 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 через макрос``d’AsciiDoc предлагает элегантное и практическое решение для отображения образцов цвета в технической документации. Хотя слегка многословный, этот подход гарантирует максимальную переносимость и упрощённое обслуживание.

Эта техника не требует внешней конфигурации, никакой дополнительной таблицы стилей и сразу работает с JBake и всеми стандартными процессорами AsciiDoc.

После того как вы создадите свой первый цветной квадрат, достаточно скопировать и вставить HTML-код и изменить шестнадцатеричный код, чтобы быстро создать полную палитру.

Эту технику можно расширить до других вариантов использования, требующих кастомной визуализации: значки, бейджи, простые графики или любой визуальный элемент, требующий точного контроля стиля.

Ресурсы

Статья опубликована 2025-11-01