Экспорт в CI/CD

Если документация лежит в одном репозитории с кодом, вы можете формировать файл с инструкциями в процессе сборки самого продукта. Для этого используется Gramax CLI.

В корне репозитория создайте .gitlab-ci.yml (или дополните существующий) и добавьте стадию экспорта, где задаются переменные и этапы.

Описание этапов в .gitlab-ci.yml

  • stages — список стадий пайплайна. Для экспорта документов используем стадию export (название можно изменить, но примеры ниже исходят из export).

  • variables — переменные окружения, доступные в задачах пайплайна.

    • EXPORT_FILE_PATH — базовый путь/имя выходного файла без расширения.

      В примерах: EXPORT_FILE_PATH: artifacts/export → на выходе файл будет в директории artifacts/export.[format].

Примеры

DOCX
PDF
stages:
  - export

variables:
  EXPORT_FILE_PATH: artifacts/export

export-docx:
  stage: export
  tags:
    - docker-linux-amd64
  image: node:latest
  script:
    - npx gramax-cli export -f docx -o $EXPORT_FILE_PATH -y -t ./my-template.docx

  artifacts:
    paths:
      - artifacts

npx gramax-cli export -f docx -o $EXPORT_FILE_PATH -y -t ./my-template.docx — команда для экспорта документации с помощью Gramax CLI.

  • -f docx — экспорта в DOCX.

  • -o $EXPORT_FILE_PATH — путь, куда будет сохранен файл export.docx (в данном примере в папке artifacts будет файл export.docx).

  • -y — для автоматического подтверждения действий без запроса подтверждения у пользователя.

  • -t — путь к шаблону (необязательный параметр).

stages:
  - export

variables:
  EXPORT_FILE_PATH: artifacts/export

export-pdf:
  stage: export
  tags:
    - docker-linux-amd64
  image: node:latest
  script:
    - npx gramax-cli export -f beta-pdf -o $EXPORT_FILE_PATH -y --pdf-title --pdf-toc --pdf-number -t./template.css

  artifacts:
    paths:
      - artifacts

npx gramax-cli export -f beta-pdf -o $EXPORT_FILE_PATH -y --pdf-title --pdf-toc --pdf-number -t./template.css — команда для экспорта документации с помощью Gramax CLI.

  • -f beta-pdf — экспорта в PDF.

  • -o $EXPORT_FILE_PATH — путь куда будет сохранен файл export.pdf (в данном примере в папке artifacts будет файл export.pdf).

  • -y — для автоматического подтверждения действий без запроса подтверждения у пользователя.

  • -t — путь к шаблону (необязательный параметр).

  • --pdf-title — добавить титульный лист (необязательный параметр).

  • --pdf-toc — добавить оглавление (необязательный параметр).

  • --pdf-number — добавить нумерацию заголовков (необязательный параметр).

Шаблоны

Gramax CLI поддерживает шаблоны для обоих форматов:

  • DOCX — файл-шаблон .docx (ваши стили, титульный лист, шапки/футеры и т. п.).

  • PDF — CSS-файл (определяет внешний вид при рендеринге PDF).

Единый флаг для подключения шаблона — --template (-t):

gramax-cli export --template TEMPLATE

TEMPLATE может быть:

  • Путем к файлу шаблона (относительным или абсолютным), например:
    ./templates/my-template.docx.

  • Именем шаблона из текущего воркспейса, если указано без слешей, например:
    standard-report.

Например:

# Имя шаблона из воркспейса
gramax-cli export --template standard-report

# Шаблон по пути (DOCX)
gramax-cli export -f docx --template ./templates/my-template.docx

# Шаблон по пути (PDF)
gramax-cli export -f beta-pdf --template ./templates/my-template.css