|
| 1 | +--- |
| 2 | +title: diagrams.D2 |
| 3 | +description: Returns an SVGDiagram object created from the given D2 markup and options. |
| 4 | +categories: [] |
| 5 | +keywords: [] |
| 6 | +params: |
| 7 | + functions_and_methods: |
| 8 | + aliases: [] |
| 9 | + returnType: diagrams.SVGDiagram |
| 10 | + signatures: ['diagrams.D2 MARKUP [OPTIONS]'] |
| 11 | +--- |
| 12 | + |
| 13 | +{{< new-in v0.153.0 />}} |
| 14 | + |
| 15 | +Useful in a [code block render hook][], the `diagrams.D2` function returns an SVGDiagram object created from the given [D2][] markup and options. |
| 16 | + |
| 17 | +```go-html-template |
| 18 | +{{ $markup := `x -> y` }} |
| 19 | +{{ $options := dict "scale" 1.5 "padding" 10 }} |
| 20 | +{{ $d := diagrams.D2 $markup $options }} |
| 21 | +{{ $d.Wrapped }} |
| 22 | +``` |
| 23 | + |
| 24 | +## Methods |
| 25 | + |
| 26 | +Diagrams rendered by D2 consist of an `svg` element that is subsequently wrapped within another `svg` element. Conceptually, the inner `svg` element is the diagram, and the outer `svg` element is a container. |
| 27 | + |
| 28 | +The SVGDiagram object has the following methods: |
| 29 | + |
| 30 | +Wrapped |
| 31 | +: (`template.HTML`) Returns the inner `svg` element wrapped within an outer `svg` element, effectively reconstructing the original SVG diagram created by D2. |
| 32 | + |
| 33 | +Inner |
| 34 | +: (`template.HTML`) Returns the inner `svg` element. |
| 35 | + |
| 36 | +Width |
| 37 | +: (`int`) Returns the `width` attribute of the outer `svg` element, which may differ from the inner `svg` element's width if scaled during rendering. |
| 38 | + |
| 39 | +Height |
| 40 | +: (`int`) Returns the `height` attribute of the outer `svg` element, which may differ from the inner `svg` element's height if scaled during rendering. |
| 41 | + |
| 42 | +ViewBox |
| 43 | +: (`string`) Returns the `viewBox` attribute of the outer `svg` element. The `viewBox` coordinates are not affected by scaling. |
| 44 | + |
| 45 | +PreserveAspectRatio |
| 46 | +: (`string`) Returns the `preserveAspectRatio` attribute of the outer `svg` element. |
| 47 | + |
| 48 | +## Options |
| 49 | + |
| 50 | +The `diagrams.D2` function takes an options map with zero or more of the following options: |
| 51 | + |
| 52 | +{{% include "/_common/diagram-d2-options.md" %}} |
| 53 | + |
| 54 | +## Render hook |
| 55 | + |
| 56 | +Hugo natively supports D2 diagrams with an [embedded code block render hook][], allowing you to use fenced code blocks for D2 markup within your Markdown. |
| 57 | + |
| 58 | +The render hook accepts the options for the `diagrams.D2` function as described above, and those described below: |
| 59 | + |
| 60 | +class |
| 61 | +: (`string`) One or more CSS classes to append to the hardcoded `class` attribute of the outer `div` element. The hardcoded `class` attribute of the outer `div` element is `d2-svg-container`. |
| 62 | + |
| 63 | +file |
| 64 | +: (`string`) The path to a file containing D2 markup, typically with a `.d2` extension. If this value is non-empty, Hugo ignores any content between the opening and closing code fences. The render hook resolves the path by looking for a matching [page resource](g), falling back to a matching [global resource](g). It throws an error and fails the build if the file does not exist. |
| 65 | + |
| 66 | +id |
| 67 | +: (`string`) The `id` attribute of the outer `div` element. |
| 68 | + |
| 69 | +title |
| 70 | +: (`string`) The `title` attribute of the outer `div` element. |
| 71 | + |
| 72 | +## Examples |
| 73 | + |
| 74 | +To create a D2 diagram using the default options: |
| 75 | + |
| 76 | +````text |
| 77 | +```d2svg |
| 78 | +direction: right |
| 79 | +x -> y |
| 80 | +``` |
| 81 | +```` |
| 82 | + |
| 83 | +```d2svg |
| 84 | +direction: right |
| 85 | +x -> y |
| 86 | +``` |
| 87 | + |
| 88 | +To enlarge and render as a sketch, specify the options as comma-separated or space-separated key-value pairs wrapped within braces: |
| 89 | + |
| 90 | +````text |
| 91 | +```d2svg {scale=1.5, sketch=true} |
| 92 | +direction: right |
| 93 | +x -> y |
| 94 | +``` |
| 95 | +```` |
| 96 | + |
| 97 | +```d2svg {scale=1.5, sketch=true} |
| 98 | +direction: right |
| 99 | +x -> y |
| 100 | +``` |
| 101 | + |
| 102 | +To change the theme and add one or more CSS classes to the outer `div` element: |
| 103 | + |
| 104 | +````text |
| 105 | +```d2svg {scale=1.5, sketch=true, lightTheme="Everglade Green" class="foo bar"} |
| 106 | +direction: right |
| 107 | +x -> y: hello { |
| 108 | + style.animated: true |
| 109 | +} |
| 110 | +``` |
| 111 | +```` |
| 112 | + |
| 113 | +```d2svg {scale=1.5, sketch=true, lightTheme="Everglade Green" class="foo bar"} |
| 114 | +direction: right |
| 115 | +x -> y: hello { |
| 116 | + style.animated: true |
| 117 | +} |
| 118 | +``` |
| 119 | + |
| 120 | +## Caching |
| 121 | + |
| 122 | +Hugo employs caching to optimize diagram rendering, storing results in memory and on disk. The default disk cache location is `:cacheDir/:project`, defined in your site configuration: |
| 123 | + |
| 124 | +{{< code-toggle config=caches.misc />}} |
| 125 | + |
| 126 | +Alternatively, you can configure Hugo to cache diagrams within the project's `resources` directory as shown below: |
| 127 | + |
| 128 | +{{< code-toggle file=hugo >}} |
| 129 | +[caches.misc] |
| 130 | +dir = ':resourceDir' |
| 131 | +maxAge = -1 |
| 132 | +{{< /code-toggle >}} |
| 133 | + |
| 134 | +Learn more about [file cache configuration]. |
| 135 | + |
| 136 | +## Configuration |
| 137 | + |
| 138 | +To achieve a consistent look and feel for all diagrams on your site, define default settings within your site's configuration file. |
| 139 | + |
| 140 | +See [configure diagrams](/configuration/markup/#diagrams). |
| 141 | + |
| 142 | +## Themes |
| 143 | + |
| 144 | +D2 themes customize visual elements like colors, fill patterns, and border radii. Two [theme catalogs][] exist: one for light and one for dark modes. When your system is in dark mode, the configured dark theme is applied. |
| 145 | + |
| 146 | +By default, Hugo uses: |
| 147 | + |
| 148 | +- Light theme: Neutral Default |
| 149 | +- Dark theme: Dark Flagship Terrastruct |
| 150 | + |
| 151 | +You can override these defaults by specifying a light and dark theme in your site configuration, within the options map passed to the `d2.Diagram` function, or in fenced D2 code blocks. |
| 152 | + |
| 153 | +### Light themes |
| 154 | + |
| 155 | +{{< list-d2-themes catalog=light >}} |
| 156 | + |
| 157 | +### Dark themes |
| 158 | + |
| 159 | +{{< list-d2-themes catalog=dark >}} |
| 160 | + |
| 161 | +## Miscellaneous |
| 162 | + |
| 163 | +### Responsive diagrams |
| 164 | + |
| 165 | +Create a CSS ruleset to make your D2 diagrams responsive: |
| 166 | + |
| 167 | +```css |
| 168 | +.d2-svg-container > svg { |
| 169 | + max-width: 100%; |
| 170 | + height: auto; |
| 171 | +} |
| 172 | +``` |
| 173 | + |
| 174 | +### Visual Studio Code |
| 175 | + |
| 176 | +Install the [D2 extension][] to help you create D2 diagrams when using Visual Studio Code. |
| 177 | + |
| 178 | +[code block render hook]: /render-hooks/code-blocks/ |
| 179 | +[D2]: https://d2lang.com/ |
| 180 | +[D2 extension]: https://marketplace.visualstudio.com/items?itemName=terrastruct.d2 |
| 181 | +[embedded code block render hook]: <{{% eturl render-codeblock-d2 %}}> |
| 182 | +[file cache configuration]: /configuration/caches/ |
| 183 | +[theme catalogs]: https://d2lang.com/tour/themes/ |
0 commit comments