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
The "software guidebook" from Simon Brown's Software Architecture for Developers: Volume 2 book.
Viewpoints and Perspectives
The Viewpoints and Perspectives template, from Software Systems Architecture by Nick Rozanski and Eoin Woods.
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.
This will embed the diagram with the key MyDiagramKey into the documentation page.
Alternatively, if your workspace is public or shareable with a link, you can use the URL of the published image, such as
https://structurizr.com/share/1/images/context.png instead.
Structurizr will see that this link corresponds to a diagram in your workspace,
and replace the static PNG image with a live embedded version.
Using this approach means that your Markdown files will be rendered to include the static image when used outside of Structurizr.
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:
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.
Alternatively, if your workspace is public or shareable with a link, you can use the URL of the published image, such as
https://structurizr.com/share/1/images/context.png instead.
Structurizr will see that this link corresponds to a diagram in your workspace,
and replace the static PNG image with a live embedded version.
Using this approach means that your AsciiDoc files will be rendered to include the static image when used outside of Structurizr.
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.