Брендирование сайта

Брендирование задаёт логотип, видимое название, необязательную подпись и favicon. Эти файлы принадлежат проекту: обновление Docara не должно заменять их. Компоновку выполняет Smart-компонент docara.brand, поэтому в настройках не нужны HTML, путь к template или CSS-классы.

1. Подготовьте файлы

Положите изображения в корневой каталог assets:

assets/
  logo.svg
  favicon.ico

Используйте относительные пути без .., обратных слешей и начального /. Символический link вместо файла не допускается. Для SVG задайте viewBox, чтобы изображение масштабировалось на узких экранах.

2. Настройте docara.json

Ниже приведён полный минимальный файл сайта с брендингом:

{
  "schema": "docara.site.v1",
  "title": "Acme Docs",
  "preset": "docs",
  "content_root": "content/ru",
  "framework_lock": "simai-framework.lock.json",
  "default_locale": "ru",
  "base_url": "/",
  "branding": {
    "title": "Acme",
    "mode": "compact",
    "size": "medium",
    "logo": "assets/logo.svg",
    "favicon": "assets/favicon.ico"
  }
}

branding.title — имя продукта и доступное название ссылки на главную. Оно обязательно даже в режиме только с логотипом. Один branding.logo используется в светлой и тёмной теме. Поле logo_dark добавляйте только тогда, когда у бренда действительно есть отдельный файл для тёмного фона.

branding.mode управляет только компоновкой:

branding.label — короткая вторая строка, например «Документация» или «API». Она выводится только в full и text; не добавляйте её только ради заполнения места. branding.size принимает small, medium или large. Размер меняет всю брендовую группу по шкале SIMAI Framework. Длинное название остаётся в одну строку и сокращается многоточием, не ломая кнопки header.

Например, вариант только с логотипом:

{
  "schema": "docara.section.v1",
  "branding": {
    "mode": "logo",
    "size": "medium"
  }
}

header — это область макета, а не компонент. По умолчанию в ней находится системная секция docara.header, которая вызывает Smart-компонент docara.brand. Компонент получает уже проверенный объект branding; вставлять HTML логотипа или путь к template в авторский JSON не нужно.

3. Переопределите бренд только для ветки

В content/api/section.json можно изменить подпись для каталога и потомков:

{
  "schema": "docara.section.v1",
  "branding": {
    "label": "API Reference",
    "mode": "full"
  }
}

Остальные поля наследуются из docara.json. Если нужен полностью другой набор, начните объект с "$reset": true и явно задайте все необходимые поля.

4. Проверьте результат

php vendor/bin/docara build production
php vendor/bin/docara verify-static build_production
php vendor/bin/docara serve production --host=127.0.0.1 --port=8000 --no-build

Проверьте header, favicon, светлую и тёмную темы, затем остановите preview через Ctrl+C. Если asset отсутствует или выходит за пределы проекта, сборка должна остановиться до замены прежнего output.

Далее: области и их содержимое и наследование настроек.