MkDocs plugin for D2
Project description
mkdocs-d2-plugin
A plugin for the MkDocs documentation site generator which automatically generates and embeds D2 diagrams.
Requirements
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!
```
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>
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.2.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0139b0cc066fe23ccf3e6cc4f1a1b2a75efb3be398f221f4250e6da715dcdb22 |
|
MD5 | 8e67e48b6cfed0683a61c4adca02dfeb |
|
BLAKE2b-256 | aa1a92dfad3d52c6a016f404da3a7ce22b9cc6a3741e023b59710ed8fe9cfc5c |