Области макета

Макет docara.docs состоит из пяти именованных областей:

sidebar и outline выводятся семантическими элементами aside. outline — устойчивое техническое имя правой области; в интерфейсе она называется «Содержание страницы». Отдельной области с именем aside нет.

Простое включение и отключение

Чтобы отключить левое меню и правое оглавление на отдельной странице, добавьте в её sidecar:

{
  "schema": "docara.page.v1",
  "layout": {
    "regions": {
      "sidebar": { "enabled": false },
      "outline": { "enabled": false }
    }
  }
}

В результате остаётся шапка и основное содержимое, а оба aside и мобильная кнопка меню отсутствуют в HTML. Открыть живой пример, результат и точные исходники.

Настройку можно положить в:

• docara.json — для всего сайта;
• section.json — для раздела и всех потомков;
• <page>.page.json — только для соседней Markdown-страницы.

Поздний уровень меняет только явно указанные области.

Сравнить включённые области, готовые shell-рецепты, наследование, оба preset и Smart-компоненты можно в демонстраторе декларативных макетов. Его результаты собираются тем же основным генератором, что и весь сайт.

Из чего собирается область

Расширенная форма использует ту же последовательность, что и Larena:

Page -> Region -> Section -> Block -> Smart

Например, стандартная левая навигация описывается так:

{
  "layout": {
    "regions": {
      "sidebar": {
        "enabled": true,
        "sections": [
          {
            "id": "docs-navigation",
            "section": "docara.navigation"
          }
        ]
      }
    }
  }
}

Стандартные секции содержат только устойчивый ID экземпляра и ссылку на зарегистрированную секцию. Слоты, блок shell.smart, Smart-компонент, maximum_depth и привязка данных находятся в определении resources/sections/docara.navigation.json, а не копируются на каждую страницу:

Секция — это зарегистрированный рецепт наполнения области. Smart-компонент — самостоятельный интерфейсный элемент с manifest, props, views, шаблонами, assets и readiness. Поэтому docara.header сохранён как имя секции, но компонент бренда называется docara.brand; docara.outline сохранён как имя секции, а компонент содержания страницы называется docara.toc.

Другую комбинацию стандартной секции сборка отклонит.

Собственная композиция области

Для практического наполнения используйте зарегистрированную секцию docara.shell. Она принимает устойчивые ID блоков, проверенные утилиты Simai Framework и два типа вызовов:

• shell.element — один безопасный семантический элемент с текстом и, для a, локальным href;
• shell.smart — зарегистрированный Smart с props, проверенными по его точному manifest. Если Smart читает данные оболочки, bind выбирается только из typed BindingRegistry и должен соответствовать capability области.

Минимальный footer:

{
  "layout": {
    "regions": {
      "footer": {
        "enabled": true,
        "sections": [
          {
            "id": "site-footer",
            "section": "docara.shell",
            "utilities": ["flex", "flex-col", "gap-1", "p-2", "surface-0"],
            "blocks": [
              {
                "id": "copyright",
                "block": "shell.element",
                "slot": "content",
                "element": {
                  "tag": "p",
                  "text": "Docara — документация как код.",
                  "utilities": ["m-0"]
                }
              }
            ]
          }
        ]
      }
    }
  }
}

Это не строка HTML. Автор выбирает только разрешённый тег, текст, локальную ссылку и утилиты из точной Framework projection. PHP, Blade, raw HTML, обработчики событий, JavaScript URL, style/class string, callback и пути к шаблонам остаются недоступны.

Для навигации доступны три зарегистрированных presentation-варианта: header, tree и compact. Они принадлежат одному docara.navigation и проходят тот же Gateway. Пример блока внутри совместимой секции:

{
  "id": "navigation",
  "block": "shell.smart",
  "slot": "content",
  "smart": "docara.navigation",
  "view": "compact",
  "bind": "docara.navigation",
  "props": {"maximum_depth": 4}
}

Поля items, label, expand_label, collapse_label и contains_current_label принадлежат binding и не задаются вручную.

Живые исходники:

• брендированный header;
• sidebar с дополнительным блоком;
• aside с оглавлением и Alert;
• footer из безопасных элементов.

Как формируется разметка

Layout и Section ссылаются на зарегистрированные безопасные View Tree:

Layout View Tree -> Region
Section View Tree -> Slot -> Block -> Smart

View Tree хранится в resources/views/*.json. Он допускает только ограниченный набор семантических тегов, безопасные атрибуты и точную проекцию утилит Simai Framework. Неизвестный класс, тег, повторная область или повторный слот завершают сборку ошибкой. Сложные presentation leaves могут использовать Blade только через внутренний реестр Docara; путь к Blade никогда не поступает из авторского файла.

Что нельзя отключить

main обязателен для docara.docs. Значение layout.regions.main.enabled: false завершает сборку ошибкой DECLARATIVE_REQUIRED_REGION_DISABLED.

Если нужен принципиально другой каркас, следует зарегистрировать другой layout, а не нарушать контракт существующего.

Наследование и provenance

sections является массивом: поздний массив целиком заменяет унаследованный. Частичное изменение enabled не затрагивает унаследованный список секций. ID секций и блоков обязаны быть уникальными и сохраняют детерминированный порядок массива. Живой пример трёх уровней с reset показывает итог docara.json → section.json → page.page.json.

Итог и владеющий файл находятся в:

build_<environment>.docara/resolved-page-plans.json

Проверьте configuration.layout.regions и соответствующие pointers вида /layout/regions/sidebar/enabled в provenance.

Далее: архитектура Smart-компонентов и живой пример product Smart-компонентов.