Первый экран

Первый экран кратко объясняет ценность страницы или продукта и предлагает следующий шаг. Обычно он открывает лендинг, а не повторяется внутри статьи. Hero владеет смыслом H1, описания, действий и изображения, а outer width, container, фон и overlay строит общая Surface presentation. Автор не пишет Surface вокруг Hero: double wrapping не поддерживается.

Без фонового изображения Hero использует лёгкую токенизированную заливку с полупрозрачными акцентами. Она автоматически следует светлой и тёмной теме; проекту не требуется добавлять собственные цвета или CSS.

Общий пример

Общий примерMarkdown

Документация, которую удобно создавать и читать

Docara превращает Markdown и проверенные JSON-настройки в быстрый статический сайт.

Открыть быстрый старт

Markdown

content_copyCopy

:::hero {variant=split}
# Документация, которую удобно создавать и читать

Docara превращает Markdown и проверенные JSON-настройки в быстрый статический сайт.

[Открыть быстрый старт](../../start/)

![Компоненты Docara](../../assets/docara-components.png)
:::

Компоновка

padding=lg|xl регулирует внутренние отступы независимо от варианта. compact по умолчанию использует lg, остальные варианты — xl. На узком экране оболочка всё равно уменьшает отступ до безопасного мобильного значения.

Изображение

media задаёт семантику единственного Markdown-изображения:

Явный смысловой side-media вариант:

:::hero {variant=split media=side}
# Документация, которую удобно читать

Один смысловой скриншот остаётся частью содержания.

![Интерфейс документации](/assets/docara-screen.png)
:::

Фоновый режим использует уже написанное Markdown-изображение — отдельного image или background_image свойства у Hero нет. Файл должен существовать в assets/; внешние URL, data URI, переходы по каталогам, symlink и hardlink отклоняются до рендера.

:::hero {media=background background_fit=cover background_x=center background_y=center overlay=dark overlay_strength=medium}
# Документация без лишней сложности

Содержимое остаётся читаемым поверх токенизированного затемнения.

![](/assets/docara-screen.png)
:::

Параметры background_fit=cover|contain|auto, background_x=left|center|right, background_y=top|center|bottom, overlay=light|dark и overlay_strength=soft|medium|strong доступны только при media=background. Их значения по умолчанию: cover, center, center, dark и medium.

:::hero {variant=compact padding=xl}
# Короткое введение

Компактный вариант подходит для внутренней страницы без изображения.
:::

:::hero {variant=centered}
# Начните с пустого каталога

Одна команда создаст проверяемую структуру сайта.

[Открыть быстрый старт](../../start/)
:::

Фоновый эффект

Первый экран может рисовать фоновый эффект из каталога эффектов SIMAI Framework. Эффект подключает Framework (SF.Effects): Docara только записывает в секцию Hero атрибуты data-sf-effect, data-sf-effect-theme и data-sf-effect-settings, а загрузчик Framework находит секцию, проверяет файлы эффекта по индексу каталога и рисует его под содержимым.

:::hero {variant=centered effect="aurora-curtain" effect_theme=auto effect_settings='{"speed": 80}'}
# Документация, которую удобно читать

Эффект рисуется под текстом и не мешает читать.
:::

Тему области задаёт Framework: секция получает класс theme-dark или theme-light той схемы, которую эффект действительно рисует, и текст Hero следует за ней. Если эффект не умеет рисовать нужную схему, Framework скрывает его, а секция получает тему страницы.

Каталог задаётся один раз для сайта в docara.json; сборка записывает его в SF_BOOT_CONFIG.effects:

{
  "effects": {
    "catalogue": "https://cdn.jsdelivr.net/gh/simai/ui-effects@<commit>/",
    "index": "catalogue/index.json",
    "index_sha256": "<64 hex>"
  }
}

catalogue — адрес каталога, закреплённый на коммите, а не на ветке. index и index_sha256 необязательны: путь к индексу внутри каталога (по умолчанию catalogue/index.json) и его SHA-256, если индекс тоже нужно проверять.

Сборка остановится, если:

• значение effect, effect_theme или effect_settings не проходит проверку (MARKDOWN_HERO_EFFECT_INVALID, MARKDOWN_COMPONENT_ATTRIBUTE_VALUE_INVALID, MARKDOWN_HERO_EFFECT_SETTINGS_INVALID);
• effect_theme или effect_settings заданы без effect (MARKDOWN_HERO_EFFECT_REQUIRED);
• эффект сочетается с media=background (MARKDOWN_HERO_EFFECT_MEDIA_CONFLICT): фоном служит либо эффект, либо изображение;
• в docara.json нет effects.catalogue (EFFECTS_CATALOGUE_REQUIRED);
• адрес эффекта лежит вне каталога (EFFECTS_OUTSIDE_CATALOGUE): Framework запускает только эффекты каталога.

Эффекты работают с парой SIMAI Framework, в которой есть SF.Effects: ui-08c07b3e938a или новее. С более ранней парой атрибуты остаются в разметке, но эффект не рисуется, а Hero выглядит как без эффекта.

Содержимое

Блок начинается с одного H1, затем содержит один или два абзаца. После них можно добавить до двух безопасных ссылок-действий и одно изображение. Для side его alt осмысленный, для background — пустой, а none запрещает изображение.

Вызов

:::hero {variant=compact}
# Короткий заголовок

Одно понятное объяснение ценности страницы.
:::

Не вкладывайте в первый экран другие типизированные директивы или Smart-компоненты. Для объявления внутри обычной статьи используйте баннер. Не оборачивайте Hero в Surface: это не добавляет ширины и отклоняется как недопустимое вложение.