Сборка для портала

Портал собирает несколько продуктов в один сайт, например https://simai.io/: каждый продукт занимает свой путь (/ru/docara/docs/), а портал владеет главной страницей, языковым префиксом и файлами хостинга. Секция portal в docara.json собирает сайт для такого пути, а команда portal-artifact упаковывает результат в три файла релиза, которые портал скачивает, проверяет и раскладывает по своим путям.

Настройка

Портальная сборка — это отдельная конфигурация сайта: один язык, путь портала в base_url, полный адрес в site_url и секция portal.

{
  "default_locale": "ru",
  "locales": {
    "ru": {
      "label": "Русский",
      "direction": "ltr",
      "content_root": "content/ru",
      "public_prefix": "",
      "fallbacks": []
    }
  },
  "locale_routing": {
    "strategy": "default_unprefixed",
    "root": "default_locale",
    "detect_browser_language": false,
    "legacy_unprefixed_redirects": false
  },
  "base_url": "/ru/docara/docs/",
  "site_url": "https://simai.io/ru/docara/docs/",
  "portal": {
    "product": "docara-docs",
    "home_url": "https://simai.io/ru/",
    "home_label": "simai.io"
  }
}

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

• не задан site_url (PORTAL_SITE_URL_REQUIRED);
• языков больше одного (PORTAL_SINGLE_LOCALE_REQUIRED): каждый язык собирается отдельно под свой путь портала;
• locale_routing.strategy не default_unprefixed (PORTAL_UNPREFIXED_ROUTING_REQUIRED): языковой префикс уже входит в путь портала, поэтому внутри сайта страницы лежат без префикса.

Сайт без секции portal собирается как обычно.

Что меняется в сборке

• canonical каждой страницы — полный адрес на портале: site_url плюс маршрут страницы.
• Шапка начинается со ссылки на portal.home_url и помечена data-portal-shell="header", подвал — data-portal-shell="footer". По этим атрибутам портал проверяет переход на общую оболочку.
• llms.txt остаётся в сборке и ссылается на страницы и _docara/page-metadata.json по адресам портала. sitemap.xml и robots.txt не создаются: их пишет портал.
• Если контент или ассеты публикуют CNAME, .nojekyll, robots.txt, sitemap.xml или 404.html в корне сборки, сборка останавливается с PORTAL_FILE_COLLISION.
• Ссылки контента, написанного для сайта с языковым префиксом, ведут на страницы без префикса: [Старт](/ru/start/) в сборке для /ru/docara/docs/ становится /ru/docara/docs/start/. Ссылки от корня сайта (/start/) работают так же.
• Поисковый индекс, ассеты, медиа и кадры примеров лежат внутри сборки и адресуются под base_url.

Собирайте и проверяйте портальную сборку как любую другую:

php vendor/bin/docara build portal
php vendor/bin/docara verify-static build_portal

verify-static для портальной сборки проверяет llms.txt и отсутствие файлов портала; ошибки выводятся с reference: "@discovery-files".

Упаковка релиза

php vendor/bin/docara portal-artifact [environment] --release=TAG --repository=OWNER/NAME --commit=SHA [--product-version=VERSION] [--output=DIR]

Команда читает build_<environment> (по умолчанию build_production) и секцию portal из docara.json и пишет в --output (по умолчанию build_<environment>.portal/):

<version> — значение --product-version или --release без начальной v.

php vendor/bin/docara portal-artifact portal \
  --release=v3.4.0 \
  --repository=simai/docara \
  --commit="$(git rev-parse HEAD)" \
  --output=portal-out

Квитанция:

{
    "schema": "simai.io.portal-artifact",
    "version": 1,
    "product": "docara-docs",
    "release": "v3.4.0",
    "repository": "simai/docara",
    "commit": "<40 hex>",
    "locale": "ru",
    "base_path": "/ru/docara/docs/",
    "archive": "docara-docs-3.4.0-portal.tar.gz",
    "sha256": "<64 hex>",
    "files": 1706,
    "framework_pair": "ui-<12 hex>",
    "docara_version": "3.4.0"
}

files — число файлов в архиве, framework_pair — пара SIMAI Framework, которую загружают страницы, docara_version — версия Docara, упаковавшая сборку.

Перед записью команда проверяет сборку и останавливается с PORTAL_PAGE_INVALID, PORTAL_FILE_COLLISION, PORTAL_INDEX_MISSING или PORTAL_BUILD_LINK, если:

• в сборке есть символическая ссылка или файл портала;
• в корне нет index.html;
• у страницы нет <html lang> языка сборки, непустого <title>, описания или ссылки на главную портала;
• canonical страницы лежит вне site_url;
• страницы загружают разные пары Framework.

Страница без description во front matter получает описание из первого абзаца. Если абзаца нет, добавьте description во front matter. Redirect-страницы описания не требуют: их canonical ведёт на цель внутри base_url.

Воспроизводимость архива

Архив собирается так, чтобы одинаковая сборка давала одинаковые байты:

• записи tar отсортированы по пути, каталоги идут перед своим содержимым;
• у каждой записи время изменения 0, владелец root (0:0), права 0644 для файлов и 0755 для каталогов;
• заголовок gzip фиксирован: без имени файла, со временем 0 и с неопределённой операционной системой.

Сжатые байты зависят от реализации zlib, поэтому сравнивайте архивы, собранные на одной платформе. Каноническим считается архив из CI; портал закрепляет его SHA-256 из квитанции.

Проверка после скачивания:

sha256sum -c docara-docs-3.4.0-portal.tar.gz.sha256
jq -r .sha256 docara-docs-3.4.0-portal-receipt.json

Оба значения должны совпасть.