Документация Adaptadocx

Adaptadocx — это система публикации документации на базе Antora. Платформа автоматически собирает многоязычные материалы из исходников AsciiDoc и создаёт три вида артефактов: HTML, PDF и DOCX. В проект встроены проверки качества, аудит безопасности и CI-конвейеры для воспроизводимых сборок.

Система поддерживает:

  • две локали (английская и русская);

  • кастомизацию UI Antora;

  • рендеринг диаграмм SVG;

  • сборки в Docker;

  • автоматизированные процессы QA, Security и линтинг;

  • мультиверсии по Git-тегам.

Обзор архитектуры

Adaptadocx построен модульно: Antora служит ядром генерации, а вспомогательные компоненты расширяют её возможности.

Компонент Назначение

Исходники документации

Контент AsciiDoc для EN и RU в docs/

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

Тема PDF и метаданные локалей в config/

UI-компоненты

Кастомизация Antora UI в custom-ui/

Скрипты сборки

Makefile и альтернативный оркестратор build.py

CI/CD

Workflow GitHub Actions в .github/

Ключевые возможности

Мультиформатный вывод

Единый набор AsciiDoc-файлов порождает три независимых артефакта.

  • HTML — статический сайт с кастомным UI-bundle и полнотекстовым поиском

  • PDF — офлайн/печать с пользовательской темой и шрифтами DejaVu для кириллицы

  • DOCX — редактируемый документ через Pandoc с автоматической обложкой

Контроль качества и безопасность

Проверки запускаются автоматически в CI.

  • Vale — линтер AsciiDoc (vale.xml)

  • htmltest — проверка ссылок (htmltest.log)

  • Shellcheck — анализ Bash-скриптов

  • Security audit — OSV-Scanner, Sandworm и поиск запрещённых паттернов (неблокирующие)

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

Adaptadocx можно собирать Make (по умолчанию) или эквивалентным Python-скриптом. Оба варианта формируют одинаковые артефакты в build/.

Режимы сборки

Локальный (по умолчанию) — собирает только текущую ветку HEAD или ветку, указанную в BUILD_REF.

make build-all
make build-all BUILD_REF=my-feature

По тегам — мультиверсийная сборка по всем Git-тегам.

make build-all BUILD_SCOPE=tags

Выходные артефакты версионированы и размещаются в:

  • build/pdf/<locale>/<version>/adaptadocx-<locale>.pdf

  • build/docx/<locale>/<version>/adaptadocx-<locale>.docx

  • копии публикуются в site/<locale>/<version>/_downloads/

Ссылки PDF и DOCX в шапке всегда указывают на _downloads активной версии.

Docker-окружение

Контейнерный образ включает:

  • Node.js 20 и Ruby ≥ 2.7

  • Python 3.11+

  • Asciidoctor PDF

  • Vale, htmltest, Shellcheck

  • Graphviz

  • Шрифты DejaVu

  • rsvg-convert для конвертации SVG→PDF/PNG

Цели Makefile

Цель Назначение

make build-all

Собрать HTML + PDF + DOCX (алиас build-site)

make build-html

Собрать только HTML

make build-pdf

Собрать только PDF

make build-docx

Собрать только DOCX

make test

Запустить Vale, htmltest и Shellcheck

make clean

Удалить build/

make release

Заархивировать артефакты после QA

Python-скрипт сборки

Если make недоступен, используйте build.py (Python 3.11+).

Команда Назначение

python3 build.py build-site

HTML + PDF + DOCX

python3 build.py build-html

Только HTML

python3 build.py build-pdf

Только PDF

python3 build.py build-docx

Только DOCX

python3 build.py prep

Только подстановка версии

python3 build.py clean

Удалить build/

Используйте либо Makefile, либо Python-скрипт — совмещать их в одной сборке не требуется.

Непрерывная интеграция

В GitHub Actions определены три группы workflow.

  1. QA Checks — линтинг AsciiDoc, проверка ссылок, анализ скриптов

  2. Security Audit — аудит зависимостей и содержимого (OSV-Scanner, Sandworm, запрещённые паттерны)

  3. Release — полная мультиверсийная сборка (BUILD_SCOPE=tags), упаковка и деплой

Быстрый старт

Установка через Docker (рекомендуется)

docker build -t adaptadocx .
# сборка Makefile
docker run --rm -v "$(pwd)":/work adaptadocx make build-all
# сборка Python-скриптом
docker run --rm -v "$(pwd)":/work adaptadocx python3 build.py build-site

Локальная установка

npm ci --no-audit --no-fund
# Makefile
make build-all
# или Python
python3 build.py build-site

См. также