= image:./small-arc42-logo.png[arc42] Template ("Golden Master")
:version 8.2:
:downloads https://arc42.org/downloads/:

image:https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/banner2-direct.svg[https://vshymanskyy.github.io/StandWithUkraine]

arc42 - the template for effective, practical and pragmatic software architecture documentation and communication.

Initially created by Dr. Gernot Starke and Dr. Peter Hruschka (way back in 2005...), free and open source.


This repository contains the (AsciiDoc) source of the arc42 template.

It is used...

*  as the basis for generating (by the https://github.com/arc42/arc42-generator[arc42-generator] project) the official download formats (i.e. docx, markdown, docbook and others). To generate, THIS repo is included as submodule from the generator project; see <<Build a Local Version>> for a preview of your changes.
* to maintain structure, content and help for the template
* to keep non-asciidoc, non-generable formats (like Sparx(R) Enterprise-Architect(R) EAP) in `other-formats/`.

In case you find issues within the template or its explanations, this is the repo to fix and issue pull requests :-)

== Revisions
* 9.1 (DE: 9.2) and 8.3: October 2026: see #197
  ** All languages: the quality goals (section 1.2) refer to ISO 25010:2023 (with link) and to the open https://quality.arc42.org[Q42 quality model].
  ** 8.x languages (ES, IT, NL, PT, RU, UKR): section 10 now refers to ISO 25010:2023 and Q42; its text is otherwise unchanged. IT got the ISO 25010 overview diagram in section 1.2.
  ** FR: fixed two broken links in section 10. DE, EN: typos in section 10.
* October 2026: first Azerbaijani version
* October 2026: first Turkish version
* November 2025: first Chinese version
* 9.0: July 2025: 
  ** Clarified and re-structured section 10 (Quality Requirements) to include overview (10.1) and details (10.2). 
  ** Unified concept-image in section 8. 
  ** Unified usage of revision number by adding version.properties file to every language. 
  ** Reworked the local build to facilitate translations
* 8.2: Jan 28th 2023: Thx to A. Bentele, added imagedir def to all files, for easier editing asciidoc. See #178

== Diagrams
We intend to provide all diagrams in platform-neutral formats, mainly `drawio`. 

The source of these diagrams is embedded in a `.png` file. To make this explicit, we use the combined extension `.drawio.png` for our diagrams.
The drawio tools will recognize this and open such files in the editor instead of an image viewer.

Therefore we will gradually remove all files under `./graphics-originals`



== Downloads

Please refer to the https://arc42.org/download[official download page] for all downloads.

The downloads are published as https://github.com/arc42/arc42-template/releases[GitHub Releases] of this repository, built by the https://github.com/arc42/arc42-generator[arc42-generator] (`make release`). Every release contains all languages, styles (plain, with help) and formats, plus a `manifest.json` with versions and SHA-256 checksums. File names do not change between releases, so this link always serves the newest file:

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

for example `https://github.com/arc42/arc42-template/releases/latest/download/arc42-template-EN-withhelp-asciidoc.zip`. The generated files are no longer committed here; the former `dist/` folder was removed in September 2026 (links to `raw/master/dist/...` no longer work).

Hand-made templates for other tools (Enterprise Architect, Confluence, IBM Rhapsody, Doxygen) are kept in `other-formats/` and published in their own release (tag `tools-...`).

== Languages

The EN and DE versions are actively maintained by the founders (G.Starke & P.Hruschka).
Translations to additional languages (see below) have been provided by volunteers, but won't be automatically updated.

The following languages are currently available:
[cols="1,1,1", options="header"]
|===
| Language | Translator | Available Since

| Azerbaijani (AZ)
| Nihad Jabrayilzade (https://github.com/nihadio[@nihadio])
| 2026-10-15

| Czech (CZ)
| jakub_rc <jakub.tomisek@gmail.com>
| 2022-10-12

| Chinese (ZH)
| Chris (Gentle) Y杨 (nodexy@gmail.com) with DannyGe
| 2025-10-30

| Traditional Chinese (ZH-TW)
| Sophie (https://github.com/sophieyin0310[@sophieyin0310])
| 2026-09-25

| Dutch (NL)
| mv <verburg.maarten@gmail.com> 
| 2022-05-01

| **English (EN)**
| Gernot Starke, Peter Hruschka (founders)
| 2005

| Spanish (ES)
| Isidoro (isidoro.trevino@vintec.mx)
| 2017-09-19

| French (FR)
| Damien Lucas (d.lucas@groupeonepoint.com) 
| 2023-06-05

| **German (DE)**
| Gernot Starke, Peter Hruschka (founders)
| 2005

| Hungarian (HU)
| László Séra (laszlo.sera@gmail.com)
| 2026-05-14

| Italian (IT)
| Mario Giustiniani (mariogiustiniani@gmail.com)
| 2021-04-04

| Dutch (NL)
| Maarten Verburg (verburg.maarten@gmail.com)
| 2022-05-01

| Portuguese (PT)
| Guilherme Weizenmann (g.weizenmann@gmail.com)
| 2024-09-10

| Russian (RU)
| Various contributors, <nerilin@cinimex.ru>, max.arshinov@gmail.com
| 2018-11-14

| Turkish (TR)
| Selman Seref (https://tecnovy.com[tecnovy GmbH]), selman.seref@tecnovy.com
| 2026-10-14

| Ukrainian (UKR)
| Ivan Bulyk, Larysa Visengeriyeva (visenger@gmail.com)
| 2024-11-10  

|===

== Build a Local Version

The template is built by the https://github.com/arc42/arc42-generator[arc42-generator], which also produces the official downloads. It needs only `make` and Docker. To preview your changes (for example a translation) in HTML or PDF:

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

# the template to build: newest main, or your branch
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 (conditionals, help blocks, images, version.properties)
----

The output is in `build/<LANG>/<format>/<plain|with-help>/`, e.g. `build/DE/html/with-help/arc42-template.html` or `build/ZH-TW/pdf/plain/arc42-template-ZH-TW.pdf`. See the https://github.com/arc42/arc42-generator#readme[generator README] for all targets.

Every pull request to this repository is checked by the same generator (workflow _Golden master validation_): problems appear as annotations on the file and line.

=== Directory Structure

----
<root>/
  ├── <LC>/                      // one folder per language, e.g. EN, DE, ZH-TW
  │    ├── arc42-template.adoc   // main document
  │    ├── version.properties    // revnumber, revdate, revdate-iso (YYYY-MM), revremark
  │    ├── adoc/                 // chapter files
  │    └── images/               // images of this language
  ├── common/                    // shared files (styles)
  ├── other-formats/<tool>/      // hand-made templates: Confluence, Doxygen, Enterprise Architect, Rhapsody
  └── graphics-originals/        // original diagram sources (being phased out)
----

=== Adding a New Language

Create a folder `<LC>/` like the ones above (a code such as `TR`, optionally with a region such as `ZH-TW`), with all four `version.properties` entries, and add it to the table under <<Languages>>. The generator finds it on its own; nothing else needs to change.


== Questions on using arc42?

* see the extensive https://docs.arc42.org[documentation website]
* see the https://arc42.org[overview] 


== Suggestions welcome

Open an issue here!