Quick Start Guide

Follow these steps to build Adaptadocx in all three formats HTML, PDF, and DOCX and run the QA checks.

Prerequisites

One-shot build (all formats)

Docker (recommended)

# Local branch only (default)
docker run --rm -v "$(pwd)":/work adaptadocx make build-all

# All tags (multiversion)
docker run --rm -v "$(pwd)":/work adaptadocx make build-all BUILD_SCOPE=tags

Local

# Local branch only (default)
make build-all

# All tags (multiversion)
make build-all BUILD_SCOPE=tags

This creates versioned artefacts:

build/site/<locale>/<version>/ — HTML
build/pdf/<locale>/<version>/adaptadocx-<locale>.pdf — PDF
build/docx/<locale>/<version>/adaptadocx-<locale>.docx — DOCX
site/<locale>/<version>/_downloads/ — published downloads per version

Verify artefacts

tree -L 3 build/

Expected outline (example):

build/
├── site/
│   ├── en/
│   │   └── 0.1.2/
│   └── ru/
│       └── 0.1.2/
├── pdf/
│   ├── en/
│   │   └── 0.1.2/
│   └── ru/
│       └── 0.1.2/
└── docx/
    ├── en/
    │   └── 0.1.2/
    └── ru/
        └── 0.1.2/

Build a single format

HTML only

make build-html

PDF only

make build-pdf
# Output:  build/pdf/<locale>/<version>/adaptadocx-<locale>.pdf
# Copied to: site/<locale>/<version>/_downloads/

DOCX only

make build-docx
# Output:  build/docx/<locale>/<version>/adaptadocx-<locale>.docx
# Copied to: site/<locale>/<version>/_downloads/

Run quality checks

make test

Tools executed:

Vale → vale.xml
htmltest → htmltest.log
Shellcheck → console output

View results:

cat vale.xml
cat htmltest.log

Package for release

make release

This creates adaptadocx-docs-<version>.zip in build/.

Edit-build-preview loop

Edit .adoc files in docs/en/… or docs/ru/….
Clean previous build: make clean
Re-build: make build-all
Open build/site/en/<version>/index.html (or build/site/en/current/index.html) in a browser; use ru/ for Russian.