Create PNGs from Structurizr DSL files.

This project uses PlantUML or Graphviz to render Structurizr DSL to PNG images with various rendering strategies. Image rendering is based on exports from the Structurizr CLI. The project performs some post-processing of the workspace model to support conventions around external software systems.

• Tags are mapped to shapes in the theme.json
• Systems tagged with External, External System or Existing System will be rendered as external

• Create PNGs from DSL files
• Live preview of PNGs in your browser
• Support for multiple renderers with --render-with flag
  • c4plantuml - C4-PlantUML (default)
  • graphviz - Dot with Graphviz
  • structurizr - Structurizr PlantUML
• Control appearance with themes and view properties

The examples section showcases the output from the tool.

The project is intended to be used locally while authoring diagrams and in build pipelines workflows to automatically update diagrams in the source repository and READMEs.

The easiest way to get started with the project is to create a helper script. If using bash, create the following script and name it dsl2png.sh.

#!/bin/sh
set -e
docker pull --quiet extenda/structurizr-to-png
exec docker run --rm -it -v "$(pwd)":/docs -p 3000:3000 extenda/structurizr-to-png "$@"

Or, if you're using Windows, create dsl2png.cmd.

@echo off
docker pull --quiet extenda/structurizr-to-png
docker run --rm -it -v "%CD%":/docs -p 3000:3000 extenda/structurizr-to-png %*

With these scripts, users will be upgraded to the latest available version and also don't need to remember the lengthy docker command. To watch a directory for changes to DSL files, simply run:

./dsl2png.sh --watch

$ docker run --rm -it -v $(pwd):/docs extenda/structurizr-to-png

The convention is to generate diagrams to an images/ directory inside the working directory. The default working directory used in the container is /docs. The above command will render all *.dsl files in the current working directory and it's subdirectories.

To render particular dsl files, use the --path option (glob is supported). Relative paths are treated from DSL file directory.

$ docker run --rm -it -v $(pwd):/docs extenda/structurizr-to-png --path workspace.ecd.dsl

To change the default output location, use the --output option. If specified as a relative path, it is resolved from DSL file directory.

$ docker run --rm -it -v $(pwd):/docs extenda/structurizr-to-png --output c4-diagrams

The above example will write files to the c4-diagrams directory in the current working directory.

To use the live preview functionality, we must add the --watch flag and a port binding.

$ docker run --rm -it -v $(pwd):/docs -p 3000:3000 extenda/structurizr-to-png --watch

Open https://localhost:3000 in your browser to see the preview images. The images will update when the DSL is changed.

The examples are created from demo.dsl.

All renderers support Structurizr themes. The theme must be reachable on a public URL. If no theme is specified the dsl-to-png theme will be used.

Renderers may also support output options, typically controlled with view properties.

The following view properties are supported with the c4plantuml renderer.

Here's an example on how to use them to disable the diagram legend and the title.

views {
  container system {
    include *
    properties {
      c4plantuml.legend false
      plantuml.title false
    }
  }
}

The following view properties are supported with the structurizr renderer.

• The project is built with Java 17 and Maven.
  • mvn verify to build and run all tests
  • java -jar target/structurizr-to-png.jar runs the client on your local machine
• Running locally requires Graphviz
• Make sure to install pre-commit hooks and use them

pre-commit install -t pre-commit -t commit-msg

• Commit messages must follow conventional commits
• SonarCloud quality gates must pass for all pull requests

This project is licensed under the MIT license.