Темизация

Статья обновлена 13 ноября 2026 г.

Темизация настраивает визуальное оформление документации.

Управлять темой документации можно с помощью конфигурационного файла 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-selection
  • link
  • link-hover
  • tab-active
  • tab-text
  • tab-text-hover
  • quote

Любое значение переменной, автоматически рассчитанное от основного акцентного цвета, можно переопределить вручную в конфигурации.

Параметры

Ниже перечислены все возможные параметры.

Параметры Описание
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 останутся без изменений.