While it was initially created to clean up the formatting of diagram source YAML files, its feature set has expanded over time; it now also “snaps” the elements and vertices in a diagram to a virtual grid and renders diagrams.
For the backstory of the creation of the framework and tool, see this blog post.
The tool has three main features:
When used to create or edit a diagram, Structurizr Express (re)generates the diagram source YAML in such a way that the YAML becomes noisy and the sorting can change unpredictably. This makes the source harder to work with in a text editor and impossible to usefully diff from revision to revision — and without useful diffing it’s very difficult to do effective peer review. And peer review is a crucial element of the Docs as Code philosophy.
So this feature rewrites diagram YAML files:
…thereby facilitating the authoring, editing, and reviewing of revisions to the diagrams.
Improves the layout of Structurizr Express diagrams:
Peopleelements so they’ll align properly with other kinds of elements (working around a rendering quirk of Structurizr Express)
Given Structurizr Express diagram YAML files, creates PNG image files that contain the visualization of the diagram.
brew cask install adoptopenjdk11-jre
brew cask install chromium
MacOS quick-start for Homebrew users:
brew cask install adoptopenjdk11-jre chromium
mv ~/Downloads/fc4/fc4* ~/bin/
fc4 -fsrw path/to/diagram.yaml/or/dir
git statusand you should see that the YAML file has been created/changed and its corresponding PNG file has also been created/changed
fc4 OPTIONS PATH [PATH...]
-f | --format,
-s | --snap, and
-r | --rendermay be specified (at least one is required)
When invoked with the
-w | --watch option, instead of immediately processing the diagrams and
exiting, the tool will start up in a persistent mode, watching the YAML files and processing them
when they’re changed. To exit, press ctrl-c on your keyboard.
fc4 -r my-diagram.yamlor
fc4 --render my-diagram.yamlwould render the specified diagram
-f | --format
Reformats each specified Structurizr Express YAML file as described above.
-r | --render
Renders each specified Structurizr Express YAML file as described above.
-s | --snap
If specified, elements in diagrams will be snapped to a virtual grid.
-w | --watch
If specified, the tool will start up in a persistent mode and watch the YAML files in/under the specified paths for changes. When a file is changed, the tool will process it according to the feature options, at least one of which is required. In this mode, the tool does not process any files when first invoked.
fc4 -fsrw . would watch the current directory and all sub-directories, recursively, for
changes to diagram files; when a change is observed the diagrams, would be formatted,
snapped, and rendered.
-h | --help
Prints out usage information and exits.
-d | --debug
Enables a debug mode of dubious utility.