MkDocs plugin for D2
Project description
mkdocs-d2-plugin
A plugin for embedding D2 diagrams in MkDocs.
Requirements
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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for mkdocs_d2_plugin-0.4.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 1af1202590cf04e5106d13faecb179e83fc7ed6e54872d5b0f93b76aa8ea4aed |
|
MD5 | 3e73a075cfab2528fa3ecfd34ff1d9b6 |
|
BLAKE2b-256 | 621e4a14140d1c10bab331c713f7f2fcc3f1b3eb7550784a5e46869c1a195786 |