https://github.com/arc42/arc42-generator
a gradle build to generate all derived templates from arc42-master
https://github.com/arc42/arc42-generator
hacktoberfest2022
Last synced: 5 months ago
JSON representation
a gradle build to generate all derived templates from arc42-master
- Host: GitHub
- URL: https://github.com/arc42/arc42-generator
- Owner: arc42
- License: mit
- Created: 2016-08-18T09:48:54.000Z (almost 10 years ago)
- Default Branch: master
- Last Pushed: 2025-12-11T15:51:23.000Z (6 months ago)
- Last Synced: 2025-12-12T09:47:31.840Z (6 months ago)
- Language: Groovy
- Homepage:
- Size: 1.33 MB
- Stars: 52
- Watchers: 5
- Forks: 16
- Open Issues: 12
-
Metadata Files:
- Readme: README.adoc
- License: LICENSE.txt
Awesome Lists containing this project
- awesome-starred - arc42/arc42-generator - a gradle build to generate all derived templates from arc42-master (others)
README
= 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
* https://www.docker.com/[Docker] and Docker Compose installed
* Git (to clone the repository with submodules)
=== Quick Start
1. Clone this repository including submodules:
+
----
git clone --recurse-submodules git@github.com:arc42/arc42-generator.git
cd arc42-generator
----
2. 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.