{"id":19293038,"url":"https://github.com/avisi-cloud/structurizr-site-generatr","last_synced_at":"2025-05-16T11:05:34.706Z","repository":{"id":37080692,"uuid":"504087853","full_name":"avisi-cloud/structurizr-site-generatr","owner":"avisi-cloud","description":"Static site generator for architecture models created with Structurizr DSL","archived":false,"fork":false,"pushed_at":"2025-05-07T16:53:44.000Z","size":10995,"stargazers_count":268,"open_issues_count":20,"forks_count":40,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-05-07T17:46:23.122Z","etag":null,"topics":["c4model","documentation","site-generator","structurizr"],"latest_commit_sha":null,"homepage":"https://avisi-cloud.github.io/structurizr-site-generatr/","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/avisi-cloud.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-06-16T09:12:04.000Z","updated_at":"2025-04-25T08:48:01.000Z","dependencies_parsed_at":"2024-02-02T08:46:54.274Z","dependency_job_id":"3e4ab18d-66a6-427c-89c5-1d20696edbac","html_url":"https://github.com/avisi-cloud/structurizr-site-generatr","commit_stats":null,"previous_names":[],"tags_count":46,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avisi-cloud%2Fstructurizr-site-generatr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avisi-cloud%2Fstructurizr-site-generatr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avisi-cloud%2Fstructurizr-site-generatr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avisi-cloud%2Fstructurizr-site-generatr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/avisi-cloud","download_url":"https://codeload.github.com/avisi-cloud/structurizr-site-generatr/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254518384,"owners_count":22084374,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c4model","documentation","site-generator","structurizr"],"created_at":"2024-11-09T22:33:53.708Z","updated_at":"2025-05-16T11:05:29.698Z","avatar_url":"https://github.com/avisi-cloud.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- TOC --\u003e\n* [Structurizr Site Generatr](#structurizr-site-generatr)\n  * [Features](#features)\n  * [Getting Started](#getting-started)\n    * [Installation using Homebrew - Recommended](#installation-using-homebrew---recommended)\n    * [Manual installation](#manual-installation)\n    * [Docker](#docker)\n      * [[Optional] Verify the Structurizr Site Generatr image with CoSign](#optional-verify-the-structurizr-site-generatr-image-with-cosign)\n  * [Usage](#usage)\n    * [Help](#help)\n    * [Version](#version)\n    * [Generate a website](#generate-a-website)\n      * [From a C4 Workspace](#from-a-c4-workspace)\n      * [For those taking the Docker approach](#for-those-taking-the-docker-approach)\n      * [Generate a website from a Git repository](#generate-a-website-from-a-git-repository)\n    * [Start a development web server around the generated website](#start-a-development-web-server-around-the-generated-website)\n      * [For those taking the Docker approach](#for-those-taking-the-docker-approach-1)\n  * [Customizing the generated website](#customizing-the-generated-website)\n  * [Contributing](#contributing)\n  * [Background](#background)\n\u003c!-- TOC --\u003e\n\n# Structurizr Site Generatr\n\nA static site generator for [C4 architecture models](https://c4model.com/) created with [Structrizr DSL](https://docs.structurizr.com/dsl).\nSee [Background](#background) for the story behind this tool.\n\n[Click here to see an example of a generated site](https://avisi-cloud.github.io/structurizr-site-generatr) based on\nthe [Big Bank plc example](https://structurizr.com/dsl?example=big-bank-plc) from \u003chttps://structurizr.com\u003e. This site\nis generated from the example workspace in this repository.\n\n## Features\n\n- Generate a static HTML site, based on a Structurizr DSL workspace.\n- Generates diagrams in SVG, PNG and PlantUML format, which can be viewed and downloaded from the generated site.\n- Easy browsing through the site by clicking on software system and container elements in the diagrams. Note that\n  external software systems are excluded from the menu. A software system is considered external when it lives outside\n  the (deprecated) enterprise boundary or when it contains a specific tag, see [Customizing the generated website](#customizing-the-generated-website). \n- Start a development server which generates a site, serves it and updates the site automatically whenever a file that's\n  part of the Structurizr workspace changes.\n- Include documentation (in Markdown or AsciiDoc format) in the generated site. Both workspace level documentation and software\n  system level documentation are included in the site.\n- Include ADR's in the generated site. Again, both workspace level ADR's and software system level ADR's are included in\n  the site.\n- Include static assets in the generated site, which can be used in ADR's and documentation.\n- Generate a site from a Structurizr DSL model in a Git repository. Supports multiple branches, which makes it possible\n  to for example maintain an actual state in `master` and one or more future states in feature branches. The generated\n  site includes diagrams for all valid configured or detected branches.\n- Include a version number in the generated site.\n\n## Getting Started\n\nTo get started with the Structurizr Site Generatr, you can either:\n\n- Install it to your local machine (recommended for the best experience), or\n- Execute it on your local machine via a container (requires Docker)\n\n**Please note**: The intended use of the Docker image is to generate a site from a CI pipeline. Using it for model\ndevelopment is possible, but not a usage scenario that's actively supported.\n\n### Installation using Homebrew - Recommended\n\nAs this approach relies on [Homebrew](https://brew.sh/), ensure this is already installed. For Windows and other\noperating systems not supported by Homebrew, please use the [Docker approach](#docker) instead.\n\nTo install Structurizr Site Generatr execute the following commands in your terminal:\n\n```shell\nbrew tap avisi-cloud/tools\nbrew install structurizr-site-generatr\n\nstructurizr-site-generatr --help\n```\n\nPeriodically, you would have to update your local installation to take advantage of any new\n[Structurizr Site Generatr releases](https://github.com/avisi-cloud/structurizr-site-generatr/releases).\n\n### Manual installation\n\nIf using Homebrew is not an option for you, it's also possible to install Structurizr Site Generatr manually. This can\nbe done as follows:\n\n- Consult the\n  [Structurizr Site Generatr releases](https://github.com/avisi-cloud/structurizr-site-generatr/releases) and choose\n  the version you wish to use\n- Download the `.tar.gz` or `.zip` distribution\n- Extract the archive using your favourite tool\n- For ease of use, it's recommended to add Structurizr Site Generatr's `bin` directory to your `PATH`\n\n### Docker\n\nThough local installation is recommended for development where possible, Structurizr Site Generatr is also a packaged\nas a Docker image. Therefore, to use this approach, ensure [Docker](https://www.docker.com/) is already installed.\nAdditionally, for Windows 10+ users, you may want to take advantage of\n[WSL2](https://docs.microsoft.com/en-us/windows/wsl/install) (Windows Subsystem for Linux). Both Docker and WSL2\nare topics too vast to repeat here, so you are invited to study these as prerequisite learning for this approach.\n\nThen to download our packaged image, consider the\n[Structurizr Site Generatr releases](https://github.com/avisi-cloud/structurizr-site-generatr/releases) and choose\nthe version you wish to use. Then, in your terminal, execute the following:\n\n```shell\ndocker pull ghcr.io/avisi-cloud/structurizr-site-generatr\n```\n\nOnce downloaded, you can execute Structurizr Site Generatr via a temporary Docker container by executing the\nfollowing in your terminal:\n\n```shell\ndocker run -it --rm ghcr.io/avisi-cloud/structurizr-site-generatr --help\n```\n\n#### [Optional] Verify the Structurizr Site Generatr image with [CoSign](https://github.com/sigstore/cosign)\n\n```shell\ncat cosign.pub\n-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEzezKl0vAWSHosQ0JLEsDzNBd2nGm\n08KqX+imYqq2avlbH+ehprJFMqKK0/I/bY0q5W9hQC8SLzTRJ9Q5dB9UiQ==\n-----END PUBLIC KEY-----\ncosign verify --key cosign.pub ghcr.io/avisi-cloud/structurizr-site-generatr\n```\n\nOr by using the Github repo url:\n\n```shell\n cosign verify --key https://github.com/avisi-cloud/structurizr-site-generatr ghcr.io/avisi-cloud/structurizr-site-generatr\n ```\n\n## Usage\n\nThese examples use the [example workspace](docs/example) in this repository.\n\nOnce installed, Structurizr Site Generatr is operated via your terminal by issuing commands. Each command is\nexplained here:\n\n### Help\n\nTo learn about available commands, or parameters for individual commands, call Structurizr Site Generatr with the\n`--help` argument.\n\n```shell\ninstalled\u003e structurizr-site-generatr --help\n\n   docker\u003e docker run -it --rm ghcr.io/avisi-cloud/structurizr-site-generatr --help\n\nUsage: structurizr-site-generatr options_list\nSubcommands:\n    serve - Start a development server\n    generate-site - Generate a site for the selected workspace.\n    version - Print version information\n\nOptions:\n    --help, -h -\u003e Usage info\n```\n\n### Version\n\nTo query the version of Structurizr Site Generatr installed / used.\n\n```shell\ninstalled\u003e structurizr-site-generatr version\n\n   docker\u003e docker run -it --rm ghcr.io/avisi-cloud/structurizr-site-generatr version\n\nStructurizr Site Generatr v1.1.3\n```\n\n### Generate a website\n\n#### From a [C4 Workspace](https://docs.structurizr.com/dsl)\n\nThis is the primary use case of Structurizr Site Generatr -- to generate a website from a\n[C4 Workspace](https://docs.structurizr.com/dsl).\n\n```shell\ninstalled\u003e structurizr-site-generatr generate-site --workspace-file workspace.dsl --assets-dir assets\n\n   docker\u003e docker run -it --rm -v c:/projects/c4:/var/model ghcr.io/avisi-cloud/structurizr-site-generatr generate-site --workspace-file workspace.dsl --assets-dir assets\n```\n\nHere, the `--workspace-file` or `-w` parameter specifies the input\n[C4 Workspace DSL file](https://docs.structurizr.com/dsl) to the `generate-site` command. The `--assets-dir` or `-a` parameter is not\nrequired, but usually needed as well. Additional parameters that affect website generation can be reviewed\nusing the `--help` operator.\n\nBy default, the generated website will be placed in `./build`, which is overwritten if it already exisits.\n\n#### For those taking the Docker approach\n\nWhen using the Docker approach, the local file system must be made available to the temporary Structurizr Site\nGeneratr container via a\n[Docker file system volume mount](https://docs.docker.com/engine/reference/commandline/run/#mount-volume--v---read-only).\nThis is achieved by specifying the `-v` parameter with a linux-like **absolute** path to the folder containing\nthe .dsl file specified via `-w`. See how `C:\\Projects\\C4` has become `-v c:/projects/c4:/var/model` in the above\nexample?\n\n#### Generate a website from a Git repository\n\nInstead of relying on local .dsl files only, the `generate-site` command can also retrieve input files from a\nGit repository as follows. This is particularly advantageous for demos, documentation, or CI/CD pipelines.\n\nTo explicitly name the branches that you want to build sites from you can use the --branches option.\n\n```shell\nstructurizr-site-generatr generate-site\n    --git-url https://github.com/avisi-cloud/structurizr-site-generatr.git\n    --workspace-file docs/example/workspace.dsl\n    --assets-dir docs/example/assets\n    --branches main,future,old\n    --default-branch main\n```\n\nor you can choose to build all branches that are found in the repository and exclude specific ones by using the --all-branches and --exclude-branches options.\n\n```shell\nstructurizr-site-generatr generate-site\n    --git-url https://github.com/avisi-cloud/structurizr-site-generatr.git\n    --workspace-file docs/example/workspace.dsl\n    --assets-dir docs/example/assets\n    --all-branches\n    --exclude-branches gh-pages\n    --default-branch main\n```\n\nBoth the --branches and --exclude-branches options are comma separated lists and can contain multiple branch names.\n\n### Start a development web server around the generated website\n\nTo aid composition of [C4 Workspace DSL files](https://docs.structurizr.com/dsl), the `serve` command will\ngenerate a website from the input .dsl specified with `-w` _and_ start a web server to view it. **Default port** for the web server is **8080**.\nA different port for the web server can be specified with `-p PORT`. Additional parameters that affect website generation and the development\nweb server can be reviewed using the `--help` operator.\n\n```shell\ninstalled\u003e structurizr-site-generatr serve -w workspace.dsl\n\n   docker\u003e docker run -it --rm -v c:/projects/c4:/var/model -p 8080:8080 ghcr.io/avisi-cloud/structurizr-site-generatr serve --workspace-file workspace.dsl --assets-dir assets\n```\n\nBy default, a development web server will be started and accessible at http://localhost:8080/ (if available).\n\n#### For those taking the Docker approach\n\nHowever, when using the Docker approach, this development web server is within the temporary Structurizr Site\nGeneratr container. So\n[Docker port mapping](https://docs.docker.com/engine/reference/commandline/run/#publish-or-expose-port--p---expose)\nis needed to expose the container's port 8080 to the host (web browser). In the example above, the\n`-p 8080:8080` argument tells Docker to bind the local machine / host's port 8080 to the container's port 8080.\n\n## Customizing the generated website\n\nBy default, the site generator uses the\n[C4PlantUmlExporter](https://docs.structurizr.com/export/plantuml#c4plantumlexporter)\nto generate the diagrams. When using this exporter, all properties available for the C4PlantUMLExporter, e.g. `c4plantuml.tags`, can be applied\nand affect the diagrams in the generate site. See also [Diagram notation](https://docs.structurizr.com/export/comparison) for an overview of supported features\nand limitations for this exporter.\n\nThe look and feel of the generated site can be customized with several additional view properties in the C4\narchitecture model:\n\n| Property name                           | Description                                                                                                                                                                                                                                                                                                                                      | Default                        | Example                                              |\n|-----------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------|------------------------------------------------------|\n| `generatr.style.colors.primary`         | Primary site color, used for header bar background and active menu background.                                                                                                                                                                                                                                                                   | `#333333`                      | `#485fc7`                                            |\n| `generatr.style.colors.secondary`       | Secondary site color, used for font color in header bar and for active menu.                                                                                                                                                                                                                                                                     | `#cccccc`                      | `#ffffff`                                            |\n| `generatr.style.faviconPath`            | Site logo location relative to the configured `assets` folder. When configured, the logo image will be place on the left side in the header bar. This requires the `--assets-dir` switch when generating the site and the corresponding file to be available in the `assets` folder.                                                             |                                | `site/favicon.ico`                                   |\n| `generatr.style.logoPath`               | Site favicon location relative to the configured `assets` folder. When configured, the favicon will be set for all generated pages. This requires the `--assets-dir` switch when generating the site and the corresponding file to be available in the `assets` folder.                                                                          |                                | `site/logo.png`                                      |\n| `generatr.style.customStylesheet`       | URL to hosted custom stylesheet or path to custom stylesheet file (location relative to the configured `assets` folder). When configured this css file will be loaded for all pages. When using a path to a file the `--assets-dir` switch must be used when generating the site and the corresponding file is available in the `assets` folder. |                                | `site/custom.css` or 'https://uri.example/custom.css |\n| `generatr.search.language`              | Indexing/stemming language for the search index. See [Lunr language support](https://github.com/olivernn/lunr-languages)                                                                                                                                                                                                                         | `en`                           | `nl`                                                 |\n| `generatr.markdown.flexmark.extensions` | Additional extensions to the markdown generator to add new markdown capabilities. [More Details](https://avisi-cloud.github.io/structurizr-site-generatr/main/extended-markdown-features/)                                                                                                                                                       | Tables                         | `Tables,Admonition`                                  |\n| `generatr.svglink.target`               | Specifies the link target for element links in the exported svg                                                                                                                                                                                                                                                                                  | `_top`                         | `_self`                                              |\n| `generatr.site.exporter`                | Specifies the UML exporter, can be `c4` (uses the `C4PlantUMLExporter`) or `structurizr` (uses the `StructurizrPlantUMLExporter`)                                                                                                                                                                                                                | `c4`                           | `structurizr`                                        |\n| `generatr.site.externalTag`             | Software systems containing this tag will be considered external                                                                                                                                                                                                                                                                                 |                                |                                                      |\n| `generatr.site.nestGroups`              | Will show software systems in the left side navigator in collapsable groups                                                                                                                                                                                                                                                                      | `false`                        | `true`                                               |\n| `generatr.site.cdn`                     | Specifies the CDN base location for fetching NPM packages for browser runtime dependencies. Defaults to jsDelivr, but can be changed to e.g. an on-premise location.                                                                                                                                                                             | `https://cdn.jsdelivr.net/npm` | `https://cdn.my-company/npm`                         |\n| `generatr.site.theme`                   | Experimental: allows to force a light or dark theme or allows to switch between light and dark mode on the website with browser preference or menu item. Possible values are 'light', 'dark' or 'auto'. Note that the 'structurizr' exporter (see 'generatr.site.exporter' setting) generally works better for the dark theme.                   | `light`                        | `auto`                                               |\n\nTo control the behavior of views, apply the following properties:\n\n| Property name                        | Description                                                                  | Value                | Scope           |\n|--------------------------------------|------------------------------------------------------------------------------|----------------------|-----------------|\n| `generatr.view.deployment.belongsTo` | Associate the diagram into the Deployment tab of a specific software system. | software system name | deployment view |\n\nSee the included example for usage of some those properties in the\n[C4 architecture model example](https://github.com/avisi-cloud/structurizr-site-generatr/blob/main/docs/example/workspace.dsl#L163).\n\n## Contributing\n\nWe welcome contributions! Please refer to [CONTRIBUTING.md](CONTRIBUTING.md) for more information on how you can help.\n\n## Background\n\nAt Avisi, we're big fans of the [C4 model](https://c4model.com). We use it in many projects, big and small, to document\nthe architecture of the systems and system landscapes we're working on.\n\nWe started out by using PlantUML, combined with the [C4 extension](https://github.com/plantuml-stdlib/C4-PlantUML). This\nworks well for small systems. However, for larger application landscapes, maintained by multiple development teams, this\nlead to duplication and inconsistency across diagrams.\n\nTo solve this problem, we needed a model based approach. Rather than maintaining separate diagrams and trying to keep\nthem consistent, we needed to have a single model, from which diagrams could be generated. This is why we started using\nthe [Structurizr for Java](https://github.com/structurizr/java) library. About a year later, we migrated our models to\nStructurizr DSL.\n\nWe created custom tooling to generate diagrams and check them in to our Git repository. All diagrams could be seen by\nnavigating to our GitLab repository. This is less than ideal, because we like to make these diagrams easily accessible\nto everyone, including our customers. This is why we decided that we needed a way of publishing our models to an easily\naccessible website.\n\nThis tool is the result. It's still a work in progress, but it has already proven to be very useful to us.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Favisi-cloud%2Fstructurizr-site-generatr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Favisi-cloud%2Fstructurizr-site-generatr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Favisi-cloud%2Fstructurizr-site-generatr/lists"}