Часто задаваемые вопросы

В этом разделе собраны ответы на популярные вопросы по установке, настройке, использованию и диагностике Adaptadocx.

Установка и настройка

Каковы минимальные системные требования?

Для работы Adaptadocx требуются:

  • Node.js 18+ с менеджером пакетов npm.

  • Ruby ≥ 2.7 — используется Asciidoctor PDF.

  • 4 ГБ свободного диска — для исходников и артефактов сборки.

  • Git — получение репозитория и контроль версий.

При установке через Docker хост-требования сокращаются до Docker Engine 20.10+ и тех же 4 ГБ места.

Докер или локальная установка?

В большинстве случаев предпочтителен Docker, так как он обеспечивает:

  • Единообразие — одинаковая версия инструментов на любой платформе.

  • Простоту — контейнер содержит все зависимости.

  • Изоляцию — не затрагивает существующие утилиты на хосте.

  • Надёжность — образ протестирован и гарантированно собирается.

Локальную установку используйте только если инструменты действительно нужны на хосте или требуется интеграция с существующей средой.

Как проверить корректность установки?

Соберите минимальный HTML-пакет и убедитесь в наличии вывода.

# Вариант с Docker
docker run --rm -v "$(pwd)":/work adaptadocx:latest make build-html

# Вариант без Docker
make build-html

При успехе HTML-артефакты появятся в:

  • build/site/en/<version>/

  • build/site/ru/<version>/

Также может присутствовать псевдоверсия current/ в зависимости от конфигурации Antora.

Система сборки

Откуда берётся ошибка "No rule to make target"?

Makefile не нашёл указанную цель. Возможные причины:

  • Неверный каталог — запускайте make из корня проекта.

  • Отсутствует Makefile — убедитесь, что файл есть и читается.

  • Опечатка — выведите список доступных целей:

    grep -E '^[A-Za-z0-9_-]+:' Makefile | cut -d: -f1 | sort -u

  • Права доступа — проверьте, что Makefile читаем текущим пользователем.

Форматы вывода

Где сохраняются сгенерированные PDF и DOCX?

Каждая сборка формирует версионированные артефакты по локали:

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

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

Копии публикуются в загрузках сайта:

  • site/<locale>/<version>/_downloads/adaptadocx-<locale>.pdf

  • site/<locale>/<version>/_downloads/adaptadocx-<locale>.docx

Почему кириллица искажена в PDF?

Убедитесь, что шрифты DejaVu доступны системе, где запускается Asciidoctor PDF.

# Debian / Ubuntu
sudo apt-get install -y fonts-dejavu fonts-dejavu-extra

# Проверка установки
fc-list | grep -i dejavu

# Убедитесь, что тема использует DejaVu
grep -i dejavu config/default-theme.yml
Как изменить оформление PDF?

Редактируйте файл темы config/default-theme.yml. Поддерживаются все ключи Asciidoctor PDF (наборы шрифтов, размеры заголовков, отступы и т. д.).

Могу ли я настроить обложку DOCX?

Да. Измените Lua-фильтр docx/coverpage.lua, например чтобы всегда заполнялись заголовок и версия:

function Meta(meta)
  meta.title   = meta.title   or pandoc.MetaString(os.getenv('DOC_TITLE') or 'Adaptadocx Documentation')
  meta.version = meta.version or os.getenv('VERSION') or 'dev'
  return meta
end
Как исправить битые ссылки в HTML?

Запустите проверку ссылок и исправьте неверные адреса.

make build-html
htmltest -c .htmltest.yml build/site

# Просмотр лога
cat htmltest.log

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

Как расширить словарь Vale?

Добавьте разрешённые термины в .vale/vocab/<DictionaryName>/accept.txt.

# .vale/vocab/Adaptadocx/accept.txt
Adaptadocx
AsciiDoc
Antora
DOCX
Почему htmltest даёт ложные срабатывания?

Настройте исключения в .htmltest.yml.

IgnoreURLs:
  - "http://localhost"
  - "https://example.com"

HTTPStatusIgnore:
  - 429  # Ограничение по запросам
  - 503  # Сервис недоступен

Многоязычная документация

Можно ли добавить язык помимо EN и RU?

Да, следуйте существующей схеме компонентов:

  1. Создайте каталог docs/<locale>/.

  2. Добавьте файл компонента docs/<locale>/antora.yml.

  3. Добавьте playbook antora-playbook-<locale>.yml.

  4. Создайте метаданные config/meta-<locale>.yml.

  5. Включите стемминг поиска для нового языка в конфигурации Lunr.

CI/CD и деплой

Почему сборка в GitHub Actions падает, а локально проходит?

Частые причины:

  • Разные версии инструментов — в CI могут быть более новые или старые версии.

  • Чувствительность к регистру — различия Windows vs. Linux файловых систем.

  • Ограничения ресурсов — память или таймауты runner’а.

  • Отсутствие секретов — переменные не заданы в настройках репозитория.

Включите подробный вывод (set -x, --debug и т. п.) в шагах workflow, чтобы локализовать проблему.

Миграция и обновления

Как перенести существующую документацию на Adaptadocx?

Рекомендуемый поэтапный процесс:

  1. Конверсия контента — переведите материалы в AsciiDoc.

  2. Организация структуры — разнесите файлы по компонентам и модулям Antora.

  3. Конфигурация — создайте файлы antora.yml и playbook’и.

  4. Обновление ссылок — замените жёсткие пути на xref.

  5. Тестирование — запустите make build-all && make test.

См. также