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.

Please note that Structurizr's documentation feature may not render your Markdown/AsciiDoc in exactly the same way that other dedicated documentation tools will, and some features may not be supported. If you need full control over the look and feel of your documentation, you may be better to use an external tool (e.g. Asciidoctor, Hugo, Jekyll, etc) in conjunction with the iframe embed or image embed features.

Examples and templates

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

Publishing existing Markdown/AsciiDoc documentation

If you have a folder full of existing MarkDown/AsciiDoc documentation, you can use one of the Structurizr client libraries to import that into a workspace. Alternatively, you can use the Structurizr CLI tool to publish existing documentation into a workspace.

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.

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:

![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.

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.