mkdocs-d2-plugin 0.2.2

MkDocs plugin for D2

mkdocs-d2-plugin

A plugin for the MkDocs documentation site generator which automatically generates and embeds D2 diagrams.

Requirements

• MkDocs >= 1.4.0
• Pydantic
• D2

Installation

Install the plugin using pip:

pip install mkdocs-d2-plugin

And add it to your mkdocs.yml:

plugins:
  - d2

Usage

The plugin will automatically generate and embed D2 diagrams from code blocks with the d2 language tag.

```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!
```

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.

```d2 sketch=true force_appendix=True
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!
```

List of available themes

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

<rant>

Why this fenced code block format?

```d2 key=value
[...]
```

MkDocs uses python-markdown library, which expects key-value pairs in a following format:

```{ .d2 key="value" }
[...]
```

This breaks syntax highlighting in most editors. The format used by this plugin breaks python-markdown library instead, however the entire code block is replaced anyway, so it doesn't matter. And according to CommonMark specification it is a valid Markdown.

</rant>