Start an interactive shell in the container

December 11, 2025 ยท View on GitHub

= image:./small-arc42-logo.png[arc42] 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 [#generator-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.

IMPORTANT: Docker is the only supported build approach. All dependencies (Java, Groovy, Pandoc, cmark) are pre-configured in the Docker container.

In theory it will be possible to run the build locally without Docker, but this is not supported and may lead to unexpected issues.

=== Prerequisites

=== Quick Start

  1. Clone this repository including submodules:

git clone --recurse-submodules git@github.com:arc42/arc42-generator.git cd arc42-generator

  1. Run the build using Docker Compose:

docker compose up

The build will:

  • Update the arc42-template submodule (Golden Master)
  • Generate templates in all supported languages and flavors
  • Convert to 15+ output formats (HTML, Markdown, DOCX, PDF, etc.)
  • Validate CommonMark markdown and image references
  • Create distribution ZIP files in arc42-template/dist/

Results are written to the local build/ directory.

=== Building in GitHub Codespaces

Docker is the recommended approach even in GitHub Codespaces:

docker compose up

The container handles all Git ownership issues automatically, so you don't need to install any local dependencies.

=== Advanced Build Options

To rebuild the Docker image from scratch:

docker compose build --no-cache

To run individual build phases inside the container:

Start an interactive shell in the container

docker compose run --rm arc42-builder /bin/bash

Then run individual phases

groovy build.groovy templates # Generate templates only groovy build.groovy convert # Convert to output formats groovy build.groovy distribution # Create distribution ZIPs

=== Build Validation

The build includes automatic validation:

  • CommonMark validation: Validates generated Markdown files against GitHub-flavored Markdown spec using cmark
  • Image validation: Checks that all image references exist in with-help flavors (markdown, asciidoc, textile, rst, html)
  • Submodule integrity: Ensures arc42-template submodule is up-to-date

All validations are non-fatal - the build continues even if warnings are reported.

=== 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
  • Final image size: ~564MB

The container includes:

  • Java Runtime (OpenJDK 21)
  • Groovy 5.0.3
  • Pandoc 3.7.0.2 (document converter)
  • cmark (CommonMark validator)
  • AsciidoctorJ (AsciiDoc processor)

No local installation of Java, Groovy, or Pandoc is required or supported.

== 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: 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 We collected the +arc42+ link:docs/arc42-requirements.adoc[requirements in a separate document].

== Template Downloads For template downloads please see the https://github.com/arc42/arc42-template[arc42-template] repository or the official download page on http://arc42.org/download.