FOnline Engine
Current master GitHub
Документация Docs/ru/contributing/decisions/0001-github-pages-markdown-publication.md

ADR-0001: публикация Markdown через GitHub Pages и структура локалей

  • Статус: принято
  • Дата: 2026-07-10
  • Изменено: 2026-08-01 после внедрения локализованного сайта и проверок собранных страниц в браузере
  • Владельцы: документация, сборка и выпуск

Контекст

FOnline уже публикует сайт репозитория через GitHub Pages, использует конфигурацию Jekyll из _config.yml и привязывает производственный домен корневым файлом CNAME = fonline.ru. Исходником документации служит Markdown в репозитории движка. Он должен оставаться читаемым как в интерфейсе репозитория GitHub, так и на публичном сайте.

Программа вывода документации на производственный уровень также требует:

  • самостоятельную документацию движка без файловой зависимости от подключающего проекта;
  • канонический английский текст и полное русское зеркало для страниц, предназначенных людям;
  • стабильные URL, перенаправления, навигацию, поиск и машиночитаемые индексы;
  • проверку pull request по тем же ограничениям, которые действуют в production;
  • отсутствие второго дерева содержимого, сгенерированный результат которого может разойтись с Markdown в репозитории.

Отдельное приложение сайта продублировало бы владение и вынесло бы контракт публикации за пределы системы, которая уже обслуживает fonline.ru.

Решение

  1. GitHub Pages остаётся производственным издателем, а Jekyll остаётся рендерером.
  2. Канонический источник документации для людей представляет собой Markdown, зафиксированный в этом репозитории.
  3. Корневые _config.yml и CNAME остаются частью проверяемого контракта публикации. Docs/documentation-manifest.json задаёт провайдера, генератор, формат исходников, домен и владеющие пути.
  4. Не вводить Docusaurus, параллельное дерево содержимого website/ или зафиксированный в репозитории сгенерированный HTML.
  5. Макеты, include-файлы, данные, поддерживаемые плагины, переопределения темы и статические ресурсы Jekyll могут обеспечивать представление и навигацию, но должны оставаться тонким слоем рендеринга поверх Markdown.

  6. Целевая публичная структура локалей:

    Docs/
  en/       # canonical English human docs
  ru/       # Russian mirror with identical relative paths and stable document IDs
  assets/   # shared published media, styles, and search assets
  _meta/    # internal plans/reports, excluded from public navigation
  7. Публичные страницы используют стабильные идентификаторы и совпадающие относительные пути в обеих локалях. Переключатель языка разрешает страницу по идентификатору документа и пути, а не по тексту заголовка.
  8. Английский язык каноничен для синхронизации с исходным кодом, поскольку идентификаторы движка, комментарии в коде, символы и upstream-взаимодействие ведутся на английском. Русские страницы являются цельными зеркалами документов, а не смешанными языковыми фрагментами.
  9. Актуальность перевода отслеживается по хешу канонического содержимого. Производственная публикация не должна выдавать устаревшую русскую страницу за актуальную.
  10. До перемещения исходных файлов существующие публичные URL получают совместимые с GitHub Pages перенаправления либо долговечные маршрутные страницы Markdown.
  11. Реструктуризация документации не меняет существующую ветку и папку-источник Pages. Перед производственной миграцией администраторы репозитория должны проверить и записать эту настройку и владельца DNS.
  12. Pull request выполняют быстрые проверки Markdown, манифеста и ссылок, а на этапе сайта также совместимую с GitHub Pages сборку Jekyll, которая сохраняет _site как артефакт для проверки. Production продолжает развёртываться через существующий маршрут Pages.

Последствия

Положительные

  • GitHub и fonline.ru отображают одни и те же авторские файлы.
  • Документация остаётся переносимой и полезной без Node или клиентского приложения.
  • ИИ-системы могут напрямую использовать чистый Markdown и сгенерированный JSON.
  • Пользовательский домен и стек публикации проверяются в обычном diff репозитория.
  • Паритет локалей можно контролировать по стабильным путям и идентификаторам без реестра переводов, привязанного к отдельному фреймворку.

Издержки

  • Навигацию, статический поиск, переключение языка и индикаторы версии необходимо реализовать в пределах возможностей Jekyll, поддерживаемых GitHub Pages.
  • Перенос текущего плоского английского дерева требует заранее спланировать маршруты до того, как Docs/en/ станет каноническим для соответствующих страниц.
  • GitHub Pages предоставляет один производственный сайт; предварительный просмотр pull request остаётся артефактом сборки, пока не появится отдельно одобренная среда просмотра.
  • После фиксации английской информационной архитектуры паритет переводов добавляет работу в процесс выпуска.

Отклонённые варианты

  • Docusaurus или другое отдельное приложение сайта: отклонено, поскольку создаёт второй контракт фреймворка и содержимого и не соответствует действующему производственному маршруту.
  • Зафиксированный в репозитории сгенерированный HTML: отклонено, поскольку результат генерации конкурировал бы с Markdown за роль источника истины.
  • Соседние корни Docs.EN и Docs.RU: отклонено в пользу общепринятых каталогов локалей в нижнем регистре под единым корнем документации.
  • Смешанные англо-русские страницы: отклонено, поскольку ослабляет маршрутизацию, поиск, контроль актуальности перевода и машинный поиск информации.
  • Немедленные снимки версий: отложено до появления у движка тегов выпусков и явной политики поддержки.

Проверка

  • python BuildTools/docs_validate.py проверяет параметры публикации в манифесте, _config.yml и согласованность CNAME с доменом.
  • python BuildTools/docs_site.py --check проверяет локализованную навигацию и ограниченный по размеру поиск, полученные из манифеста.
  • python BuildTools/docs_site_artifact.py --site-dir _site проверяет собранные маршруты Jekyll и статические endpoint.
  • npm --prefix BuildTools/docs-browser run audit проверяет страницы в desktop/mobile-профилях, взаимодействия, скриншоты и результаты axe-core.
  • Задания Validate documentation и Build documentation site выполняются без подключающего проекта и нативной сборки и сохраняют _site как артефакт проверки.
  • Самостоятельное отображение Markdown в GitHub остаётся обязательным маршрутом наряду с Jekyll.

Связанные документы

Введите запрос.