.

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

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 <true|false>
+```
+
+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)

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)

dsl/cookbook/workspace/example-1.dsl

@@ -0,0 +1,9 @@
+workspace "Name" "Description" {
+
+    model {
+    }
+
+    views {
+    }
+
+}

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)

dsl/defaults.md

@@ -2,7 +2,8 @@
 layout: default
 title: Defaults
 parent: Structurizr DSL
-nav_order: 2
+nav_order: 3
+permalink: /dsl/defaults
 ---
 
 # Defaults

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 <path> [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.
+

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)

dsl/expressions.md

@@ -2,24 +2,30 @@
 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
 
 - `-><identifier|expression>`: the specified element(s) plus afferent couplings
 - `<identifier|expression>->`: the specified element(s) plus efferent couplings
 - `-><identifier|expression>->`: the specified element(s) plus afferent and efferent couplings
-- `element.type==<type>`: elements of the specified type (Person, SoftwareSystem, Container, Component, DeploymentNode, InfrastructureNode, SoftwareSystemInstance, ContainerInstance, Custom)
+- `element.type==<type>`: elements of the specified type (`Person`, `SoftwareSystem`, `Container`, `Component`, `DeploymentNode`, `InfrastructureNode`, `SoftwareSystemInstance`, `ContainerInstance`, `Custom`)
 - `element.parent==<identifier>`: elements with the specified parent
 - `element.tag==<tag>[,tag]`: all elements that have all of the specified tags
 - `element.tag!=<tag>[,tag]`: all elements that do not have all of the specified tags
 - `element==-><identifier>`: the specified element plus afferent couplings
 - `element==<identifier>->`: the specified element plus efferent couplings
 - `element==-><identifier>->`: the specified element plus afferent and efferent couplings
 
+## Relationship expressions
+
 - `*->*`: all relationships
 - `<identifier>->*`: all relationships with the specified source element
 - `*-><identifier>`: 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==<identifier>->*`: all relationships with the specified source element
 - `relationship==*-><identifier>`: all relationships with the specified destination element
 - `relationship==<identifier>-><identifier>`: all relationships between the two specified elements
-
-Element and relationship expressions are not supported on dynamic views.

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 {

dsl/includes.md

@@ -2,7 +2,8 @@
 layout: default
 title: Includes
 parent: Structurizr DSL
-nav_order: 4
+nav_order: 6
+permalink: /dsl/includes
 ---
 
 # Includes

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,