Темизация
Темизация настраивает визуальное оформление документации.
Управлять темой документации можно с помощью конфигурационного файла theme.yaml в корне проекта, при сборке с помощью флага --theme или в корневой секции .yfm.
Определение темы в файле конфигурации
Структура файла
Файл конфигурации theme.yaml задаёт цветовую палитру вашей документации. Цвет может быть определен как в общем для светлой и для темной темы, так и отдельно для каждой.
Параметры, указанные в секциях light или dark, имеют приоритет над общими значениями. Если переменная определена одновременно и в основной секции, и в light или dark секции, то использоваться будет значение конкретной темы.
Цвет может быть задан в формате rgb, rgba, hex, hsl, hsla или названием цвета.
Пример файла конфигурации:
base-brand: rgb(152 223 37)
link: red
light:
link: rgb(0 255 170)
quote: rgb(255 0 255)
dark:
quote: rgba(0, 208, 255, 1)
base-background: hsl(30 46% 41%)
Параметр base-brand
Параметр base-brand является основным акцентным цветом темы. От значения base-brand автоматически определяются следующие зависимые параметры:
base-selectionlinklink-hovertab-activetab-texttab-text-hoverquote
Любое значение переменной, автоматически рассчитанное от основного акцентного цвета, можно переопределить вручную в конфигурации.
Параметры
Ниже перечислены все возможные параметры.
| Параметры | Описание |
|---|---|
base-brand |
Основной акцентный цвет. Цвет табов, цитат, активных переключателей. |
base-background |
Фон страницы. |
base-selection |
Выбранная страница в оглавлении и выбранный пункт дропдауна. |
base-simple-hover |
Цвет при наведении на элементы интерфейса. |
quote |
Цвет цитат. |
tab-active |
Цвет активного таба. |
tab-text |
Цвет текста табов. |
tab-text-hover |
Цвет текста табов при наведении. |
link |
Цвет ссылок. |
link-hover |
Цвет ссылок, текста табов, радиобаттонов, пункта аккордиона при наведении. |
term-dfn-background |
Фон всплывающих подсказок. |
text-primary |
Основной текст, текст в таблицах. |
text-secondary |
Цвет второстепенного текста. Пункты оглавления, значки настроек, языка и т.д. |
line-generic |
Цвет линии между элементами страницы, внешние рамки таблицы, общая линия табов, общая линия оглавления статьи. |
code |
Цвет текста в блоке кода. |
code-background |
Фон блока кода. |
inline-code |
Цвет текста в фрагменте кода. |
inline-code-background |
Фон фрагмента кода. |
table |
Цвет текста в таблице. |
table-background |
Фон таблицы. |
table-row-background |
Цвет фона выделяющихся рядов таблицы. |
table-border |
Рамка таблицы. |
note-info-background |
Цвет фона в заметке "Примечание" и заметке со своим заголовком. |
note-tip-background |
Цвет фона в заметке "Совет". |
note-warning-background |
Цвет фона в заметке "Важно". |
note-important-background |
Цвет фона в заметке "Внимание". |
mini-toc-border |
Цвет общей линии оглавления статьи. |
mini-toc |
Цвет текста оглавления статьи. |
mini-toc-hover |
Цвет текста оглавления статьи при наведении. |
mini-toc-active |
Цвет текста активного пункта оглавления статьи. |
mini-toc-active-border |
Цвет линии активного пункта оглавления статьи. |
Смотри также: Ajv схема конфигурации темизатора theme.yaml
Подчёркивание и выделение в верхней навигации
Для выбранного пункта верхней навигации доступны две независимые настройки:
Ключ в theme.yaml |
CSS-переменная в theme.css |
Назначение |
|---|---|---|
navigation-active-underline |
--dc-color-navigation-active-underline |
Цвет линии под выбранным пунктом верхней навигации. |
navigation-dropdown-selected-background |
--dc-color-navigation-dropdown-selected-background |
Цвет фона выбранного пункта в выпадающем меню навигации. |
Эти настройки не меняют общие цвета Gravity UI, включая base-brand и base-selection, и не задают цвет текста или состояния наведения. Параметр tab-active относится к табам в содержимом документа, а mini-toc-active-border — к линии активного пункта оглавления статьи.
Пример theme.yaml:
navigation-active-underline: '#0066cc'
navigation-dropdown-selected-background: '#e6f0ff'
light:
navigation-active-underline: '#0055aa'
dark:
navigation-active-underline: '#80bfff'
navigation-dropdown-selected-background: '#253850'
Общие значения применяются к обеим темам; значения в light и dark переопределяют их для соответствующей темы. Если ключ не задан, CLI не выпускает для него CSS-переменную и сохраняется стандартное оформление.
Для применения этих настроек нужны версия CLI и схема @diplodoc/ajv, поддерживающие новые ключи, а также интерфейс документации, использующий указанные CSS-переменные.
Определение base-brand при сборке
При отсутствии файла конфигурации цвет base-brand может быть задан с помощью ключа запуска --theme
Например:
yfm build -i ./input-folder -o ./output-folder --theme green
Так же цвет base-brand может быть задан с помощью настройки в корневой секции .yfm.
Например:
theme: green
Если одновременно заданы и настройка в .yfm, и флаг --theme, то флаг будет приоритетнее.
Если одновременно заданы и файл конфигурации, и флаг --theme, то флаг переопределит параметр base-brand только в основной секции конфигурационного файла. Значения в секциях light и dark останутся без изменений.