Home

Awesome

D2 Extension For Quarto

This Quarto extension allows you to render D2 diagrams directly within your markdown documents.

Main features:

This extension was inspired by ram02z/d2-filter.

Installation

Prerequisites

Ensure that you have D2 installed on your system.

Install

Run the following command to add this extension to your current project:

quarto add data-intuitive/quarto-d2

This will install the extension under the _extensions subdirectory. If you’re using version control, you will want to check in this directory.

Examples

D2 can be used for simple diagrams.

And for more complex diagrams.

<div> 
logs: {
  shape: page
  style.multiple: true
}
user: User {shape: person}
network: Network {
  tower: Cell Tower {
    satellites: {
      shape: stored_data
      style.multiple: true
    }

    satellites -> transmitter
    satellites -> transmitter
    satellites -> transmitter
    transmitter
  }
  processor: Data Processor {
    storage: Storage {
      shape: cylinder
      style.multiple: true
    }
  }
  portal: Online Portal {
    UI
  }

  tower.transmitter -> processor: phone logs
}
server: API Server

user -> network.tower: Make call
network.processor -> server
network.processor -> server
network.processor -> server

server -> logs
server -> logs
server -> logs: persist

server -> network.portal.UI: display
user -> network.portal.UI: access {
  style.stroke-dash: 3
}
<img src="images/diagram-2.svg" style="width:50.0%" /> </div>

The enclosing curly brakets are optional if you are only using document level options. Quarto block-level options, e.g. #|, are not currently supported.

Attributes

You can specify additional attributes to control the appearance and layout of the diagram and document:

You can also replace the contents of the block with an external D2 file by using the file parameter. file must be an existing file ending in a “d2” or “txt” file extension. Other parameters related to rendering and embedding diagrams include:

Note that for Typst format output the width and height can’t be supplied as a percent value.

Here’s an example that uses multiple attributes:

```{.d2 theme="CoolClassics" layout="elk" pad=20 caption="This is a caption" width="50%"}
x -> y -> z
```

Global Options

You can set global options for the d2 filter using the d2 field in the document metadata. Here’s an example:

---
title: "D2 Example"
filters:
  - d2
d2:
  layout: elk
  theme: "GrapeSoda"
---

```{.d2 width="40%" echo=true}
x -> y -> z
```

Setting an input file

You can specify an input d2 file. If echo=true, the contents of the file block is replaced by the contents of the file.

```{.d2 file="./diagram.d2"}
```

Setting output folder and file name

You can specify a folder where the generated diagram will be saved using the folder attribute. The filename attribute allows you to set a custom name for the output file.

```{.d2 folder="./images" filename="my_diagram"}
x -> y -> z
```

[!NOTE]

If the folder attribute is not provided and the output format is HTML, the image will be embedded inline in the document.

Interactive diagrams

Interactive diagrams will only work when the Quarto output format is HTML, the figure format is "svg", and the embed mode is "raw". Example:

---
title: "D2 Example"
format: html
filters:
  - d2
d2:
  format: svg
  embed_mode: raw
---

```{.d2 width="40%"}
x { 
  link: "https://quarto.org"
}
y {
  tooltip: "This is a tooltip"
}
x -> y -> z
```