Архитектура системы

Adaptadocx — модульная система документации на базе Antora. Стек организован в пять слоёв:

  1. Исходные файлы

  2. Оркестрация сборки

  3. Генерация форматов (HTML, PDF, DOCX)

  4. Контроль качества

  5. CI-процессы безопасности и упаковки

Основные компоненты

Слой Каталог / Файл Роль

Контент

docs/en/, docs/ru/

Языковые исходники AsciiDoc

Контент

docs/*/modules/ROOT/pages

Отдельные страницы .adoc

Контент

docs/*/antora.yml

Имя компонента, версия, навигация

Конфигурация

antora-playbook-en.yml, antora-playbook-ru.yml

Глобальная конфигурация сайта (источники, UI, вывод)

Конфигурация

antora-assembler.yml

Настройки ассемблера для экспортов PDF/DOCX

Конфигурация

config/

Тема PDF и метаданные по локалям (meta-*.yml)

UI

custom-ui/

Переопределения CSS/JS и макетов (ссылки на загрузки ведут в _downloads)

Сборка

Makefile, build.py

Основной и альтернативный оркестраторы

Контейнер

Dockerfile

Воспроизводимая цепочка инструментов для CI и локального запуска

CI

.github/workflows/*.yml

Workflow для QA, security audit и релизов

Приоритеты конфигурации

Приоритет Файл Область

1

docs/*/antora.yml

Компонент

2

antora-playbook-*.yml

Весь сайт

3

Встроенные атрибуты

Отдельный документ

Конвейер сборки

  1. build-html — Antora генерирует сайт в build/site/ и экспорт ассемблера в build/asm/. Объём сборки управляется переменными BUILD_SCOPE (local по умолчанию или tags) и BUILD_REF (по умолчанию HEAD).

  2. build-pdf — использует build/asm/, создаёт версионированные PDF в build/pdf/<locale>/<version>/, затем копирует их в site/<locale>/<version>/_downloads/.

  3. build-docx — использует build/asm/, создаёт версионированные DOCX в build/docx/<locale>/<version>/, затем копирует их в site/<locale>/<version>/_downloads/.

  4. make test — запускает Vale, htmltest, Shellcheck.

  5. Упаковка — make release архивирует результат (adaptadocx-docs-<version>.zip).

Каталог build/asm/ содержит промежуточные сборки от @antora/pdf-extension. Каталог build/site/ содержит итоговый HTML-сайт.

Поток HTML

AsciiDoc → Antora → UI bundle → Lunr index → HTML site

  • Поиск — Lunr со стеммерами EN/RU.

  • Диаграммы SVG рендерятся нативно в браузере.

Поток PDF

AsciiDoc → Asciidoctor PDF → theme → fonts → PDF

  • Тема — config/default-theme.yml.

  • Шрифты — DejaVu (латиница + кириллица).

  • SVG — при наличии конвертируются rsvg-convert.

Поток DOCX

AsciiDoc → Pandoc → Lua filter → metadata → DOCX
Команда (пример EN)
pandoc --from asciidoc \
       --to docx \
       --lua-filter=docx/coverpage.lua \
       --metadata-file=config/meta-en.yml \
       -o build/docx/en/0.1.2/adaptadocx-en.docx \
       docs/en/modules/ROOT/pages/*.adoc

Контроль качества

Инструмент Проверки Вывод

Vale

Стиль, орфография

vale.xml

htmltest

Целостность ссылок

htmltest.log

Shellcheck

Lint shell-скриптов

Консоль

Параметры объёма сборки

Переменная Назначение Значение по умолчанию

BUILD_SCOPE

local — собирать только текущую ветку; tags — собирать все Git-теги

local

BUILD_REF

Ветка/ссылка для локального режима (например, my-feature, HEAD)

HEAD

Контейнерный образ

  • База — Node.js 20 + Ruby ≥ 2.7

  • Дополнительно — Asciidoctor PDF, Pandoc, Vale, htmltest, Shellcheck, Graphviz, шрифты DejaVu

Образ собирается один раз и переиспользуется во всех задачах CI.

CI-процессы

Workflow Задача Триггер

QA Checks

Vale, htmltest, Shellcheck

pull_request (в main)

Security Audit

OSV-Scanner, Sandworm, проверка запрещённых паттернов

pull_request → main, push → теги ('*')

Release

Контейнерная сборка, мультиверсионные доки (BUILD_SCOPE=tags), архив артефактов и деплой

push по тегам
Релизный workflow публикует полный сайт и загружает архив с артефактами.

См. также