A practical guide to standing up an AsciiDoc toolchain for software architecture documentation — with PlantUML diagrams, PDF/HTML output, and a free, open-source license. Written for embedded teams who need formal docs (arc42) without the Microsoft Word dance.

TL;DR

What Is AsciiDoc (and Asciidoctor)?

AsciiDoc is the language — a lightweight, human-readable plain-text markup. Asciidoctor is the processor — the open-source tool (originally Ruby, also available as JavaScript and a JVM build) that converts .adoc files into HTML5, PDF, DocBook, EPUB, and man pages.

Think of it as Markdown’s bigger sibling: same readable-as-source philosophy, but with first-class support for the things technical and architecture documents actually need — admonitions, cross-references, includes, tables, footnotes, conditional content, and diagram blocks.

If you’ve ever wrestled with a 40-page Word document where the table of contents broke after someone moved a heading, or tried to diff a binary .docx file in Git, you’ll feel the relief immediately.

Step-by-Step Setup

This is the toolchain I use for the cu_mainboard arc42 documentation: Asciidoctor + asciidoctor-pdf + asciidoctor-diagram (PlantUML) + the VS Code AsciiDoc extension.

Step 1 — Install Ruby (the Asciidoctor runtime)

Asciidoctor runs on Ruby. Install Ruby first.

Windows (recommended — RubyInstaller with DevKit):

1. Download from https://rubyinstaller.org/ (pick the latest "Ruby+Devkit" x64)
2. Run the installer, keep "Add Ruby to PATH" checked
3. At the end, let it run "ridk install" → choose option 3 (MSYS2 + dev toolchain)

macOS / Linux (Ruby is usually preinstalled):

# macOS (Homebrew)
brew install ruby

# Debian / Ubuntu
sudo apt-get install ruby-full

Verify:

ruby --version

Step 2 — Install Asciidoctor

With Ruby in place, install the core processor plus the two extensions you need for architecture docs:

# Core HTML processor
gem install asciidoctor

# PDF output backend
gem install asciidoctor-pdf

# Diagrams-as-code (PlantUML, Graphviz, Mermaid, etc.)
gem install asciidoctor-diagram

Verify:

asciidoctor --version

Step 3 — Install Java + PlantUML (for diagrams)

Architecture documents live and die by their diagrams. asciidoctor-diagram renders PlantUML blocks, and PlantUML needs a Java runtime.

1. Install a JRE/JDK (Java 11+):  https://adoptium.net/
2. Verify:  java -version
3. PlantUML itself is pulled in automatically by asciidoctor-diagram,
   or download plantuml.jar from https://plantuml.com/download
   (Graphviz is optional, only needed for certain diagram types)

Step 4 — Set Up VS Code for Live Editing

Write .adoc files in any editor, but VS Code with the official extension gives you live side-by-side preview.

1. Open VS Code → Extensions (Ctrl+Shift+X)
2. Search "AsciiDoc" → install "AsciiDoc" by asciidoctor (publisher: asciidoctor)
3. Open any .adoc file → Ctrl+Shift+V for a live preview pane

In settings.json, point the extension at your local Asciidoctor and enable diagrams:

{
  "asciidoc.use_asciidoctorpdf": true,
  "asciidoc.extensions.enableKroki": false,
  "asciidoc.preview.refreshInterval": 600
}

Step 5 — Write Your First Architecture Document

Create architecture.adoc:

= Control Unit — Software Architecture
Hoa Nguyen <hoanguyen.asm@gmail.com>
v1.0, 2026-06-29
:toc: left
:toclevels: 3
:sectnums:
:icons: font

== Introduction and Goals

The Control Unit (CU) firmware runs on an NXP i.MX RT1062
(Cortex-M7 @ 600 MHz) using QP/C active objects over FreeRTOS.

TIP: Admonitions like TIP, NOTE, WARNING render as styled callouts.

== Building Block View

[plantuml, component-overview, svg]
----
@startuml
component SystemManager
component Spe
component ProcessController
SystemManager --> Spe
SystemManager --> ProcessController
@enduml
----

Step 6 — Generate HTML and PDF

# Single self-contained HTML page (with embedded diagrams)
asciidoctor -r asciidoctor-diagram architecture.adoc

# PDF (print-ready architecture document)
asciidoctor-pdf -r asciidoctor-diagram architecture.adoc

The first run renders the PlantUML block to an image and embeds it. Open architecture.html in a browser or architecture.pdf in any viewer.

Why AsciiDoc Is a Strong Fit for Architecture Documentation

1. Docs-as-Code: Diffable, Reviewable, Versioned

Because .adoc files are plain text, they sit in the same Git repository as the firmware. Architecture changes go through pull requests, get reviewed line-by-line, and carry the same history as the code they describe. No more architecture_final_v3_REALLY_final.docx.

2. Diagrams-as-Code (No Manual Drawing)

With PlantUML embedded directly in the document, your component and sequence diagrams are text you can diff. When the architecture changes, you edit a few lines instead of dragging boxes in a drawing tool — and the diagram is regenerated automatically on build.

3. Built for arc42

The arc42 template — the de-facto standard for documenting software architecture — ships an official AsciiDoc version. Its 12 chapters (Introduction & Goals, Constraints, Context, Building Blocks, Runtime View, Deployment, Crosscutting Concepts, Decisions, Quality, Risks, Glossary) map cleanly onto AsciiDoc include:: directives, so each chapter is its own file stitched into one master document.

4. Single Source, Many Outputs

Write once; publish as HTML (for the team wiki/site), PDF (for formal sign-off and audits), or DocBook. Safety-critical and industrial projects frequently need a stamped PDF for the quality record — AsciiDoc gives you that from the same source the developers edit.

5. Richer Than Markdown

Cross-references (<<section-id>>), automatic table of contents, numbered sections, footnotes, admonition callouts, conditional content, and include:: for splitting large docs — all the structure a real architecture document needs, which Markdown lacks natively.

Cost & Licensing — Is AsciiDoc Free?

Yes, completely free and open source. There are no license fees, no per-seat costs, and nothing to phone home.

The MIT license on Asciidoctor is about as permissive as it gets: you can use it in commercial, closed-source, and safety-critical products with no obligation to publish anything. PlantUML is dual-licensed (GPL/LGPL among others) but is invoked as an external tool to generate images — it does not link into or contaminate your firmware or documents, so there is no licensing concern for the output.

NOTE: Optional commercial add-ons exist (for example, hosted Kroki diagram servers or PDF theming services), but nothing in the core toolchain above requires payment.

Quick-Start Checklist

  • Install Ruby (RubyInstaller+Devkit on Windows)
  • gem install asciidoctor asciidoctor-pdf asciidoctor-diagram
  • Install Java (for PlantUML diagrams)
  • Install the VS Code “AsciiDoc” extension (asciidoctor)
  • Download the arc42 AsciiDoc template from https://arc42.org/download
  • Write .adoc files, commit them next to your source code
  • Build HTML: asciidoctor -r asciidoctor-diagram doc.adoc
  • Build PDF: asciidoctor-pdf -r asciidoctor-diagram doc.adoc
  • Add the build commands to CI so docs regenerate on every push

FAQ

Is AsciiDoc better than Markdown for architecture docs?

For large, structured documents — yes. AsciiDoc has native cross-references, includes, numbered sections, admonitions, and built-in PDF/diagram support that Markdown needs plugins to approximate. For a quick README, Markdown is fine.

Do I have to use Ruby?

The reference processor is Ruby-based, but Asciidoctor.js (Node) and AsciidoctorJ (JVM) exist if you prefer. Most teams use the Ruby toolchain because asciidoctor-pdf and asciidoctor-diagram are most mature there.

Can I version diagrams in Git?

Yes — that’s the main draw. PlantUML diagrams are written as text inside the .adoc file, so they diff and review like code and regenerate on build.

Is it really free for commercial / safety-critical products?

Yes. The core toolchain is MIT-licensed (and arc42 is Creative Commons). There is no fee and no copyleft obligation on your documents or firmware.

Author: Hoa Nguyen | Toolchain: Asciidoctor + asciidoctor-pdf + asciidoctor-diagram (PlantUML) | Use case: arc42 architecture documentation for the NEXSealion Control Unit (NXP i.MX RT1062)

💬 Questions, corrections, or your own war story with AsciiDoc toolchains? Leave a comment below — I read and answer all of them.