# docToolchain: docs-as-code for software architecture > docToolchain is an AsciiDoc toolchain for technical documentation, built around the idea that software architecture documentation should be treated like code, using the arc42 template. It is a Gradle and Groovy build with a dtcw wrapper, Gitpod and Netlify preview support, and a default branch called ng where the configuration model is still changing. **docToolchain/docToolchain** — a AsciiDoc Toolchain for technical Software Documentation, focused on Software Architecture Documentation - Repository: https://github.com/docToolchain/docToolchain - Website: https://doctoolchain.github.io/docToolchain/ - Stars: 871 · Forks: 243 - Language: Groovy - License: MIT - Published: 2026-10-20 · Updated: 2026-10-20 · Language: en - Canonical page: https://hysenlabs.com/projects/doctoolchain-doctoolchain ## AsciiDoc plus arc42, with the build written in Groovy docToolchain describes itself as an implementation of the docs-as-code approach for software architecture, and the basis of it is the philosophy that software documentation should be treated in the same way as code, together with the arc42 template for software architecture. That pairing is the whole idea. The toolchain does not invent a documentation format; it takes AsciiDoc, which many teams already use, and wraps it in a structure taken from arc42, which is a well-known template for architecture documentation. The project topics list confirms the shape of the stack: asciidoc, asciidoctor, asciidoctor-diagram, asciidoctor-pdf and confluence alongside arc42, docs-as-code and enterprise-architect. The implementation tells you what kind of project this is. The primary language is Groovy, and the top-level listing has both Config.groovy and docToolchainConfig.groovy, a build.gradle, a settings.gradle, a gradle.properties, an init.gradle and a libs.versions.toml, which is Gradle's version catalogue. So the configuration of a documentation project is a program, and a Gradle build with a version catalogue is what you would expect from a tool that has to run the same pipeline for HTML, PDF, diagram generation and Confluence output. The licence is MIT, the homepage is the project site at doctoolchain.github.io/docToolchain, and the default branch is not master but ng. ## The branch split is the first thing to understand The README carries an IMPORTANT block that tells you how to choose a starting point, and it is the most useful paragraph in the file. It says that if you have used docToolchain in the past, be aware that the master branch is undergoing some changes. If you are looking for a fresh version and are willing to accept changes in the configuration, this ng branch is the right thing for you. If you are looking for what you are used to, then download the V1.0.0 release. So there are two lines of the toolchain in the repository, and the default branch is the new one. The ng branch is the next generation layout, and the price of using it is a configuration model that is still moving. The old layout is preserved as a tagged release, and a V1.0.0 release is linked for download rather than as a branch. The versions tell the same story from the release side. The recent releases are v3.4.1 on 2024-09-05, v3.4.2 on 2025-04-06 and v3.5.0 on 2026-04-19, so a 3.x line has been shipping for a while, and the last push to the repository was on 2026-10-15, which means the work is current even though the release number has not moved in half a year. The practical consequence for an evaluating team is that the decision you are really making is which configuration model you want to live with, and the README answers it in one sentence. Read that sentence first, then read the configuration files. ## dtcw, the wrapper that has to work on four shells The repository has a command line entry point called dtcw, and it ships in three forms: a dtcw script, a dtcw.bat for the Windows command shell and a dtcw.ps1 for PowerShell. There is also a dtcw_docker.env file next to them. The presence of three launchers for the same name is the interesting part. A documentation toolchain that has to invoke a Java build, an AsciiDoc processor and a diagram renderer ends up with a long chain of path and environment handling, and each shell spells environment variables differently. Shipping a .bat and a .ps1 alongside the shell script is a sign that the project expects people to run it on Linux, on Windows and from an IDE, and that the author did not want the command to be the thing that breaks first. Alongside the wrappers there are the supporting scripts. There is a .ci.sh, a copyDocs.sh and a netlifyBuildPreview.sh. The names describe three different jobs: continuous integration, copying documentation somewhere, and producing a preview deployment. There is also a bin/ directory, a scripts/ directory, a core/ directory, a src/ directory and a test/ directory, plus a template_config/ directory that holds the configuration skeleton that a new project starts from. The gradlew and gradlew.bat files, together with the gradle/ directory, mean the build does not ask you to install Gradle. That is a small but meaningful decision for a toolchain whose whole premise is that it should be as close to the code pipeline as possible. ## Gitpod, Netlify previews and submodules Three entries in the top-level listing point at how the project expects to be used in a team. The first is .gitpod.yml together with .gitpod.dockerfile, which is a cloud development environment definition. Gitpod gives a repository a reproducible workspace with the right tools already installed, and for a documentation toolchain that is a large part of the setup cost, because the toolchain's dependencies are spread across a Java build, an AsciiDoc toolchain and whatever renders the diagrams. A workspace description pins that down for everyone. The second is netlifyBuildPreview.sh, which produces preview deployments. For a docs-as-code project this is the piece that makes the approach work socially rather than technically: a pull request that changes the documentation can be reviewed as a rendered site, not as a diff of AsciiDoc source. That is the difference between docs-as-code as a principle and docs-as-code as something a reviewer can actually use. The third is .gitmodules, so parts of the toolchain are pulled in as submodules rather than vendored. The .gitignore, .gitattributes and .editorconfig files round out a repository that is careful about the boring parts of version control, and the .github/ directory holds the workflows. The images/ directory at the root holds the images used by the documentation, including the company logos listed in the README, and the project keeps a manual hosted at the project site with the Overview diagram referenced in the README. ## It started with a Confluence exporter and Enterprise Architect diagrams The history section of the README is short and explains where the tool came from. It all began with two important parts: a script called asciidoc2confluence and some scripts to export diagrams from Enterprise Architect. The first commit dates back to the middle of 2015, and the README credits the many contributors who have joined since. Those two origins are still visible in the project's shape. Confluence is one of the topics and asciidoctor-pdf is another, so the toolchain still targets the two outputs that a large organisation actually consumes: a wiki and a file. Enterprise Architect, a modelling tool many enterprise architects use, explains the enterprise-architect topic and the diagram pipeline. That history also explains the arc42 pairing. The author's original problem was getting diagrams out of a modelling tool and text into a wiki, and arc42 is a template built for exactly the documentation that goes with such a model. A toolchain born from that workflow carries its assumptions: it is oriented towards producing a document set for a review, rather than towards a developer reading reference pages about a library. The repository also carries a template_config/ directory and a docs site with a manual, which is where a new project is expected to start and where the structure of a generated document set is defined. ## LLM.md, two security files, and a note that has been there for years The README has a section aimed squarely at assistants, and it is unusual enough to mention. If you are using an AI assistant like ChatGPT or Claude to help with docToolchain, it asks you to point the assistant at the LLM.md file first, because that file contains accurate, up-to-date information about docToolchain's installation and usage, which helps assistants give better guidance. A project maintaining its own machine-readable brief for assistants is a small sign of where the maintainer expects usage to go. There is a CLAUDE.md in the root as well, alongside LLM.md, and the two security files, SECURITY.adoc and SECURITY.md, which is the same pattern seen in projects that keep both a source-format and a rendered or plain version of the same document. The other governance files are the usual set for an open source project that wants contributions: CODE_OF_CONDUCT.md, CONTRIBUTORS.adoc, a changelog.adoc, a LICENSE, and a .github/ directory for the workflows and templates. One passage of the README is worth flagging for a different reason. A NOTE block at the top says that Corona and Covid19 are taking their toll, that time is short in these times and issues are not worked on, and that sponsored issues with higher priority have been introduced, with a sponsor link on top of the issue page. That note is a snapshot of a particular period, and it is still sitting in the README of a repository that was pushed on 2026-10-15. The funded-work model is real, through OpenCollective, the same service Asciidoctor uses, and the same service that hosts the project's backers and sponsors. But the wording around it has not been refreshed, which tells you the README is maintained in bursts rather than continuously. ## Small project, real users, and an uneven release rhythm The README is candid about scale. docToolchain is still one of the smaller open source projects, but some companies already fully embrace the docs-as-code approach through docToolchain, and the page lists TomTom, DB Systel, codecentric and INNOQ with a request that a company add its logo through a pull request, stating in the PR that permission is given to display the logo within all project websites and documentation. That is a small but real signal: an architecture documentation toolchain has been adopted as a standard by a handful of European software houses and one mapping company, and the four names are the sort that are quietly used in enterprise architecture work rather than shouted about. The release rhythm is uneven. Two releases in 2024 and 2025, one in April 2026, and source commits in between, including one on 2026-10-15. The project is a single-maintainer effort with funding and sponsorship behind it and a community around it, and the pattern of the dates matches that: work continues, and releases come when there is a coherent set of changes. For a team choosing a tool, the reasons to pick docToolchain are specific. The output targets are the ones enterprises consume, PDF and Confluence. The structure is the arc42 template, which many architecture practices already know. The build is Gradle with a Groovy configuration, so a documentation build can be driven by the same tooling as the code. And the LLM.md file means an assistant you point at the repository starts from the maintainer's own current description rather than from a web search. Against that, the ng branch is explicitly a configuration that is still changing, and the v3.x line has had no release since 2026-04-19, so both the branch you choose and the version you pin deserve a look. ## Conclusion Adopt docToolchain if your team already writes documentation in AsciiDoc and wants architecture documents that live in the same repository and build pipeline as the code, because the arc42 template and the docs-as-code philosophy are the point of the project rather than an add-on. Do not adopt it expecting a finished configuration model, since the README states that the master branch is undergoing changes and that the ng branch asks you to accept changes in the configuration, and do not start from the V1.0.0 release assuming it is the current design. Before you commit, read LLM.md, which the project maintains as its own up-to-date guide to installation and usage, check the version you are pinning against the changelog, and look at template_config/ and Config.groovy, because that is where the structure you will inherit is defined. ## FAQ ### What is docToolchain? An AsciiDoc toolchain for technical software documentation, focused on software architecture. It implements the docs-as-code approach, treating documentation the way code is treated, and pairs it with the arc42 template for software architecture. ### Which branch should I use for docToolchain? The README says the master branch is undergoing some changes, and that if you want a fresh version and are willing to accept changes in the configuration, the ng branch is the right thing, while users who want what they are used to should download the V1.0.0 release. The repository's default branch is ng. ### How do I configure a docToolchain project? In Groovy, through the Config.groovy and docToolchainConfig.groovy files at the repository level, with the project skeleton in template_config/. The build itself is Gradle, with a version catalogue in libs.versions.toml and wrapper scripts gradlew and gradlew.bat. ### What output formats does docToolchain produce? The project topics list asciidoctor, asciidoctor-diagram, asciidoctor-pdf and confluence, and the project's own history starts with a script called asciidoc2confluence, so PDF and Confluence are the two targets it was built around. ## Sources - [docToolchain/docToolchain on GitHub](https://github.com/docToolchain/docToolchain) - [License: MIT](https://github.com/docToolchain/docToolchain/blob/ng/LICENSE) - [Project website](https://doctoolchain.github.io/docToolchain/) - [README](https://github.com/docToolchain/docToolchain/blob/ng/README.md) - [Releases](https://github.com/docToolchain/docToolchain/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/doctoolchain-doctoolchain