arc42-template is a golden master, and its generated downloads stopped living in the repository

This repository is a source, and the document is built elsewhere

The README's first structural statement is that this repository contains the AsciiDoc source of the arc42 template. It is not the template as a document, and the words Golden Master in the title describe the relationship: this is the master copy, and everything a user downloads is generated from it.

The generator is a separate project, arc42-generator, which includes this repository as a submodule. The README gives three reasons this repository exists, and they are all maintenance tasks rather than consumption ones. It is the basis for generating the official download formats, docx, markdown, docbook and others. It maintains the structure, content and help text of the template. And it holds the non-AsciiDoc, non-generable formats, kept in other-formats/.

That last one is a useful distinction. Hand-made templates for Enterprise Architect, Confluence, IBM Rhapsody and Doxygen are not generated from AsciiDoc, so they live in their own directory and are published in their own release with a tools- tag rather than in the main release line.

The consequence for an adopter is that you do not consume this repository. You consume a release. Everything from version numbers to file names in the distributed template is produced by another project, and a change to this source only reaches users when that project rebuilds.

Stable file names, and the dist/ folder that no longer exists

The distribution design is worth studying because it solves a problem most template projects ignore: how does someone link to the newest version of a file without the link going stale?

The answer is that file names never change between releases. The README gives the pattern:

https://github.com/arc42/arc42-template/releases/latest/download/arc42-template-<LANG>-<plain|withhelp>-<format>.zip

An example given is the English template with help text in AsciiDoc format, and the latest/download path in the middle is what makes that link evergreen. A document that tells a team to fetch the template can keep the same URL indefinitely.

The same section records a change that will bite anyone with old links. The generated files are no longer committed to this repository, the former dist/ folder was removed in September 2026, and links to raw paths under dist no longer work. Only the release assets remain.

Each release also contains a manifest.json with versions and SHA-256 checksums, and covers every language in both the plain and with help styles across the supported formats. The checksums are the part to use if you distribute the template internally, since they let you verify what you downloaded rather than trusting the transport.

Adding a language is creating a folder

The directory structure is documented in full, and it is the clearest statement of how the template is organised. Each language code has its own folder at the root, and the top-level listing shows them all: CZ, DE, EN, ES, FR, HU, IT, NL, PT, RU, TR, UKR, ZH and ZH-TW, alongside common/ for shared styles, other-formats/ for the hand-made tool templates, and graphics-originals/ for original diagram sources.

Inside a language folder there are exactly four things: arc42-template.adoc as the main document, a version.properties file, an adoc/ directory holding the chapter files, and an images/ directory for that language's images.

The version.properties file holds four entries named in the README, revnumber, revdate, revdate-iso in YYYY-MM form, and revremark. Version 9.0 added this file to every language as part of unifying how a revision number is expressed, which is the kind of small consistency that matters when fifteen languages are versioned independently.

The procedure for a new language is remarkably short, which is the point. Create a folder named with a language code, optionally with a region as in ZH-TW, include all four version.properties entries, and add a row to the languages table. The generator finds the folder on its own and nothing else needs to change, so a translator is not asking anyone to edit a build script.

Volunteer translations freeze at the date they were written

The languages table is the most important governance document in the repository, and one line of it changes how you should read the rest.

The English and German versions are actively maintained by the founders, Gernot Starke and Peter Hruschka, who created the template in 2005. Translations to the other languages were provided by volunteers and will not be automatically updated.

That has a practical meaning. A translation available since a given date is a translation of the template as it stood then, not a live mirror. The table records availability dates ranging from 2005 for English and German through 2017 for Spanish, 2018 for Russian, 2021 for Italian, 2022 for Czech and Dutch, 2023 for French, 2024 for Portuguese and Ukrainian, 2025 for Chinese, 2026 for Traditional Chinese, Hungarian and Turkish.

Two of those recent entries are worth noticing for a reader. Traditional Chinese arrived on 2026-09-25 and Turkish on 2026-10-14, and the revision history records a first Turkish version in October 2026 and a first Chinese version in November 2025. So the newest languages are also the least synchronised with the English master, and there is no stated mechanism that would bring them up to date.

For a team writing documentation in a translated language, the honest move is to take the section structure and rewrite the guidance rather than assume a current translation exists.

Diagrams are drawio files wearing a .png extension

The Diagrams section describes a small hack that is worth stealing. The intention is to provide all diagrams in platform-neutral formats, mainly drawio, and the problem is that the diagram source has to be embedded in a .png file so that a documentation build can find it.

The solution is the combined extension .drawio.png. Because drawio recognises that suffix, double clicking the file opens it in the diagram editor rather than in an image viewer, so the same file satisfies both the build and the editor.

The same section records the migration in progress: files under graphics-originals are being gradually removed as the combined extension format takes over, and graphics-originals/ is marked as being phased out in the directory listing.

Version 9.0 in July 2025 also unified the concept image in section 8, and 8.2 in January 2023 added an imagedir definition to all files to make editing the AsciiDoc easier. Those two entries are examples of what a template maintainer actually spends time on, and they are a useful corrective to the idea that this is a document people write once.

Building a preview needs make and Docker, and the check is a pull request gate

A translator who wants to see their work rendered does not build this repository. They build the generator, which includes this template as a submodule. The README gives the sequence, and the requirement list is short: only make and Docker.

The commands run from a clone of the generator project. The Docker image is built once, then the template is pointed at a branch, either the newest main or the contributor's own:

git clone --recurse-submodules https://github.com/arc42/arc42-generator.git
cd arc42-generator
make image                                  # once: the Docker image with all tools

make template-update
git -C arc42-template fetch https://github.com/<you>/arc42-template.git <branch>
git -C arc42-template checkout FETCH_HEAD

make generate FORMAT=html                   # or FORMAT=pdf; without FORMAT: all 15 formats
make templates OPTS=--lint=warn             # only check the template

The --recurse-submodules flag is not optional here, because the template is consumed as a submodule. The FORMAT variable is the switch between a quick HTML preview and the full run, and without it the generator produces all fifteen formats. The output lands under build/, arranged by language, format and style, and the README gives a path such as a German HTML file with help as one example.

The last target is the one contributors should care about most. Running the template check with --lint=warn validates conditionals, help blocks, images and version.properties without producing documents, which is fast feedback before a full build. And every pull request to this repository is validated by the same generator in a workflow named Golden master validation, with problems reported as annotations on the file and line rather than as a failing log line.

The licence is not one GitHub recognises, and that is worth reading

The repository's licence is listed as Other, a custom licence that GitHub cannot classify, with LICENSE.txt named as the authority. No legal advice is offered here, and the point to make is narrow: this is not a MIT or Apache or Creative Commons grant, and a reviewer who assumes one from the topic list will be wrong.

For a documentation template that teams copy sections into their own repositories, that distinction has teeth. The template is MIT-like in spirit in that it is free and open source, as the README says, and it was created in 2005 by the two founders. But the actual grant, including any attribution requirement, modification rule or warranty disclaimer, is whatever LICENSE.txt says, and that file is the only place to read it.

The revision history is worth a second look for anyone tracking what changed. Version 9.0 in July 2025 clarified and restructured section 10 on quality requirements into an overview at 10.1 and details at 10.2, unified the concept image in section 8, added the version.properties file to every language, and reworked the local build to make translations easier. 8.2 in January 2023 added the imagedir definition.

The release cadence matches that maintenance style. The three most recent tags are 2026.09.30.2, 2026.10.2 and 2026.10.15, the last of which matches the last push on 2026-10-15, and releases are named by date rather than by a semantic version.

Editorial conclusion

Adopt arc42 if your team wants a fixed set of architecture document sections rather than a blank wiki, and if you are willing to treat the template as source and rebuild it with the generator project. Do not adopt it expecting volunteer translations to track the English master, because the README states they are not automatically updated, and do not assume the licence is a standard one, since GitHub could not classify it and LICENSE.txt is the authority. Verify first the download URL you bookmark still resolves, since the dist/ folder was removed in September 2026 and old raw links no longer work.

Frequently asked questions

Official sources

1. arc42/arc42-template on GitHub
2. Issues
3. Project website
4. README
5. Releases