diff --git a/dsl/adrs.md b/dsl/adrs.md new file mode 100644 index 0000000..02db6ad --- /dev/null +++ b/dsl/adrs.md @@ -0,0 +1,29 @@ +--- +layout: default +title: Architecture Decision Records (ADRs) +parent: Structurizr DSL +nav_order: 9 +permalink: /dsl/adrs +--- + +# Architecture decision records (ADRs) + +The `!adrs` keyword can be used to attach Markdown/AsciiDoc ADRs to the parent context (either the workspace, a software system, or a container). + +``` +!adrs [fully qualified class name] +``` + +The path must be a relative path, located within the same directory as the parent file, or a subdirectory of it. For example: + +``` +!adrs subdirectory +``` + +By default, the [com.structurizr.documentation.importer.AdrToolsDecisionImporter](https://github.com/structurizr/documentation/blob/main/src/main/java/com/structurizr/documentation/importer/AdrToolsDecisionImporter.java) class will be used to import ADRs as follows: + +- All Markdown files in this directory will be imported, alphabetically according to the filename. +- The files must have been created by [adr-tools](https://github.com/npryce/adr-tools), or at least follow the same format. +- All images in the given directory (and sub-directories) are also imported into the workspace. + +The above behaviour can be customised by specifying the fully qualified class name of your own implementation of [DocumentationImporter](https://github.com/structurizr/documentation/blob/main/src/main/java/com/structurizr/documentation/importer/DocumentationImporter.java), which needs to be on the DSL classpath or installed as a JAR file in the `plugins` directory next to your DSL file. diff --git a/dsl/basics.md b/dsl/basics.md index e09179c..89df6bf 100644 --- a/dsl/basics.md +++ b/dsl/basics.md @@ -2,7 +2,8 @@ layout: default title: Basics parent: Structurizr DSL -nav_order: 1 +nav_order: 2 +permalink: /dsl/basics --- # Basics @@ -32,6 +33,16 @@ In addition, workspaces are subject to the following rules: - Infrastructure node names must be unique with their parent context. - All relationships from a source element to a destination element must have a unique description. +## Implied relationships + +``` +!impliedRelationships +``` + +The `!impliedRelationships` keyword provides a way to enable or disable whether implied relationships are created. +A value of `false` disables implied relationship creation, while `true` creates implied relationships between all valid combinations of the parent elements, unless any relationship already exists between them +(see [Structurizr for Java - Implied relationships - CreateImpliedRelationshipsUnlessAnyRelationshipExistsStrategy](https://github.com/structurizr/java/blob/master/docs/implied-relationships.md#createimpliedrelationshipsunlessanyrelationshipexistsstrategy) for more details). + ## Constants The `!constant` keyword can be used to define a constant, which can be used with [string substitution](#string-substitution) diff --git a/dsl/cookbook/index.md b/dsl/cookbook/index.md new file mode 100644 index 0000000..c0e4f0e --- /dev/null +++ b/dsl/cookbook/index.md @@ -0,0 +1,48 @@ +--- +layout: default +title: Cookbook +nav_order: 13 +parent: Structurizr DSL +has_children: true +permalink: /dsl/cookbook +--- + +# Structurizr DSL cookbook + +Creating software architecture diagrams from a textual definition ("diagrams as code") is becoming more popular, +but if you have a collection of related diagrams, it's easy to introduce inconsistencies if you don't keep the many +diagram source files in sync. + +This cookbook is a tutorial guide to the Structurizr DSL, an open source tool for creating diagrams as code from +a single consistent model. This cookbook assumes that you're using the diagram renderer provided by the +[Structurizr cloud service](https://structurizr.com/help/cloud-service), +the [Structurizr on-premises installation](https://structurizr.com/help/on-premises), +or [Structurizr Lite](https://structurizr.com/help/lite). +Please note that some features (e.g. perspectives, element style shapes/icons, etc) may not be supported if you're +using one of the PlantUML/Mermaid/D2/DOT/etc export formats provided by the +[Structurizr CLI](https://github.com/structurizr/cli) and the [structurizr-export library](https://github.com/structurizr/export). + +## Table of contents + +- [Workspace](workspace) +- [Workspace extension](workspace-extension) +- [Implied relationships](implied-relationships) +- [System Context view](system-context-view) +- [Container view](container-view) +- [Container view (spanning multiple software systems)](container-view-for-multiple-software-systems) +- [Component view](component-view) +- [Shared components](shared-components) +- [Image view](image-view) +- [Filtered view](filtered-view) +- [Dynamic view](dynamic-view) +- [Dynamic view with parallel sequences](dynamic-view-parallel) +- [Deployment view](deployment-view) +- [Amazon Web Services](amazon-web-services) +- [Deployment groups](deployment-groups) +- [Element styles](element-styles) +- [Relationship styles](relationship-styles) +- [Themes](themes) +- [Groups](groups) +- [Perspectives](perspectives) +- [Scripts](scripts) +- [DSL and code (hybrid usage pattern)](dsl-and-code) \ No newline at end of file diff --git a/dsl/cookbook/workspace/example-1.dsl b/dsl/cookbook/workspace/example-1.dsl new file mode 100644 index 0000000..5e6388a --- /dev/null +++ b/dsl/cookbook/workspace/example-1.dsl @@ -0,0 +1,9 @@ +workspace "Name" "Description" { + + model { + } + + views { + } + +} diff --git a/dsl/cookbook/workspace/index.md b/dsl/cookbook/workspace/index.md new file mode 100644 index 0000000..eda6993 --- /dev/null +++ b/dsl/cookbook/workspace/index.md @@ -0,0 +1,32 @@ +--- +layout: default +title: Workspace +nav_order: 1 +parent: Cookbook +grand_parent: Structurizr DSL +has_children: true +permalink: /dsl/cookbook/workspace +--- + +# Workspace + +In Structurizr terminology, a "workspace" is a wrapper for a software architecture model (elements and relationships) and views. + +``` +workspace "Name" "Description" { + + model { + } + + views { + } + +} +``` + +A workspace can be given a name and description, although these are only used by the [Structurizr cloud service and on-premises installation](https://structurizr.com) - you don't need to specify a name/description if you're exporting views to one of the export formats (PlantUML, Mermaid, etc). + +## Links + +- [DSL language reference - workspace](/dsl/language#workspace) +- [Example](http://structurizr.com/dsl?src=https://docs.structurizr.com/dsl/cookbook/workspace/example-1.dsl) diff --git a/dsl/defaults.md b/dsl/defaults.md index c1f9e2a..ebfe835 100644 --- a/dsl/defaults.md +++ b/dsl/defaults.md @@ -2,7 +2,8 @@ layout: default title: Defaults parent: Structurizr DSL -nav_order: 2 +nav_order: 3 +permalink: /dsl/defaults --- # Defaults diff --git a/dsl/docs.md b/dsl/docs.md new file mode 100644 index 0000000..d65c114 --- /dev/null +++ b/dsl/docs.md @@ -0,0 +1,30 @@ +--- +layout: default +title: Markdown/Asciidoc Documentation +parent: Structurizr DSL +nav_order: 8 +permalink: /dsl/docs +--- + +# Documentation + +The `!docs` keyword can be used to attach Markdown/AsciiDoc documentation to the parent context (either the workspace, a software system, or a container). + +``` +!docs [fully qualified class name] +``` + +The path must be a relative path, located within the same directory as the parent file, or a subdirectory of it. For example: + +``` +!docs subdirectory +``` + +By default, the [com.structurizr.importer.documentation.DefaultDocumentationImporter](https://github.com/structurizr/documentation/blob/main/src/main/java/com/structurizr/importer/documentation/DefaultDocumentationImporter.java) class will be used to import documentation as follows: + +- All Markdown and AsciiDoc files in the given directory will be imported, alphabetically according to the filename. +- All images in the given directory (and sub-directories) are also imported into the workspace. +- See [Structurizr - Documentation - Headings and sections](https://structurizr.com/help/documentation/headings) for details about how section headings and numbering are handled. + +The above behaviour can be customised by specifying the fully qualified class name of your own implementation of [DocumentationImporter](https://github.com/structurizr/documentation/blob/main/src/main/java/com/structurizr/importer/documentation/DocumentationImporter.java), which needs to be on the DSL classpath or installed as a JAR file in the `plugins` directory next to your DSL file. + diff --git a/dsl/example.md b/dsl/example.md new file mode 100644 index 0000000..355140e --- /dev/null +++ b/dsl/example.md @@ -0,0 +1,42 @@ +--- +layout: default +title: Example +parent: Structurizr DSL +nav_order: 1 +permalink: /dsl/example +--- + +# Structurizr DSL + +The Structurizr DSL provides a way to define a software architecture model +(based upon the [C4 model](https://c4model.com)) using a text-based domain specific language (DSL). +The Structurizr DSL has appeared on the +[ThoughtWorks Tech Radar - Techniques - Diagrams as code](https://www.thoughtworks.com/radar/techniques/diagrams-as-code) +and is text-based wrapper around the [Structurizr for Java library](https://github.com/structurizr/java). + +## Example + +As an example, the following DSL can be used to create a software architecture __model__ and +an associated __view__ that describes a user using a software system. + +``` +workspace { + + model { + user = person "User" + softwareSystem = softwareSystem "Software System" + + user -> softwareSystem "Uses" + } + + views { + systemContext softwareSystem { + include * + autolayout lr + } + } + +} +``` + +![Example system context diagram](/assets/images/dsl/example.png) \ No newline at end of file diff --git a/dsl/expressions.md b/dsl/expressions.md index 9358483..6086e26 100644 --- a/dsl/expressions.md +++ b/dsl/expressions.md @@ -2,17 +2,21 @@ layout: default title: Expressions parent: Structurizr DSL -nav_order: 5 +nav_order: 6 +permalink: /dsl/expressions --- # Expressions The Structurizr DSL supports a number of expressions for use when including or excluding elements/relationships on views. +Please note that expressions are not supported on dynamic views. + +## Element expressions - `->`: the specified element(s) plus afferent couplings - `->`: the specified element(s) plus efferent couplings - `->->`: the specified element(s) plus afferent and efferent couplings -- `element.type==`: elements of the specified type (Person, SoftwareSystem, Container, Component, DeploymentNode, InfrastructureNode, SoftwareSystemInstance, ContainerInstance, Custom) +- `element.type==`: elements of the specified type (`Person`, `SoftwareSystem`, `Container`, `Component`, `DeploymentNode`, `InfrastructureNode`, `SoftwareSystemInstance`, `ContainerInstance`, `Custom`) - `element.parent==`: elements with the specified parent - `element.tag==[,tag]`: all elements that have all of the specified tags - `element.tag!=[,tag]`: all elements that do not have all of the specified tags @@ -20,6 +24,8 @@ The Structurizr DSL supports a number of expressions for use when including or e - `element==->`: the specified element plus efferent couplings - `element==->->`: the specified element plus afferent and efferent couplings +## Relationship expressions + - `*->*`: all relationships - `->*`: all relationships with the specified source element - `*->`: all relationships with the specified destination element @@ -32,5 +38,3 @@ The Structurizr DSL supports a number of expressions for use when including or e - `relationship==->*`: all relationships with the specified source element - `relationship==*->`: all relationships with the specified destination element - `relationship==->`: all relationships between the two specified elements - -Element and relationship expressions are not supported on dynamic views. \ No newline at end of file diff --git a/dsl/identifiers.md b/dsl/identifiers.md index 8177ca1..1118b0c 100644 --- a/dsl/identifiers.md +++ b/dsl/identifiers.md @@ -2,7 +2,8 @@ layout: default title: Identifiers parent: Structurizr DSL -nav_order: 3 +nav_order: 5 +permalink: /dsl/identifiers --- # Identifiers @@ -37,7 +38,7 @@ Identifiers are only needed where you plan to reference the element/relationship ## Identifier scope -By default, all identifiers are treated as being globally scoped and `flat`, so the following will fail with an error message saying that the `api` identifier is already in use. +By default, all identifiers are treated as being globally scoped, so the following will fail with an error message saying that the `api` identifier is already in use. ``` workspace { diff --git a/dsl/includes.md b/dsl/includes.md index 026e242..ada94d9 100644 --- a/dsl/includes.md +++ b/dsl/includes.md @@ -2,7 +2,8 @@ layout: default title: Includes parent: Structurizr DSL -nav_order: 4 +nav_order: 6 +permalink: /dsl/includes --- # Includes diff --git a/dsl/index.md b/dsl/index.md index d75797d..1940227 100644 --- a/dsl/index.md +++ b/dsl/index.md @@ -3,7 +3,7 @@ layout: default title: Structurizr DSL nav_order: 2 has_children: true -permalink: dsl +permalink: /dsl --- # Structurizr DSL @@ -14,33 +14,6 @@ The Structurizr DSL has appeared on the [ThoughtWorks Tech Radar - Techniques - Diagrams as code](https://www.thoughtworks.com/radar/techniques/diagrams-as-code) and is text-based wrapper around the [Structurizr for Java library](https://github.com/structurizr/java). -## Example - -As an example, the following DSL can be used to create a software architecture __model__ and -an associated __view__ that describes a user using a software system. - -``` -workspace { - - model { - user = person "User" - softwareSystem = softwareSystem "Software System" - - user -> softwareSystem "Uses" - } - - views { - systemContext softwareSystem { - include * - autolayout lr - } - } - -} -``` - -![Example system context diagram](assets/images/dsl/example.png) - ## Rendering tools The Structurizr DSL itself does not create diagrams, and is rendering tool independent, diff --git a/dsl/grammar.md b/dsl/language.md similarity index 90% rename from dsl/grammar.md rename to dsl/language.md index 2280e37..8042152 100644 --- a/dsl/grammar.md +++ b/dsl/language.md @@ -1,13 +1,14 @@ --- layout: default -title: Grammar +title: Language reference parent: Structurizr DSL -nav_order: 7 +nav_order: 12 +permalink: /dsl/language --- -# Grammar +# Language reference -The following describes the language grammar, with angle brackets (`<...>`) used to show required properties, and square brackets (`[...]`) used to show optional properties. +The following describes the language syntax and grammar, with angle brackets (`<...>`) used to show required properties, and square brackets (`[...]`) used to show optional properties. Most statements are of the form: `keyword [optional properties]` ## workspace @@ -36,24 +37,12 @@ Permitted children: - name - description - [properties](#properties) -- [!docs](#documentation) -- [!adrs](#architecture-decision-records-adrs) -- [!identifiers](#identifier-scope) -- [!impliedRelationships](#impliedrelationships) +- [!docs](#docs) +- [!adrs](#adrs) - [model](#model) - [views](#views) - [configuration](#configuration) -# !impliedRelationships - -``` -!impliedRelationships -``` - -The `!impliedRelationships` keyword provides a way to enable or disable whether implied relationships are created. -A value of `false` disables implied relationship creation, while `true` creates implied relationships between all valid combinations of the parent elements, unless any relationship already exists between them -(see [Structurizr for Java - Implied relationships - CreateImpliedRelationshipsUnlessAnyRelationshipExistsStrategy](https://github.com/structurizr/java/blob/master/docs/implied-relationships.md#createimpliedrelationshipsunlessanyrelationshipexistsstrategy) for more details). - ## model Each workspace must contain a `model` block, inside which elements and relationships are defined. @@ -154,8 +143,8 @@ The following tags are added by default: Permitted children: -- [!docs](#documentation) -- [!adrs](#architecture-decision-records-adrs) +- [!docs](#docs) +- [!adrs](#adrs) - [group](#group) - [container](#container) - [description](#description) @@ -182,8 +171,8 @@ The following tags are added by default: Permitted children: -- [!docs](#documentation) -- [!adrs](#architecture-decision-records-adrs) +- [!docs](#docs) +- [!adrs](#adrs) - [group](#group) - [component](#component) - [description](#description) @@ -211,8 +200,8 @@ The following tags are added by default: Permitted children: -- [!docs](#documentation) -- [!adrs](#architecture-decision-records-adrs) +- [!docs](#docs) +- [!adrs](#adrs) - [description](#description) - [technology](#technology) - [tags](#tags) @@ -1141,7 +1130,7 @@ users { } ``` -## Documentation +## !docs The `!docs` keyword can be used to attach Markdown/AsciiDoc documentation to the parent context (either the workspace, a software system, or a container). @@ -1149,21 +1138,9 @@ The `!docs` keyword can be used to attach Markdown/AsciiDoc documentation to the !docs [fully qualified class name] ``` -The path must be a relative path, located within the same directory as the parent file, or a subdirectory of it. For example: - -``` -!docs subdirectory -``` - -By default, the [com.structurizr.importer.documentation.DefaultDocumentationImporter](https://github.com/structurizr/documentation/blob/main/src/main/java/com/structurizr/importer/documentation/DefaultDocumentationImporter.java) class will be used to import documentation as follows: +See [Documentation](docs.html) for more details. -- All Markdown and AsciiDoc files in the given directory will be imported, alphabetically according to the filename. -- All images in the given directory (and sub-directories) are also imported into the workspace. -- See [Structurizr - Documentation - Headings and sections](https://structurizr.com/help/documentation/headings) for details about how section headings and numbering are handled. - -The above behaviour can be customised by specifying the fully qualified class name of your own implementation of [DocumentationImporter](https://github.com/structurizr/documentation/blob/main/src/main/java/com/structurizr/importer/documentation/DocumentationImporter.java), which needs to be on the DSL classpath or installed as a JAR file in the `plugins` directory next to your DSL file. - -## Architecture decision records (ADRs) +## !adrs The `!adrs` keyword can be used to attach Markdown/AsciiDoc ADRs to the parent context (either the workspace, a software system, or a container). @@ -1171,16 +1148,4 @@ The `!adrs` keyword can be used to attach Markdown/AsciiDoc ADRs to the parent c !adrs [fully qualified class name] ``` -The path must be a relative path, located within the same directory as the parent file, or a subdirectory of it. For example: - -``` -!adrs subdirectory -``` - -By default, the [com.structurizr.documentation.importer.AdrToolsDecisionImporter](https://github.com/structurizr/documentation/blob/main/src/main/java/com/structurizr/documentation/importer/AdrToolsDecisionImporter.java) class will be used to import ADRs as follows: - -- All Markdown files in this directory will be imported, alphabetically according to the filename. -- The files must have been created by [adr-tools](https://github.com/npryce/adr-tools), or at least follow the same format. -- All images in the given directory (and sub-directories) are also imported into the workspace. - -The above behaviour can be customised by specifying the fully qualified class name of your own implementation of [DocumentationImporter](https://github.com/structurizr/documentation/blob/main/src/main/java/com/structurizr/documentation/importer/DocumentationImporter.java), which needs to be on the DSL classpath or installed as a JAR file in the `plugins` directory next to your DSL file. +See [Architecture decision records](adrs.html) for more details. diff --git a/dsl/plugins.md b/dsl/plugins.md index 9ec8c58..1781a59 100644 --- a/dsl/plugins.md +++ b/dsl/plugins.md @@ -2,7 +2,8 @@ layout: default title: Plugins parent: Structurizr DSL -nav_order: 7 +nav_order: 11 +permalink: /dsl/plugins --- # Plugins diff --git a/dsl/scripts.md b/dsl/scripts.md index 7fe2a08..ab3cfe1 100644 --- a/dsl/scripts.md +++ b/dsl/scripts.md @@ -2,7 +2,8 @@ layout: default title: Scripts parent: Structurizr DSL -nav_order: 6 +nav_order: 10 +permalink: /dsl/scripts --- # Scripts diff --git a/dsl/workspace-extension.md b/dsl/workspace-extension.md new file mode 100644 index 0000000..7edf56c --- /dev/null +++ b/dsl/workspace-extension.md @@ -0,0 +1,11 @@ +--- +layout: default +title: Workspace extension +parent: Structurizr DSL +nav_order: 7 +permalink: /dsl/workspace-extension +--- + +# Workspace extension + +... \ No newline at end of file diff --git a/index.md b/index.md index bb7c114..4b5c413 100644 --- a/index.md +++ b/index.md @@ -6,33 +6,4 @@ description: Structurizr documentation permalink: / --- -This is a *bare-minimum* template to create a Jekyll site that uses the [Just the Docs] theme. You can easily set the created site to be published on [GitHub Pages] – the [README] file explains how to do that, along with other details. - -If [Jekyll] is installed on your computer, you can also build and preview the created site *locally*. This lets you test changes before committing them, and avoids waiting for GitHub Pages.[^1] And you will be able to deploy your local build to a different platform than GitHub Pages. - -More specifically, the created site: - -- uses a gem-based approach, i.e. uses a `Gemfile` and loads the `just-the-docs` gem -- uses the [GitHub Pages / Actions workflow] to build and publish the site on GitHub Pages - -Other than that, you're free to customize sites that you create with this template, however you like. You can easily change the versions of `just-the-docs` and Jekyll it uses, as well as adding further plugins. - -[Browse our documentation][Just the Docs] to learn more about how to use this theme. - -To get started with creating a site, simply: - -1. click "[use this template]" to create a GitHub repository -2. go to Settings > Pages > Build and deployment > Source, and select GitHub Actions - -If you want to maintain your docs in the `docs` directory of an existing project repo, see [Hosting your docs from an existing project repo](https://github.com/just-the-docs/just-the-docs-template/blob/main/README.md#hosting-your-docs-from-an-existing-project-repo) in the template README. - ----- - -[^1]: [It can take up to 10 minutes for changes to your site to publish after you push the changes to GitHub](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/creating-a-github-pages-site-with-jekyll#creating-your-site). - -[Just the Docs]: https://just-the-docs.github.io/just-the-docs/ -[GitHub Pages]: https://docs.github.com/en/pages -[README]: https://github.com/just-the-docs/just-the-docs-template/blob/main/README.md -[Jekyll]: https://jekyllrb.com -[GitHub Pages / Actions workflow]: https://github.blog/changelog/2022-07-27-github-pages-custom-github-actions-workflows-beta/ -[use this template]: https://github.com/just-the-docs/just-the-docs-template/generate +... \ No newline at end of file