Статический результат

Собранный каталог содержит HTML страниц, копии контентных ассетов и служебные Framework-ассеты. Рядом с ним Docara кладёт квитанции сборки — они описывают, как собран сайт, и не публикуются:

build_production/                  публикуется целиком
  index.html
  section/page/index.html
  _docara/search-index.json
  _docara/search.js
  _docara/docara-shell.<sha256>.css   общие стили первого кадра, несколько на страницу
  _docara/framework/
  _docara/vendor/simai-framework/runtime/<revision>/
  old/route/index.html
build_production.docara/           квитанции сборки, не публикуются
  resolved-page-plans.json
  redirects.json
  locale-routes.json
  performance.json
  examples.json
  …

Каталог build_production/ можно копировать на хостинг как есть: служебных файлов сборки в нём нет. Квитанции из build_production.docara/ читают verify-static, однострочная пересборка build --page, preview и inspect. Сайт, собранный Docara 3.0.0, хранил их внутри результата в .docara/; такие каталоги по-прежнему проверяются, но при новой сборке квитанции переезжают наружу.

В _docara/vendor/ попадает только то, чем пользуются собранные страницы. Mermaid публикуется, если хотя бы одна страница содержит диаграмму, KaTeX со шрифтами — если есть формула, начертания значков Rounded и Sharp — если разметка, скрипт примера или собственные стили сайта запрашивают это семейство, полный utility.full.css Framework — если страница на него ссылается. Лицензия библиотеки публикуется вместе с ней. Подмножество значков и полный шрифт Outlined публикуются всегда: значки вне подмножества Smart компоненты выбирают уже в браузере. verify-static заново вычисляет этот выбор по страницам и сообщает @vendor-asset-selection, если нужного файла нет или он отличается от файла пакета.

HTML можно обслуживать обычным статическим веб-сервером. Значение base_url должно совпадать с префиксом размещения: / для корня домена или безопасный путь вроде /project/docs/ для вложенного размещения.

Файлы поиска появляются только когда search.enabled: true хотя бы для одной страницы. Индекс строится до очистки destination, проходит JSON Schema и содержит только URL опубликованных страниц, locale, заголовки, описания, навигационный путь и видимый текст. Браузер загружает его лениво. Индекс и runtime имеют независимые SHA-256 query revisions.

Проверка артефакта читает base_url из resolved-page-plans.json: совпадающий deployment-префикс удаляется перед поиском файла внутри build-каталога, а похожий или посторонний абсолютный путь отклоняется.

Verifier требует exact schema manifest, непустой список страниц и точное совпадение его output и redirect receipt со всеми HTML-файлами результата. Отсутствующий, дублированный, лишний, symlink- или hardlink-output отклоняется. Элемент HTML <base> запрещён, чтобы относительные quoted href/src всегда разрешались одинаково verifier-ом и браузером.

Если redirects_file не пуст, квитанция redirects.json фиксирует SHA-256 source, locale, версию документации, base_url, source/target URL и output каждого redirect. Redirect HTML содержит canonical, noindex, meta refresh и обычную видимую ссылку на один и тот же внутренний target.

Локальные ссылки с #fragment проверяются против фактических HTML id — как в сыром Unicode, так и в percent-encoded форме. Основные диагностические маркеры:

Любой из этих маркеров делает проверку артефакта неуспешной.

Текущий lock публикует необходимые Docara файлы SIMAI Framework локально: Core, используемые utilities, нужные Docara webpack/language chunks, Inter, Material Symbols и допущенные Smart assets. Страница не зависит от runtime-загрузки с CDN.

Перед первым отображением общий production Asset Planner SIMAI Framework анализирует готовый HTML страницы по тем же правилам distr/rule/rule.json, которые использует динамический Loader. Он раскрывает зависимости и подключает точный набор CSS страницы и геометрию Docara в порядке каскада.

Эти CSS публикуются несколькими общими файлами docara-shell.<sha256>.css, имя которых определяется содержимым. Когда собраны все страницы, Docara группирует их исходные CSS в файлы, которые подходят сразу многим страницам: большая общая часть — один файл для всего сайта, частые наборы компонентов — свои файлы, редкие — небольшие отдельные. Страница подключает только нужные ей CSS, ничего лишнего, в среднем 4–6 файлов вместо полусотни; браузер кеширует их между страницами. Общий объём файлов ограничен двойным объёмом различных исходных CSS сайта.

Каскад страницы не меняется. Файл — это точные байты его исходных CSS подряд. Два исходных CSS меняются местами только тогда, когда порядок между ними не может повлиять ни на одно объявление: у них нет общего свойства в одном слое каскада (сокращённые записи, логические и физические свойства и префиксные псевдонимы считаются одним свойством) и нет одноимённых @keyframes, @property, @font-face и подобных правил. Порядок слоёв задаёт core.css Framework, который подключается раньше. Всё, что анализ не понимает, остаётся на своём месте. Нужные JavaScript-модули подключаются в порядке зависимостей до Core, а window.SF_PRELOADED перечисляет только фактически опубликованные ресурсы. Поэтому Loader не загружает их повторно после первого отображения и остаётся ответственным только за содержимое, появившееся позднее.

Docara является первым потребителем этого общего build-time механизма, а не владельцем отдельного списка Framework-компонентов. Проект без production планирования продолжает работать по прежней динамической схеме через sfPath, sfSmartPath, core.css и core.js. Редкий ресурс первого кадра, который невозможно увидеть в итоговом HTML, можно явно назвать через необязательный data-sf-require.

Те же ранние ресурсы включают используемые подмножества Inter и Material Symbols. Обычный fenced code-блок сразу получает серверный заголовок языка той же геометрии, что и итоговая интерактивная панель копирования. Это не глобальный скелетон: содержимое страницы доступно сразу, а поздняя регистрация компонентов не меняет размеры каркаса и кодовых блоков.

Пока Inter загружается, Framework использует локальный метрически совместимый fallback. Он сохраняет естественные размеры текста и элементов управления, поэтому подмена шрифта не перестраивает шапку, меню и колонки. Фиксированная высота шапки, скрытие страницы или отдельный проектный кеш для этого не нужны.

resolved-page-plans.json содержит отдельный Framework asset receipt для каждого HTML-output: входные файлы и их SHA-256, порядок JavaScript, список preload-модулей, hash HTML-содержимого и публичные имена generated CSS в порядке подключения. verify-static повторно вычисляет каждый план по финальному HTML и отклоняет ложный preload, изменённый CSS, отсутствующий ресурс, stale receipt или другой порядок подключения. В точном production-режиме utility.full.css не публикуется.

На статическом хостинге рекомендуется разделить кеширование:

• файлы с SHA-256 в имени — Cache-Control: public, max-age=31536000, immutable;
• HTML — без immutable, с обычной проверкой актуальности (ETag или Last-Modified).

Это не превращает произвольный upstream-компонент в поддерживаемый: admission по-прежнему определяется manifest, provider policy и exact lock.

Публичную production или release готовность следует заявлять только после отдельной приёмки конкретного артефакта и условий распространения.