Initial commit of DSL docs.

README.md

@@ -1 +1 @@
-Source for the website published at https://structurizr.github.io
+Source for the website published at https://docs.structurizr.com

dsl/general-rules.md → dsl/basics.md

@@ -1,10 +1,13 @@
 ---
 layout: default
-title: General rules
+title: Basics
 parent: Structurizr DSL
+nav_order: 1
 ---
 
-# General rules
+# Basics
+
+## DSL rules
 
 - Line breaks are important; long lines can be split with `\` as the last character on the line.
 - Lines are processed in order.
@@ -17,6 +20,8 @@ parent: Structurizr DSL
 - Use `""` as a placeholder for an earlier optional property that you'd like to skip.
 - Tags are comma separated (e.g. `Tag 1,Tag 2,Tag 3`) - see [Structurizr - Notation](https://structurizr.com/help/notation) for details of how tags and styling works.
 
+## Workspace rules
+
 In addition, workspaces are subject to the following rules:
 
 - Each view must have a unique "key" (this is generated for you if not specified; __automatically generated view keys are not guaranteed to be stable over time, and you will likely lose [manual layout information](https://structurizr.com/help/manual-layout) when using them in conjunction with Structurizr Lite/on-premises/cloud__). 
@@ -27,3 +32,57 @@ 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.
 
+## Constants
+
+The `!constant` keyword can be used to define a constant, which can be used with [string substitution](#string-substitution)
+
+```
+!constant <name> <value>
+```
+
+Constant names may only contain the following characters: `a-zA-Z0-9-_.` 
+
+## String substitution
+
+String substitution will take place on any text specified within a token using the `${NAME}` syntax, where `NAME` corresponds to a [constant](#constants) or an environment variable.
+For example:
+
+```
+!constant ORGANISATION_NAME "Organisation"
+!constant GROUP_NAME "Group"
+
+workspace {
+
+    model {
+        group "${ORGANISATION_NAME} - ${GROUP_NAME}" {
+            user = person "User"
+        }
+    }
+
+}
+```
+
+If a named constant or environment variable cannot be found, the string will not be substituted.
+Names may only contain the following characters: `a-zA-Z0-9-_.`
+
+## Comments
+
+Comments can be defined as follows:
+
+```
+/*
+    multi-line comment
+*/
+```
+
+```
+/* single-line comment */
+```
+
+```
+# single line comment
+```
+
+```
+// single line comment
+```

dsl/defaults.md

@@ -0,0 +1,39 @@
+---
+layout: default
+title: Defaults
+parent: Structurizr DSL
+nav_order: 2
+---
+
+# Defaults
+
+The DSL is designed to be as compact as possible.
+When used in conjunction with [Structurizr Lite](https://structurizr.com/help/lite)
+or the [Structurizr CLI](https://github.com/structurizr/cli),
+the following DSL fragment will automatically:
+
+- Create the [implied relationship](docs/cookbook/implied-relationships)
+between the ```user``` and ```softwareSystem``` elements.
+- Create a default set of views (1 x System Landscape, 1 x System Context, 1 x Container - all with auto-layout enabled, see [ViewSet.createDefaultViews()](https://github.com/structurizr/java/blob/master/structurizr-core/src/com/structurizr/view/ViewSet.java)).
+- Add some default element styles from a theme.
+
+```
+workspace {
+
+    model {
+        user = person "User"
+        softwareSystem = softwareSystem "Software System" {
+            webapp = container "Web Application"
+            database = container "Database"
+         }
+
+        user -> webapp "Uses"
+        webapp -> database "Reads from and writes to"
+    }
+    
+    views {
+    	theme default
+    }
+
+}
+```

dsl/expressions.md

@@ -0,0 +1,36 @@
+---
+layout: default
+title: Expressions
+parent: Structurizr DSL
+nav_order: 5
+---
+
+# Expressions
+
+The Structurizr DSL supports a number of expressions for use when including or excluding elements/relationships on views.
+
+- `-><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.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
+
+- `*->*`: all relationships
+- `<identifier>->*`: all relationships with the specified source element
+- `*-><identifier>`: all relationships with the specified destination element
+- `relationship==*`: all relationships
+- `relationship==*->*`: all relationships
+- `relationship.tag==<tag>[,tag]`: all relationships that have all of the specified tags
+- `relationship.tag!=<tag>[,tag]`: all relationships that do not have all of the specified tags
+- `relationship.source==<identifier>`: all relationships with the specified source element
+- `relationship.destination==<identifier>`: all relationships with the specified destination element
+- `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.