Архитектура
Основной пакет simai/docara владеет CLI, JSON schemas, разрешением
наследования, Markdown renderer, Framework adapter, starter и статической
сборкой.
Проект определяется наличием docara.json со schema docara.site.v1.
Поток portable-сборки:
- Загрузить и проверить site, section, page и Framework lock.
- Разрешить наследование и provenance каждой страницы.
- Один раз скомпилировать Markdown и Smart-вызовы в типизированный
DocumentIrв памяти. - Подготовить страницу, области, секции и блоки из проверенных настроек. Превратить эту структуру в Recipe, передать стандартному сборщику SIMAI Framework и получить готовый Composition Document. Вход PHP-рендерера восстановить из этого проверенного документа.
- Построить маршруты и каноническую топологию.
- Получить из одной топологии видимое меню, breadcrumbs и previous/next.
- Отрендерить содержимое через единый registry/Smart gateway, а regions — через зарегистрированные templates и immutable view models.
- Построить производные индекс, меню, breadcrumbs, outline, previous/next, search и эффективный machine-readable каталог из результатов PageBuilder.
- Собрать кандидатный полный документ через зарегистрированный publisher template и передать его общему Framework Asset Planner.
- По существующему Loader registry определить точные CSS/JS и зависимости первого кадра, повторно собрать документ с этим планом и проверить его устойчивость по финальному HTML.
- Записать HTML, content-hashed CSS, отдельные Framework receipts страниц, search index и остальные plans.
- Только после полного успеха транзакционно заменить действующий
build_*.
Каноническая топология содержит все страницы, включая скрытые. Проекция меню отбрасывает скрытые листья, но сохраняет видимые дочерние ветви. Breadcrumbs и соседние страницы используют каноническую модель, поэтому UI-поверхности не расходятся по пути или порядку.
TOC builder работает с безопасным HTML Markdown до подстановки
Smart-компонентов. Он назначает H1–H6 уникальные Unicode id, а компонент
docara.toc выводит H2–H6 только до reading.toc_depth. В конфигурации правая
область называется outline: это стабильный layout key, а не имя
компонента.
Источники и производные поверхности
resources/component-catalog/native,typed,smartиrequirementsсодержат owner-записи возможностей;- exact Framework lock и manifests ограничивают Smart admission;
EffectiveComponentCatalogBuilderсоздаёт один проверяемый каталог;- страницы компонентов принадлежат Markdown, а их индекс строится из метаданных результатов PageBuilder без generated index/detail projector;
_docara/component-catalog.json, HTML и диагностический receipt являются производными результатами, а не вторым источником истины.
Техническая canonical-запись компонента хранит стабильный ID, контракт и
lifecycle. Текст каждой русской публичной страницы находится в одном Markdown,
а повторяющиеся интерфейсные подписи — в content/ru/lang.json. Package-owned
fixtures и данные других локалей не являются владельцами русской страницы.
Все страницы проходят через один PageBuilder и общий Composition Recipe
resolver Framework. Markdown сначала получает типизированное представление
DocumentIr, а готовая структура всей страницы — Composition Document.
Это разные документы: первый описывает прочитанный Markdown, второй —
результат сборки страницы вместе с областями, секциями и блоками.
Layout composer принимает типизированный
PageBuilder artifact; сырого trustedMainHtml, generated-page bypass и
публичных page projector нет.
Файлы являются источником истины; база данных, runtime CRUD, роли и workflow не входят в standalone Docara.
resources/publisher/templates/page.php является только host-шаблоном
документа. Элементы publisher chrome находятся в зарегистрированных шаблонах
resources/publisher/components; product Smart-шаблоны, manifest и их CSS/JS
— в resources/smart. В resources/portable остаётся общая геометрия shell и
поведение уровня документа. Builder не содержит HTML, CSS или client runtime.
Для сборки нужны PHP и Node.js. Закреплённая generated-поставка SIMAI Framework, включая среду выполнения Composition Recipe, входит в пакет Docara. Node.js запускает общий Recipe resolver один раз на всю сборку; автору не нужно заводить отдельный frontend-проект. Готовый сайт остаётся статическим: для его публикации PHP и Node.js не нужны.
Если node отсутствует в PATH, укажите путь к Node.js:
export DOCARA_NODE_BINARY=/path/to/node
php vendor/bin/docara build production
Необязательная переменная DOCARA_SIMAI_UI_ROOT (или SIMAI_UI_ROOT)
направляет сборку на другую поставку Framework, которая реализует ту же
спецификацию Recipe. Для обычной сборки она не нужна.
Каждая страница получает отпечатки Recipe и готового Document в отчёте сборки. Ошибка проверки останавливает создание кандидата и сохраняет предыдущий результат. Два варианта страницы показывают явную Recipe, которая выбирает шапку по настройке; для обычных страниц Recipe создаётся автоматически.