mkdocs-d2-plugin 0.4.1

MkDocs plugin for D2

mkdocs-d2-plugin

A plugin for embedding D2 diagrams in MkDocs.

Requirements

• MkDocs >= 1.4.0
• D2

Installation

Install the plugin using pip:

pip install mkdocs-d2-plugin

And add it to your mkdocs.yml:

plugins:
  - d2

Usage

There are two ways to use the plugin:

• fenced code block
• image tag

The end result is exactly the same, so which one you choose is a matter of personal preference.

Fenced code block

```d2
shape: sequence_diagram
Alice -> John: Hello John, how are you?
Alice -> John.ack: John, can you hear me?
John.ack -> Alice: Hi Alice, I can hear you!
John -> Alice: I feel great!
```

Image tag

![Diagram](diagram.d2)

Only files with .d2 extension are processed.

Configuration

The plugin can be configured in your mkdocs.yml file.

plugins:
  - d2:
      executable: d2
      layout: dagre
      theme: 0
      dark_theme: False
      sketch: False
      pad: 100
      scale: -1.0
      force_appendix: False

Run d2 --help for more information about the options.

Everything (except executable path) can be overriden locally.

Fenced code block

```d2 sketch="True" pad="30"
shape: sequence_diagram
Alice -> John: Hello John, how are you?
Alice -> John.ack: John, can you hear me?
John.ack -> Alice: Hi Alice, I can hear you!
John -> Alice: I feel great!
```

Quotes around values are mandatory.

There is one special option, available only in fenced code blocks:

```d2 render="False"
Bob -> Alice
```

This option disables rendering of the diagram, but still allows you to use d2 language tag to highlight the code.

Image tag

![Diagram](diagram.d2){sketch="True" pad="30")

Contrary to fenced code blocks, quotes around values are optional. However white space before opening brace is not allowed. Blame attr_list.

Example

You can find example app in the example directory. Live version is available here.

To run in locally:

cd example
python3 -m venv .venv
source .venv/bin/activate
pip install mkdocs-material mkdocs-d2-plugin
mkdocs serve

To run it using Docker:

cd example
docker build --tag mkdocs-d2-plugin:latest .
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs mkdocs-d2-plugin:latest

Known issues I plan to fix

• Layered diagrams (animations) are not supported. D2 does not allow outputing such diagrams to stdout.
• Image tags require paths relative to base docs directory.