vars docs

docs/tour/vars.md

@@ -0,0 +1,143 @@
+# Variables & Substitutions
+
+`vars` is a special keyword that lets you define variables. These variables can be
+referenced with the substitution syntax: `${}`.
+
+```d2
+vars: {
+  server-name: Cat
+}
+
+server1: ${server-name}-1
+server2: ${server-name}-2
+
+server1 <-> server2
+```
+
+<div style={{width: 400}} className="embedSVG" dangerouslySetInnerHTML={{__html: require('@site/static/img/generated/vars-intro.svg2')}}></div>
+
+## Variables can be nested
+
+Use `.` to refer to nested variables.
+
+```d2
+vars: {
+  primaryColors: {
+    button: {
+      active: "#4baae5"
+      border: black
+    }
+  }
+}
+
+button: {
+  width: 100
+  height: 40
+  style: {
+    border-radius: 5
+    fill: ${primaryColors.button.active}
+    stroke: ${primaryColors.button.border}
+  }
+}
+```
+
+<div style={{width: 200}} className="embedSVG" dangerouslySetInnerHTML={{__html: require('@site/static/img/generated/vars-nested.svg2')}}></div>
+
+## Variables are scoped
+
+They work just like variable scopes in programming. Substitutions can refer to variables
+defined in a more outer scope, but not a more inner scope. If a variable appears in two
+scopes, the one closer to the substitution is used.
+
+```d2
+vars: {
+  region: Global
+  font: mono
+}
+
+lb: ${region} load balancer
+lb.style.font: ${font}
+
+zone1: {
+  vars: {
+    region: us-east-1
+  }
+  server: ${region} API
+  server.style.font: ${font}
+}
+```
+
+<div style={{width: 600}} className="embedSVG" dangerouslySetInnerHTML={{__html: require('@site/static/img/generated/vars-scoped.svg2')}}></div>
+
+## Single quotes bypass substitutions
+
+```d2
+vars: {
+  names: John and Joyce
+}
+a -> b: 'Send field ${names}'
+```
+
+<div className="embedSVG" dangerouslySetInnerHTML={{__html: require('@site/static/img/generated/vars-escaped.svg2')}}></div>
+
+## Spread substitutions
+
+If `x` is a map or an array, `...${x}` will spread the contents of `x` into either a map
+or an array.
+
+```d2
+vars: {
+  base-constraints: [NOT NULL; UNQ]
+  disclaimer: DISCLAIMER {
+    I am not a lawyer
+    near: top-center
+  }
+}
+
+data: {
+  shape: sql_table
+  a: int {constraint: [PK; ...${base-constraints}]}
+}
+
+custom-disclaimer: DRAFT DISCLAIMER {
+  ...${disclaimer}
+}
+```
+
+<div style={{width: 400}} className="embedSVG" dangerouslySetInnerHTML={{__html: require('@site/static/img/generated/vars-spread.svg2')}}></div>
+
+## Configuration variables
+
+Some configurations can be made directly in `vars` instead of using flags or environment
+variables.
+
+```d2
+vars: {
+  d2-config: {
+    theme-id: 4
+    dark-theme-id: 200
+    pad: 0
+    center: true
+    sketch: true
+    layout-engine: elk
+  }
+}
+
+direction: right
+x -> y
+```
+
+This is equivalent to calling the following with no `vars`:
+```shell
+d2 --layout=elk --theme=4 --dark-theme=200 --pad=0 --sketch --center input.d2
+```
+
+<div style={{width: 400}} className="embedSVG" dangerouslySetInnerHTML={{__html: require('@site/static/img/generated/vars-config.svg2')}}></div>
+
+:::info Precedence
+Flags and environment variables take precedence.
+
+In other words, if you call `D2_PAD=2 d2 --theme=1 input.d2`, it doesn't matter what
+`theme-id` and `pad` are set to in `input.d2`'s `d2-config`; it will use the options from
+the command.
+:::

sidebars.js

@@ -24,7 +24,6 @@ const sidebars = {
         "tour/containers",
       ],
     },
-
     {
       type: "category",
       label: "Special Objects",
@@ -71,7 +70,13 @@ const sidebars = {
       type: "category",
       label: "In Depth",
       link: { type: "doc", id: "tour/strings" },
-      items: ["tour/strings", "tour/comments", "tour/overrides", "tour/auto-formatter"],
+      items: [
+        "tour/strings",
+        "tour/vars",
+        "tour/comments",
+        "tour/overrides",
+        "tour/auto-formatter",
+      ],
     },
     {
       type: "category",

static/d2/vars-config.d2

@@ -0,0 +1,13 @@
+vars: {
+  d2-config: {
+    theme-id: 4
+    dark-theme-id: 200
+    pad: 0
+    center: true
+    sketch: true
+    layout-engine: elk
+  }
+}
+
+direction: right
+x -> y

static/d2/vars-escaped.d2

@@ -0,0 +1,5 @@
+direction: right
+vars: {
+  names: John and Joyce
+}
+a -> b: 'Send field ${names}'

static/d2/vars-intro.d2

@@ -0,0 +1,9 @@
+direction: right
+vars: {
+  server-name: Cat
+}
+
+server1: ${server-name}-1
+server2: ${server-name}-2
+
+server1 <-> server2

static/d2/vars-nested.d2

@@ -0,0 +1,18 @@
+vars: {
+  primaryColors: {
+    button: {
+      active: "#4baae5"
+      border: black
+    }
+  }
+}
+
+button: {
+  width: 100
+  height: 40
+  style: {
+    border-radius: 5
+    fill: ${primaryColors.button.active}
+    stroke: ${primaryColors.button.border}
+  }
+}

static/d2/vars-scoped.d2

@@ -0,0 +1,12 @@
+vars: {
+  region: Global
+}
+
+lb: ${region} load balancer
+
+zone1: {
+  vars: {
+    region: us-east-1
+  }
+  server: ${region} API
+}

static/d2/vars-spread.d2

@@ -0,0 +1,16 @@
+vars: {
+  base-constraints: [NOT NULL; UNQ]
+  disclaimer: DISCLAIMER {
+    I am not a lawyer
+    near: top-center
+  }
+}
+
+data: {
+  shape: sql_table
+  a: int {constraint: [PK; ...${base-constraints}]}
+}
+
+custom-disclaimer: DRAFT DISCLAIMER {
+  ...${disclaimer}
+}