Documentation

Because the code doesn't tell the whole story, Structurizr also provides support for lightweight supplementary technical documentation, based upon a number of popular templates. You can also create your own custom template.

The documentation is a collection of Markdown or AsciiDoc documents, one per section, which are rendered in the web browser. This content is uploaded in a workspace along with the software architecture model, which makes it easy to embed diagrams from that workspace.

Getting started

You can find some documentation and examples on both the Structurizr for Java and Structurizr for .NET GitHub repositories.

Software guidebook

Software guidebook

The "software guidebook" from Simon Brown's Software Architecture for Developers: Volume 2 book.

GitHub Java Markdown AsciiDoc

Software guidebook

arc42

The arc42 template, by Dr. Gernot Starke and Dr. Peter Hruschka.

GitHub Java Markdown AsciiDoc

Software guidebook

Viewpoints and Perspectives

The Viewpoints and Perspectives template, from Software Systems Architecture by Nick Rozanski and Eoin Woods.

GitHub Java Markdown AsciiDoc

Markdown

The markdown-it library is used to render the documentation content in the web browser. This is a comprehensive implementation of the Markdown format, providing support for all of the basic elements such as paragraphs, lists, images, etc.

Embedding software architecture diagrams

In addition to the usual Markdown syntax, you can embed diagrams from the workspace into your documentation using the following syntax.

![](embed:MyDiagramKey)

This will embed the diagram with the key MyDiagramKey into the documentation page.

Images

Images can be included using the regular Markdown syntax. For this to work, the image files must be hosted externally (e.g. on your own web server) or uploaded with your workspace.

UML diagrams

You can also use services such as yUML to include UML diagrams. For example:

![A simple UML class diagram]( http://yuml.me/diagram/nofunky/class/[Class A]->[Class B] )

AsciiDoc

The asciidoctor.js library is used to render the documentation content in the web browser, supporting all of the basic elements such as paragraphs, lists, images, etc.

Embedding software architecture diagrams

In addition to the usual AsciiDoc syntax, you can embed diagrams from the workspace into your documentation using the following syntax.

image::embed:MyDiagramKey[]

This will embed the diagram with the key MyDiagramKey into the documentation page.

Images

Images can be included using the regular AsciiDoc syntax. For this to work, the image files must be hosted externally (e.g. on your own web server) or uploaded with your workspace.

Headings and sections

Structurizr will automatically generate the first two top-level headings for you as follows:

  • Heading level 1: Software system name
  • Heading level 2: Documentation section name (e.g. "1. Context")

For this reason, and depending upon the format being used, specific heading types will be hidden in the rendered content. See this example Markdown file and how it is rendered in Structurizr.

Markdown

When using Markdown, # Heading level 1 and ## Heading level 2 will be hidden in the rendered content, with ### Heading level 3 automatically becoming navigable sub-section headings.

AsciiDoc

When using AsciiDoc, = Document Title (Level 0) and == Level 1 Section Title will be hidden in the rendered content, with === Level 2 Section Title automatically becoming navigable sub-section headings.