Generator for arc42 Template Formats

If you want to use an arc42 template for your system, you don’t need to use this repo - just use one of the templates you find on https://arc42.org/download.

General Overview

The content (structure + embedded-help) of the arc42 template are maintained in the https://github.com/arc42/arc42-template repository.

>See section General Requirements for a brief explanation of terminology and requirements.

How to Build

This repository contains a Groovy-based build system that generates arc42 templates in multiple formats and languages from the Golden Master source.

Everything runs through make, and every target runs in Docker. Java, Groovy, Pandoc and cmark live in the Docker image; nothing else is installed on your machine. make help lists all targets and variables.

Prerequisites

• make

• Docker with Compose v2

• Git, to clone the repository (and for make pin and make release, which commit and push with your identity)

• For releases only: the GitHub CLI gh, logged in (gh auth login)

Quick Start

git clone --recurse-submodules https://github.com/arc42/arc42-generator.git
cd arc42-generator
make image      # build the Docker image once (Java, Groovy, Pandoc 3.7.0.2, cmark)
make build      # full arc42 build
make test       # all test scripts

make build:

• checks out the arc42-template submodule (Golden Master) at the commit recorded in this repository,

• validates the Golden Master (conditionals, help blocks, the arc42help attribute, images, version.properties) and stops on errors,

• generates the templates in all languages and styles and converts them to 15 output formats (HTML, PDF, Markdown variants, DOCX, EPUB, LaTeX, reStructuredText, Textile, DocBook, AsciiDoc), stopping on Asciidoctor or Pandoc diagnostics,

• creates the distribution ZIPs in build/dist/, together with a manifest.json that lists languages (with version and date), styles, formats and every ZIP with its size and SHA-256,

• validates the output: the Markdown with cmark (warnings only), the images of the with-help styles and the includes of the AsciiDoc output (both fail the build).

Every run starts from a clean build/ output, so nothing from an earlier run ends up in the ZIPs. The output is reproducible: unchanged content produces byte-identical files and ZIPs (timestamps come from SOURCE_DATE_EPOCH or the last commit of the Golden Master outside dist/, not from the build time, so a merged release does not change them; every EPUB gets a fixed identifier derived from project, language and style instead of a random one).

Make Targets

Target	What it does
Build arc42
make build	Full build: check out arc42-template, all phases, validate the output
make generate	All phases (templates, convert, distribution) without checkout and output validation
make templates	Phase 1: validate the Golden Master, generate the templates into build/src_gen/
make convert	Phases 2-3: discover and convert the templates
make distribution	Phase 4: create the distribution ZIPs
make validate	Validate the output: Markdown with cmark (warnings only), images of the with-help styles and AsciiDoc includes (fail)
Tests
make test	All test scripts
make test-<name>	One test script: templates, discovery, converter, config, lint
Golden Master (arc42-template submodule)
make template-checkout	Check out arc42-template at the recorded commit (local changes are kept; the target stops instead)
make template-update	Move arc42-template to the newest main, for a build of the latest translations
make pin	Record the checked-out arc42-template commit in this repository (a git commit on the current branch)
Release
make release	Full build, then publish the ZIPs and manifest.json as GitHub Release <TAG> of arc42-template (default: today, YYYY.MM.DD). Builds the newest template main; stops if its content differs from the recorded commit.
make release-tools TOOLS_TAG=tools-YYYY.MM	Publish the hand-made tool files of arc42-template other-formats/ (Enterprise Architect, Confluence, Rhapsody, Doxygen) as a GitHub Release that never becomes latest
Docker image and tools
make image	Build the Docker image; rerun after changing the Dockerfile
make image-fresh	Rebuild the image without cache
make versions	Show the tool versions inside the image
make shell	Interactive shell in the container; the make targets work there as well
Cleanup
make clean	Remove build/ (with the ZIPs in build/dist/) and build2/
make fix-owner	Linux: give files created by the container (root) back to the calling user; the targets do this automatically

Variables:

make convert FORMAT=html                       # one format only
make templates OPTS="--lint=warn"              # report Golden Master problems without failing
make convert OPTS="--failure-level=error"      # fail only on errors, not on warnings (default: warn; also fatal, none)
make generate OPTS="--parallel=false"          # sequential conversion
make build UPDATE_TEMPLATE=1                   # build the newest arc42-template main instead of the recorded commit
make generate TEMPLATE=../req42-framework      # another template repository, see below
SOURCE_DATE_EPOCH=1751846400 make generate     # fixed timestamp for DOCX/EPUB/ZIP entries
make templates DOCKER_RUN_OPTS="-e FOO=bar"    # extra options for docker compose run (the arc42-template CI passes GITHUB_ACTIONS this way)

docker compose up runs make build inside the container, for example in GitHub Codespaces.

Working on the Golden Master

Template content, including new translations, is developed in arc42-template. Its CI validates every pull request with this generator and shows each problem as annotation on the file and line.

This repository records the arc42-template commit it builds (the submodule "pin"), so the same generator commit always produces the same ZIPs. When arc42-template main moves, Dependabot opens a pull request here that moves the pin; the CI of this repository builds it. To try a template change locally:

make template-update          # newest arc42-template main (or: git -C arc42-template checkout <branch>)
make generate                 # build what is checked out; 'make build' would go back to the recorded commit
make pin                      # optional: record the commit, then open a pull request

A new language only needs its directory in arc42-template: <LANG>/ with a code such as TR, optionally with a region such as ZH-TW.

Publishing the Distribution ZIPs

make release                                          # release YYYY.MM.DD on arc42/arc42-template
make release TAG=2026.09.30.2                         # a second release on the same day
make release REPO=you/arc42-template PRERELEASE=1     # test on your fork; a pre-release never becomes latest
make release-tools TOOLS_TAG=tools-2026.09            # the hand-made tool files, never latest

make release builds everything with the release tag in manifest.json and publishes a GitHub Release <TAG> on arc42-template: every ZIP of the manifest and manifest.json, release notes with the version of every language, targeted at the template commit that was built. https://github.com/arc42/arc42-template/releases/latest/download/<file>; then serves the newest file, and https://arc42.org/download links there (through arc42.org/dl/<file>). Nothing is committed to arc42-template. After a release on arc42/arc42-template, make release notifies arc42.org-site (repository_dispatch template-released), which then refreshes the language and format data of the download page.

If the files equal those of the latest release (names and SHA-256 in manifest.json), nothing is published. The release targets need the GitHub CLI gh, logged in, on your machine. make release-tools publishes the hand-made tool files from the other-formats/ folders of arc42-template; they change rarely.

make check-downloads PREFIX=<url> requests every file of build/dist/manifest.json from a prefix and lists the missing ones; with CHECKSUMS=1 it downloads them and compares their SHA-256 with the manifest:

make check-downloads PREFIX=https://arc42.org/dl/
make check-downloads PREFIX=https://github.com/arc42/arc42-template/releases/latest/download/ CHECKSUMS=1

Building Other Templates (e.g. req42)

The generator is not tied to arc42. Everything project-specific lives in the config file:

• project.name - base name of the main document (<LANG>/<name>.adoc) and of all generated files and ZIPs

• project.featurePrefix - prefix of the feature markers, e.g. [role="arc42help"] and ifdef::arc42help[], and of the about page (about-arc42.adoc)

• project.logo - the only image copied into the plain style

• goldenMaster.sourcePath and distribution.targetPath - location of the sources and of the ZIPs

• distribution.languageNames and the label of each format - names used in manifest.json (a language or format without one is listed by its code)

buildconfig.groovy holds the arc42 values. Another template keeps a complete copy of this file (all sections) in its own repository and follows the layout of arc42-template: <LANG>/<name>.adoc, <LANG>/adoc/, <LANG>/images/ and <LANG>/version.properties. Paths in a config file are relative to the directory of that file, including the build/ output.

TEMPLATE mounts the template repository into the container and uses its config; the output is written below that repository:

make templates TEMPLATE=../req42-framework
make generate TEMPLATE=../req42-framework
make validate TEMPLATE=../req42-framework

Testing the Generator

See the meta.arc42.org repository (internal arc42 documentation) for a step-by-step guide: self-tests, the arc42 build, building another template such as req42, and what output to expect.

Build Validation

The build fails on problems in the sources, in the conversion and in the output:

• Golden Master lint (before generation): unbalanced ifdef::arc42help[]/endif::arc42help[], help blocks that are not wrapped in a conditional, a language that uses ifdef::arc42help[] but never sets :arc42help: (its with-help template would lose all help text), image references without a file in <LANG>/images/, incomplete version.properties, and a revdate-iso that is not a month YYYY-MM are errors; a chapter set or help-block count that differs from EN, and a version.properties without revdate-iso (the machine-readable month of revdate, written to manifest.json as isoDate), are warnings. Use OPTS=--lint=warn to report instead of fail.

• Diagnostics (after conversion): Asciidoctor log records (e.g. a missing include) and Pandoc warnings (e.g. an image it could not embed into DOCX or EPUB) are printed with file and line. Records at --failure-level (default warn) or above fail the build.

• Clean output: the output directories of a phase are deleted before the phase runs.

• Output validation (make validate, part of make build): the Markdown is checked with cmark (warnings only); for the with-help styles the images/ directories of markdown, asciidoc, textile, rst and html must exist and be non-empty, and every image reference in the with-help Markdown must resolve to a file. All image findings are printed, then the build fails.

Docker Image Details

The Docker image is optimized for size and build speed:

• Multi-stage build: Separates build-time and runtime dependencies

• Cached dependencies: Groovy Grape cache pre-populated during image build

• Minimal runtime: Alpine Linux 3.20 with only essential tools

• Pinned converter: Pandoc 3.7.0.2 from the official GitHub release (static binary, SHA-256 verified)

• Image size: not re-measured since the pandoc change (the static pandoc binary is about 160 MB on amd64)

The container includes:

• Java Runtime (OpenJDK 21)

• Groovy 5.0.3

• Pandoc 3.7.0.2 (document converter, pinned release binary with checksum)

• cmark (CommonMark validator)

• GNU make and git

• AsciidoctorJ 2.5.10 (AsciiDoc processor, bundles Asciidoctor 2.0.20) and AsciidoctorJ PDF 2.3.27

• Droid Sans Fallback (fallback font of the PDF output for Chinese)

General Requirements

Requirements Concerning the Generator

We need to build the template for several output formats and natural languages from a single source (the Golden Master in arc42-template).

• Technical formats: PDF, docx, Markdown (with numerous variants), AsciiDoc, reStructuredText, Textile, HTML

• Variantes (aka flavours): withHelp (embedded help texts), plain (no help texts)

• Natural languages: English, German, Spanish, French, Italian, Portuguese, Chinese and others.

Requirements Concerning arc42

The arc42 requirements are collected in the meta.arc42.org repository.

Template Downloads

For template downloads please see the arc42-template repository or the official download page on http://arc42.org/download.