11 Эффективное использование тем и брендирование в Quarto

11.1 Встроенные темы

В Quarto можно использовать встроенные темы на основе Bootstrap 5 для определения того, как будет выглядеть веб-страница. Посмотреть, как будут выглядеть данные темы, можно на сайте Bootswatch (Free themes for Bootstrap), полный список тем на выбор доступен на странице HTML Theming. Для определения темы используется параметр theme как в конструкции ниже.

format:
  html:
    theme: cosmo # тема настоящей книги
    # несколько примеров других тем:
    # theme: flatly
    # theme: pulse
    # theme: sketchy

Одна из возможностей для оформления темы веб-страницы — использование светлой и темной темы. Для указания тем нужно использовать параметры light и dark при использовании theme в YML.

format:
  html:
    theme: 
      dark: flatly
      light: darkly

Замечание

Подбирайте темы для светлого и темного режимов как можно более схожие по шрифтам и другим визуальным элементам, например, flatly/darkly, cyborg/lux.

Начиная с версии 1.7 в Quarto можно установить параметр для html, автоматически переключающий тему на темную или светлую в зависимости от настроек операционной системы или браузера.

_quarto.yml

format:
  html:
    respect-user-color-scheme: true

Еще одна возможность (реализованная в данной книге) — использовать расширение quarto-auto-dark, которое автоматически применяет темный режим в зависимости от настроек операционной системы. Для установки необходимо использовать команду:

Terminal

quarto add gadenbuie/quarto-auto-dark

и далее установить в YML:

_quarto.yml

# установите только(!) светлую тему
theme:
  light: flatly

# включите автоматический переход на темную тему
filters:
  - auto-dark

Существует возможность создания собственных тем, например, это можно сделать на базе существующих SCSS Bootswatch-тем для Quarto, которые можно кастомизировать и добавить как показано ниже.

format:
  html:
    theme: custom.scss

11.2 Использование CSS и Sass в Quarto

CSS

Mozilla Web Docs

Quarto Websites 3: Customize appearance with CSS/SCSS | Emil Hvitfeldt | Posit

https://www.youtube.com/watch?v=PL3Odw-k8W4&ab_channel=Coding2GO

How to style your Quarto docs without knowing HTML & CSS

11.3 Брендирование

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

Благодаря такому подходу можно унифицировать внешний вид публикаций, создаваемых с помощью Quarto, а также обеспечивает совместимость с другими инструментами экосистемы Posit, такими как Shiny (как в R, так и в Python), поддерживать единые брендовые стандарты при разработке отчетов, презентаций, веб-приложений, дэшбордов и других материалов. Применение файла _brand.yml в проектах Quarto позволяет автоматически применять единые заданные стили ко всем выходным документам, гарантируя стильный и продуманный внешний вид без необходимости ручной настройки тем.

Замечание

Подробную документацию и примеры по использованию брендинга с помощью YAML-файла _brand.yml можно посмотреть на веб-сайте BRAND.YML, большой справочник функций можно посмотреть в разделе Brand на сайте Quarto.

Покажем, как будет выглядеть веб-страница, сгенерированная на его основе различных файлов _brand.yml:

веб-сайт Примера 1 | файл с настройками _brand.yml;
веб-сайт Примера 2 | файл с настройками _brand.yml.

В настоящий момент _brand.yml может содержать в своей структуре следующую информацию:

метаданные (meta) для хранения общей информации о компании или проекте, описанных в файле;
логотип (logo) позволяет определять и организовывать логотипы и фирменные изображения для проекта;
цвет (color) определяет цветовую палитру бренда и цвет темы;
типографика (typography) позволяет определить шрифты, размеры, насыщенность и другие типографические свойства;
настройки по умолчанию (defaults) хранит переменные или параметры формата, которые имеют отношение к брендингу, привязанные к определенному формату вывода или контексту.

Рассмотрим эти компоненты более подробно.

11.3.1 Метаданные

В разделе meta могут указываться метаданные о компании или проекте, например, название бренда/проекта, гиперссылки для добавления иконок социальных сетей. Кроме основных полей name и link, которые необязательны, здесь можно добавлять дополнительные поля по мере необходимости для вашего конкретного варианта использования и определять как место для хранения дополнительного контекста.

Простой пример использования meta:

_brand.yml

meta:
  name: Университет
  link: https://www.my_university.ru

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

_brand.yml

meta:
  name:
    full: Федеральное государственное автономное образовательное учреждение высшего образования «Национальный исследовательский университет»
    short: Университет
  link:
    home: https://www.my_university.ru
    docs: https://docs.my_university.ru
    github: https://github.com/my_university
    mastodon: https://https://mastodon.social/@my_university
    telegram: https://t.me/my_university
  description: |
    Приоритетные направления ВУЗа: информационные технологии, искусственный интеллект, фотоника, робототехника, квантовые коммуникации.
  founded: 1900

11.3.2 Логотип

Раздел logoв позволяет определять и организовывать логотипы и фирменные изображения проекта. Здесь поддерживаются различные размеры логотипов, светлые/темные варианты и возможность хранить несколько ресурсов изображений для различных вариантов использования.

Простой пример логотипа в поле logo:

_brand.yml

logo: my_logo.png

Вы можете указать разные логотипы для светлого и темного фона/цветового режима. Для этого необходимо установить дочерние аттрибуты light (для светлого фона) или dark (для темного фона).

_brand.yml

logo:
  light: logos/light-logo.png
  dark: logos/dark-logo.png

Замечание

Отметим, что путь к рисункам может содержать URL-адрес, но онлайн-изображения должны использовать полные адреса, начинающиеся с http:// или https://.

Поле images может содержать несколько ресурсов, на которые можно в дальнейшем ссылаться как атрибуты:

small определяет логотип, используемый для небольших контекстов отображения, таких как значки сайтов или значки мобильных приложений;
medium определяет логотип для контекстов отображения среднего размера, обычно используемых в заголовках веб-сайтов или на панелях навигации;
large определяет логотип для крупных контекстов отображения, таких как титульные слайды или постеры.

Базовая конфигурация для логотипов различных размеров выглядит так:

_brand.yml

logo:
  small: logos/icon.png
  medium: logos/header-logo.png
  large: logos/full-logo.svg

Можно указать логотип бренда и изменить альтернативный текст:

_quarto.yml

logo:
  path: large
  alt: Альтернативный текст

Замечание

Отметим, что логотипы имеют свои предпочтения для отображения, например, для верхней панели навигации в HTML или дэшборде логотипы имеют приоритет small > medium > large, а в Reveal.js-презентациях medium > small > large.

11.3.3 Цвет

Категория color используется в файле _brand.yml для определения цветовой палитры и цветовых значений темы. Последовательность определения следующая:

Сначала определяется палитра набор именованных цветов, характерных для бренда с помощью аттрибутов palette.
Цвета бренда связываются с элементами темы с помощью ссылок на псевдоним (семантические названия цветов), основанных на палитрах из Bootstrap. Такая структура делает дизайн проекта более гибким, автоматически адаптируя темы к брендовым цветам.

Приведем пример определения палитры:

_brand.yml

color:
1  palette:
    white: "#FFFFFF"      
    black: "#151515"      
    blue: "#447099"       
    orange: "#EE6331"     
    green: "#72994E"      
    teal: "#419599"       
    burgundy: "#9A4665"   

2  foreground: black
  background: white       
  primary: blue           
  secondary: "#707073"    
  tertiary: "#C2C2C4"     
  success: green          
  info: teal              
  warning: orange         
  danger: burgundy        
  light: white            
  dark: "#404041"

1: Определение цветов палитры.
2: Использование палитры путем сопоставления с элементами темы.

Обратите внимание, что во второй части _brand.yml можно задавать цвета как в формате HEX (например, dark: #404041◉), так и ссылаться напрямую с помощью стандартных названий цветов (например, dark: black), Файл _brand.yml автоматически преобразует такие именованные значения. Ниже описаны аттрибуты для сопоставления цветов бренда в разделе color для поддержания единообразной цветовой схемы.

Таблица 11.1: Таблица определения цветов темы

Аттрибут	Описание
`foreground`	Основной цвет текста. Обычно он близок к черному и должен хорошо контрастировать с цветом фона.
`background`	Основной цвет фона. Обычно он близок к белому и должен хорошо контрастировать с цветом переднего плана.
`primary`	Основной вспомогательный цвет, используемый для гиперссылок, активных состояний и кнопок основных действий.
`secondary`	Второй вспомогательный цвет, часто используется для светлого текста или неактивных элементов.
`tertiary`	Третичный вспомогательный цвет, используемый для состояний наведения (hover), акцентов и фоновых панелей.
`success`	Цвет, используемый для обозначения успешных действий и информации.
`info`	Цвет, используемый для нейтральных или информационных действий и элементов.
`warning`	Цвет, используемый для обозначения предупреждений или предостерегающей информации.
`danger`	Цвет, используемый для обозначения ошибок, опасных действий или негативной информации.
`light`	Яркий цвет, используемый как контрастный цвет переднего плана на темных элементах или как цвет фона с низким контрастом на светлых элементах.
`dark`	Темный цвет, используемый как контрастный цвет переднего плана на светлых элементах или как контрастный фоновый цвет для светлых элементов.

11.3.4 Типографика

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

Прежде всего указываются шрифты, которые использует бренд, с указанием локальных или онлайн-источников источников шрифтов.
Определяются шрифты и стили, используемые различными типографскими элементами (базовый текст, заголовки, моноширинный текст и т. д.).

Ниже показан подробный пример определения шрифтов.

_brand.yml

color:
  primary: "#f24242"

typography:
1  fonts:
    # Локальные шрифты
    - family: Open Sans
      source: file
      files:
        - path: fonts/open-sans/OpenSans-Variable.ttf
        - path: fonts/open-sans/OpenSans-Variable-Italic.ttf
          style: italic
    # Онлайн шрифты
    - family: Closed Sans
      source: file
      files:
        - path: https://example.com/Closed-Sans-Bold.woff2
          weight: bold
        - path: https://example.com/Closed-Sans-Italic.woff2
          style: italic
    # Google Fonts
    - family: Roboto Slab
      source: google
      weight: [600, 900]
      style: normal
    # Bunny Fonts
    - family: Fira Code
      source: bunny

2  base:
    family: Open Sans
    line-height: 1.25
    size: 1rem
  headings:
    family: Roboto Slab
    color: primary
    weight: 600
  monospace:
    family: Fira Code
    size: 0.9em

1: Раздел с определением шрифтов на основе аттрибута fonts.
2: Раздел с упоминанием шрифтов для использования в Quarto документе.

В качестве источника шрифтов (source) могут выступать шрифты из Google Fonts (source: google), Bunny Fonts как замена Google Fonts (source: bunny) или локальные шрифты (source: file). Здесь перечисляются каждый файл шрифта files с атрибутом path.

Поскольку семейства шрифтов (гарнитуры) могут состоять из нескольких файлов, отвечающих за стиль и начертание, можно перечислить эти файла, указав параметры weight и style шрифта.

Атрибут weight указывает тип начертания шрифта. Например, weight: [600, 900] из примера соответствует значениям начертания 600 и 900. Если оставить это поле пустым, будут включены начертания от 100 до 900.
Атрибут style указывает стили шрифтов. В примере включен только обычный стиль (style: normal). Если оставить это пустым, будут включены как обычные, так и курсивные стили как [normal, italic].

Для шрифтов, которые размещены онлайн, можно использовать тот же подход, что и для выше локальных шрифтов, но вместо локального пути к файлу необходимо указать URL-адрес в атрибуте path.

Приведем возможные параметры для определения шрифтов во второй части файла _brand.yml.

Таблица 11.2: Таблица определения цветов темы

Аттрибут	Описание	Поддерживаемые поля
`base`	Текст по умолчанию, используемый главным образом в основном содержании документа.	`family`, `size`, `line-height`, `weight`
`headings`	Все уровни заголовков (h1, h2 и т. д.).	`family`, `line-height`, `weight`, `style`, `color`
`monospace`	Общий моноширинный текст, обычно используемый в блоках кода и другом контенте, связанном с программированием.	`family`, `size`, `weight`
`monospace-inline`	Встроенный моноширинный текст, обычно используемый для фрагментов кода в обычном тексте. Наследует свойства моноширинного шрифта (`monospace`).	`family`, `size`, `weight`, `color`, `background-color`
`monospace-block`	Блочный (многострочный) текст с моноширинным шрифтом, обычно используемый для блоков кода. Наследует свойства моноширинного шрифта. (`monospace`)	`family`, `size`, `weight`, `line-height`, `color`, `background-color`
`link`	Гиперссылки	`weight`, `color`, `background-color`, `decoration`

Сделаем расшифровку параметров указанных выше.

Таблица 11.3: Таблица основных параметорв шрифтов

Аттрибут	Описание
Семейство (`family`)	Шрифтовое семейство, используемое для типографического элемента. Должно соответствовать шрифтовому ресурсу, объявленному в `typography.fonts`.
Размер (`size`)	Размер шрифта для типографического элемента. Указывается с использованием единиц CSS (например, `14px`, `1em`, `0.9rem`).
Насыщенность (`weight`)	Толщина (жирность) шрифта. Может быть числовым значением от 100 до 900 или строкой, например, `normal` (обычный) или `bold` (жирный).
Стиль (`style`)	Стиль шрифта, обычно `normal` (обычный) или `italic` (курсив).
Высота строки (`line-height`)	Вертикальное расстояние между строками текста. Обычно задаётся как множитель от размера шрифта или в фиксированных единицах.
Цвет текста (`color`)	Цвет текста. Может быть любым значением цвета, совместимым с CSS, или ссылкой на цвет из палитры бренда.
Цвет фона (`background-color`)	Цвет фона текстового элемента. Может быть любым значением цвета, совместимым с CSS, или ссылкой на цвет из палитры бренда.
Декорация текста (`decoration`)	Декоративное оформление текста, часто применяемое для ссылок. Типичные значения: «underline» (подчёркивание), `none` (без декорации), `overline` (линия над текстом).

Отметим, что все части _brand.yml являются необязательными.

Thomas Lin Pedersen написал хорошую статью Fonts in R, которая также в некоторой мере касается использования шрифтов в Quarto, а именно, как применять системные шрифты для использования пользовательских шрифтов в графиках. В Quarto необходимо установить dev опцию как ragg_png, что можно сделать с помощью кода:

#| include: false
knitr::opts_chunk$set(dev = "ragg_png")

либо в YAML

---
title: "My Document"
format: html
knitr:
  opts_chunk:
    dev: "ragg_png"
---

Теперь можно использовать шрифт, установленный на вашем компьютере.

grid::grid.text(
  "FUTURA 🎉", 
  gp = grid::gpar(fontfamily = "Futura", 
                  fontface = 3, 
                  fontsize = 30)
)

Рисунок 11.9: Пример использования шрифта, установленного на компьютере

Стоит упомянуть, что Nan Xiao создал руководство Open Source Typography, по поиску шрифтов из коллекции шрифтов с открытым исходным кодом, которые могут быть использованы для программного обеспечения или веб-сайта. Благодаря интерактивным функциям настройки, позволяющим экспериментировать с типографскими параметрами. Вы можете ввести собственный текст и сразу увидеть, как он будет выглядеть в выбранном шрифте.

11.3.5 Настройки по умолчанию

Отдельные форматы могут не входить в параметры, которые были указаны выше, но могут иметь отношение к брендингу. Как правило, эти параметры привязаны к определенному формату вывода или контексту, поэтому их нельзя включить в основную спецификацию бренда. В настоящее время раздел defaults в Quarto поддерживает раздел bootstrap, который можно использовать для установки значений по умолчанию для переменных Bootstrap Sass.

Например, можно использовать rules в defaults для предоставления правила CSS, как в примере — для удаления границы под заголовками второго уровня:

_brand.yml_

defaults:
  bootstrap:
    # uses: <string>
    # functions: <string>
    # mixins: <string>
    rules: |
      h2 {
        border: none;
      }

В документах Quarto существует возможность ссылаться на параметры brand с помощью shortcodes, например, для указания логотипа бренда:

Quarto

{{< brand logo LOGO_NAME >}}

Замечание

Garrick Aden-Buie написал статью Creating a brand.yml with an LLM с указанием инструкций, как автоматизированно создать файл _brand.yml с помощью большой языковой модели (LLM), например ChatGPT или Claude, что может быть полезным.

В заключение отметим, что включить _brand.yml в документ можно указав в _quarto.yml

_quarto.yml_

theme:
  - cosmo        # предопределенная тема
  - brand        # тематизация, полученная из _brand.yml
  - tweaks.scss  # пользовательская настройка

При этом _brand.yml всегда будет иметь наименьший приоритет. Аналогичный синтаксис также работает для объединения светлых и темных брендов со светлыми и темными темами:

_quarto.yml_

theme:
  light:
    - cosmo
    - brand
  dark:
    - slate
    - brand

Также, светлые и темные бренды можно определить на уровне проекта:

_quarto.yml_

brand:
  light: light-brand.yml
  dark: dark-brand.yml

11.1 Встроенные темы

11.2 Использование CSS и Sass в Quarto

11.3 Брендирование

11.3.1 Метаданные

11.3.2 Логотип

11.3.3 Цвет

11.3.4 Типографика

11.3.5 Настройки по умолчанию

Заключение