Merge pull request #264 from terrastruct/legend

document 0.7.0 features

Author: alixander

docs/tour/globs.md

@@ -11,6 +11,7 @@ import GlobsRecursive2 from '@site/static/d2/globs-recursive-2.d2';
 import GlobsFilter from '@site/static/d2/globs-filter.d2';
 import GlobsFilter2 from '@site/static/d2/globs-filter-2.d2';
 import GlobsFilter3 from '@site/static/d2/globs-filter-3.d2';
+import GlobsFilterEndpoints from '@site/static/d2/globs-filter-endpoints.d2';
 import GlobsFilterGlobValue from '@site/static/d2/globs-filter-glob-value.d2';
 import GlobsInverseFilter from '@site/static/d2/globs-inverse-filter.d2';
 import GlobsNested from '@site/static/d2/globs-nested.d2';
@@ -164,6 +165,24 @@ means the key must be specified.
 
 <div style={{width: 600}} className="embedSVG" dangerouslySetInnerHTML={{__html: require('@site/static/img/generated/globs-filter-glob-value.svg2')}}></div>
 
+
+### Connection endpoint filters
+
+Connections can be filtered by properties on their source and destination shapes.
+
+<CodeBlock className="language-d2">
+    {GlobsFilterEndpoints}
+</CodeBlock>
+
+<div style={{width: 600}} className="embedSVG" dangerouslySetInnerHTML={{__html: require('@site/static/img/generated/globs-filter-endpoints.svg2')}}></div>
+
+Endpoint filters also work with IDs, e.g. `&src: b`.
+
+:::info
+Endpoint IDs are absolute. For example, `a.c` instead of just `c`, even if the glob is
+declared within `a`.
+:::
+
 ## Inverse filters
 
 Use `!&` to inverse-filter what globs target.

docs/tour/icons.md

@@ -23,10 +23,6 @@ You can use any URL as value.
 
 <div style={{width: "200px", margin: "0 auto 20px auto"}} className="embedSVG" dangerouslySetInnerHTML={{__html: require('@site/static/img/generated/icons-1.svg2')}}></div>
 
-:::info
-Icons on connections coming soon.
-:::
-
 :::info
 Using the D2 CLI locally? You can specify local images like `icon: ./my_cat.png`.
 :::

docs/tour/legend.md

@@ -0,0 +1,25 @@
+import CodeBlock from '@theme/CodeBlock';
+import Legend from '@site/static/d2/legend.d2';
+import LegendHidden from '@site/static/d2/legend-hidden.d2';
+
+# Legend
+
+Use a special variable, `d2-legend`, to declare a legend.
+
+<CodeBlock className="language-d2">
+    {Legend}
+</CodeBlock>
+
+<div style={{width: "100%"}} className="embedSVG" dangerouslySetInnerHTML={{__html: require('@site/static/img/generated/legend.svg2')}}></div>
+
+## Hiding shapes
+
+Since `a -> b` declares 3 things (1 connection and 2 shapes), 3 things will show up on the
+legend. If you only intended to show the connection in the legend, you can set the opacity
+of shapes to exclude them from the legend.
+
+<CodeBlock className="language-d2">
+    {LegendHidden}
+</CodeBlock>
+
+<div style={{width: "100%"}} className="embedSVG" dangerouslySetInnerHTML={{__html: require('@site/static/img/generated/legend-hidden.svg2')}}></div>

docs/tour/man.md

@@ -14,9 +14,12 @@ NAME
      d2 – compiles and renders d2 diagrams into svgs.
 
 SYNOPSIS
-     d2 [--watch false] [--theme 0] file.d2 [file.svg | file.png]
+     d2 [--watch false] [--theme 0] [--salt string] file.d2
+	[file.svg | file.png]
      d2 layout [name]
      d2 fmt file.d2 ...
+     d2 play file.d2
+     d2 validate file.d2
 
 DESCRIPTION
      d2 compiles and renders file.d2 to file.svg | file.png.
@@ -88,7 +91,7 @@ OPTIONS
      --animate-interval 0
 		 If given, multiple boards are packaged as 1 SVG which
 		 transitions through each board at the interval (in
-		 milliseconds). Can only be used with SVG exports.
+		 milliseconds). Can only be used with SVG and GIF exports.
 
      --browser true
 		 Browser executable that watch opens. Setting to 0 opens no
@@ -125,11 +128,30 @@ OPTIONS
 		 out and exiting. When rendering a large diagram, it is
 		 recommended to increase this value.
 
+     --check false
+		 Check that the specified files are formatted correctly.
+
+     --salt string
+		 Add a salt value to ensure the output uses unique IDs. This
+		 is useful when generating multiple identical diagrams to be
+		 included in the same HTML doc, so that duplicate id's do not
+		 cause invalid HTML. The salt value is a string that will be
+		 appended to IDs in the output..
+
      -h, --help  Print usage information and exit.
 
      -v, --version
 		 Print version information and exit.
 
+     --stdout-format string
+		 Set the output format when writing to stdout. Supported
+		 formats are: png, svg. Only used when output is set to stdout
+		 (-).
+
+     --no-xml-tag false
+		 Omit XML tag (<?xml ...?>) from output SVG files. Useful when
+		 generating SVGs for direct HTML embedding.
+
 SUBCOMMANDS
      layout	 Lists available layout engine options with short help.
 
@@ -140,11 +162,88 @@ SUBCOMMANDS
      themes	 Lists available themes.
 
      fmt file.d2 ...
-		 Format all passed files.
+		 Format all passed files
+
+     play file.d2
+		 Opens the file in playground, an online web viewer
+		 (https://play.d2lang.com)
+
+     validate file.d2
+		 Validates file.d2
+
+ENVIRONMENT VARIABLES
+     Many flags can also be set with environment variables.
+
+     D2_WATCH
+	     See -w[atch] flag.
+
+     D2_LAYOUT
+	     See -l[ayout] flag.
+
+     D2_THEME
+	     See -t[heme] flag.
+
+     D2_DARK_THEME
+	     See --dark-theme flag.
+
+     D2_PAD  See --pad flag.
+
+     D2_CENTER
+	     See --center flag.
+
+     D2_SKETCH
+	     See -s[ketch] flag.
+
+     D2_BUNDLE
+	     See -b[undle] flag.
+
+     D2_FORCE_APPENDIX
+	     See --force-appendix flag.
+
+     D2_FONT_REGULAR
+	     See --font-regular flag.
+
+     D2_FONT_ITALIC
+	     See --font-italic flag.
+
+     D2_FONT_BOLD
+	     See --font-bold flag.
+
+     D2_FONT_SEMIBOLD
+	     See --font-semibold flag.
+
+     D2_ANIMATE_INTERVAL
+	     See --animate-interval flag.
+
+     D2_TIMEOUT
+	     See --timeout flag.
+
+     D2_CHECK
+	     See --check flag.
+
+     DEBUG   See -d[ebug] flag.
+
+     IMG_CACHE
+	     See --img-cache flag.
+
+     HOST    See -h[ost] flag.
+
+     PORT    See -p[ort] flag.
+
+     BROWSER
+	     See --browser flag.
+
+     D2_STDOUT_FORMAT
+	     See --stdout-format flag.
+
+     D2_NO_XML_TAG
+	     See --no-xml-tag flag.
 
 SEE ALSO
      d2plugin-tala(1)
 
 AUTHORS
      Terrastruct Inc.
+
+macOS 14.1			March 12, 2025			    macOS 14.1
 ```

docs/tour/models.md

@@ -0,0 +1,70 @@
+import CodeBlock from '@theme/CodeBlock';
+import Suspend from '@site/static/d2/suspend.d2';
+import Suspend2 from '@site/static/d2/suspend-2.d2';
+import Suspend3 from '@site/static/d2/suspend-3.d2';
+import Suspend4 from '@site/static/d2/suspend-4.d2';
+
+# Models
+
+Let's say you want to define all models and relationships between models once, then
+display them in different ways.
+
+First, let's define the models and relationships.
+
+<CodeBlock className="language-d2-incomplete">
+    {Suspend}
+</CodeBlock>
+
+<div className="embedSVG" dangerouslySetInnerHTML={{__html: require('@site/static/img/generated/suspend.svg2')}}></div>
+
+We will use this as the example for multiple views of the same model. How do we treat
+these as models and not just ordinary shapes and connections? We use the following
+keywords:
+
+1. `suspend`: This marks the shape or connection for deletion
+2. `unsuspend`: This restores the shape or connection
+
+Since models are meant to be invisible until used, we define models at the top of our
+diagram and `suspend` all of them with the following globs.
+
+```d2
+**: suspend
+(** -> **)[*]: suspend
+```
+
+We then use globs to selectively `unsuspend` the models we want to show. Let's take a look
+at some use cases.
+
+:::info
+If you haven't yet, please familiarize yourself with [globs](globs.md).
+:::
+
+## Show only top-level
+
+<CodeBlock className="language-d2-incomplete">
+    {Suspend2}
+</CodeBlock>
+
+<div className="embedSVG" dangerouslySetInnerHTML={{__html: require('@site/static/img/generated/suspend-2.svg2')}}></div>
+
+## Show only connection to X
+
+<CodeBlock className="language-d2-incomplete">
+    {Suspend3}
+</CodeBlock>
+
+<div className="embedSVG" dangerouslySetInnerHTML={{__html: require('@site/static/img/generated/suspend-3.svg2')}}></div>
+
+## Show only likes
+
+<CodeBlock className="language-d2-incomplete">
+    {Suspend4}
+</CodeBlock>
+
+<div className="embedSVG" dangerouslySetInnerHTML={{__html: require('@site/static/img/generated/suspend-4.svg2')}}></div>
+
+## Utilizing imports
+
+As you may have noticed, each of these examples repeated the initial models. You can
+further apply the "one model" principle by defining models once in their own file and
+importing them. See the [import model-view pattern](model-view) for more.

docs/tour/text.md

@@ -4,6 +4,7 @@ pagination_next: tour/icons
 ---
 import CodeBlock from '@theme/CodeBlock';
 import Markdown from '@site/static/d2/markdown.d2';
+import MarkdownLabel from '@site/static/d2/markdown-label.d2';
 import Text2 from '@site/static/d2/text-2.d2';
 import Code2 from '@site/static/d2/code-2.d2';
 import NonMarkdownText from '@site/static/d2/non-markdown-text.d2';
@@ -19,6 +20,16 @@ import Latex from '@site/static/d2/latex.d2';
 
 <div style={{width: 300, margin: "0 auto"}} className="embedSVG" dangerouslySetInnerHTML={{__html: require('@site/static/img/generated/markdown.svg2')}}></div>
 
+## Markdown label
+
+If you want to set a Markdown label on a shape, you must explicitly declare the shape.
+
+<CodeBlock className="language-d2">
+    {MarkdownLabel}
+</CodeBlock>
+
+<div style={{width: 300, margin: "0 auto"}} className="embedSVG" dangerouslySetInnerHTML={{__html: require('@site/static/img/generated/markdown-label.svg2')}}></div>
+
 ## Most languages are supported
 
 D2 most likely supports any language you want to use, including non-Latin ones like
@@ -57,11 +68,6 @@ does not have linebreaks. You can kind of get around this with the `displaylines
 See below.
 :::
 
-:::note
-Currently cannot be applied to labels, which is why the above example nests an object.
-This is coming soon.
-:::
-
 ## Code
 
 Change `md` to a programming language for code blocks

sidebars.js

@@ -76,6 +76,8 @@ const sidebars = {
         "tour/globs",
         "tour/comments",
         "tour/overrides",
+        "tour/models",
+        "tour/legend",
         "tour/auto-formatter",
       ],
     },

static/d2/globs-filter-endpoints.d2

@@ -0,0 +1,35 @@
+a: {
+  shape: circle
+  style: {
+    fill: blue
+    opacity: 0.8
+  }
+}
+b: {
+  shape: rectangle
+  style: {
+    fill: red
+    opacity: 0.5
+  }
+}
+c: {
+  shape: diamond
+  style.fill: green
+  style.opacity: 0.8
+}
+(* -> *)[*]: {
+  &src.style.fill: blue
+  style.stroke-dash: 3
+}
+(* -> *)[*]: {
+  &dst.style.opacity: 0.8
+  style.stroke: cyan
+}
+(* -> *)[*]: {
+  &src.shape: rectangle
+  &dst.style.fill: green
+  style.stroke-width: 5
+}
+a -> b
+b -> c
+a -> c

static/d2/icons-1.d2

@@ -1,3 +1,11 @@
-my network: {
-  icon: https://icons.terrastruct.com/infra/019-network.svg
+deploy: {
+  icon: https://icons.terrastruct.com/aws%2FDeveloper%20Tools%2FAWS-CodeDeploy.svg
+}
+
+backup: {
+  icon: https://icons.terrastruct.com/aws%2FStorage%2FAWS-Backup.svg
+}
+
+deploy -> backup: {
+  icon: https://icons.terrastruct.com/infra%2F002-backup.svg
 }

static/d2/legend-hidden.d2

@@ -0,0 +1,18 @@
+vars: {
+  d2-legend: {
+    a <-> b: Good relationship {
+      style.stroke: red
+      style.stroke-dash: 2
+    }
+    a.style.opacity: 0
+    b.style.opacity: 0
+  }
+}
+
+api-1 <-> api-2: {
+  style.stroke: red
+  style.stroke-dash: 2
+}
+api-1 -> api-3: {
+  target-arrowhead.shape: circle
+}