Handle .d2 files

[Karreg]

Hello,

I'm currently (and freshly) evaluating d2 as a replacement for drawio in our mkdocs documentations, as drawio is a bit overkill, and d2 looks promising, especially since I prefer the -as-code logic.

Your plugin is working fine, and many thanks for that!

Still, I would be glad to see this plugin handle .d2 files, alongside d2 markdown blocks. I have multiple reasons for that:

• the diagram may be used as a standalone diagram. As markdown block, it requires all the mkdocs galaxy to get the generated diagram
• people working on the diagram may be different than people working on the documentation
• a diagram could be included in multiples places

As example, I'm using the mkdocs drawio plugin that does exactly that. Of course there's a technical reason, drawio only handling its own format, but in the end it has been proven more effective than embedded diagram.

I have a sample mkdocs site, alongside an mkdocs devcontainer publicly available. I would be glad to discuss this need with you, if you are interested.

• My devcontainer + mkdocs with drawio sample
• A branch to trial d2
• Especially how diagrams are included
• The drawio plugin

Thanks!

[landmaj]

Hi,

this is a great idea and should be easy to implement. I will have some time this weekend, so there is a chance this issue will be closed by Monday. 🙂

One thing I need to consider is how to allow per-diagram configuration. The drawio plugin you linked uses standard markdown links (![My alt text](my-diagram.drawio)) and there is no space in them to put key=value pairs. However I've seen other plugins use something more akin to HTML and I think it could work. For example MkDocs Swagger UI Tag:

<swagger-ui src="https://petstore.swagger.io/v2/swagger.json"/>

I'm open to suggestions.

[Karreg]

I'm really glad that you like the idea :)

I had the same thought about configuration while writing this issue, and I got "eh, I guess it's doable directly in the D2 file, and if not, we could consider not allowing custom config for D2 file, while allowing on markdown diagrams".

But any other way to include them could work. I think there's a way to pass configuration to an include in a markeownish way, but without being markdown standard...

However, there's no markdown standard.

I'll give it a thought and come back with a better answer :)

[Karreg]

Got it. I knew I wouldn't have to search for long : https://squidfunk.github.io/mkdocs-material/reference/images/#image-alignment

Mkdocs material is using such key value configuration on images. We could consider the same thing... And even allow D2 configuration alongside image configuration when the diagram is generated.

[landmaj]

I got it working, you can check out and test version 0.4.1. I want to improve finding source files (https://github.com/landmaj/mkdocs-d2-plugin#known-issues-i-plan-to-fix) so I'm not closing the issue just yet.

[landmaj]

And it's done, I just released version 1.0.0. You can find usage and configuration examples in the updated documentation.

[Karreg]

Great! I'll try right away and get back to you... Thanks!

[Karreg]

It's working fine. I have created a PR to fix typos in the associated documentation.

I'm interested by the multiboard output cannot be written to stdout problem if you have more information, as I couldn't find reference to that in either d2 documentation nor their issue list. Do you know why it's (not) working like that, and if it can be worked around. The notion of scenario would be a great addition, by, for example, selecting the scenario to export by an include attribute...

And many, many thanks for this feature addition! Except the generation time that is quite long with ELK (but that's unrelated to your plugin), it's working really fine.

[landmaj]

There is this comment in D2 source code but no related issue, so I would not expect it to be fixed any time soon.

It doesn't allow outputting to stdout because such diagrams produce multiple files. Try to compile last diagram from this page like so:

d2 in.d2 out.svg

And will end up with the following output:

out
├── index.svg
└── numbers.svg

I have no idea how to embed that into HTML.

[Karreg]

scenarios could be used in 2 different manners:

• to generate a single, animated file, like what d2 is showcasing, but I'm not really impressed, I'm not sure about the use case. animation gets in the way of reading the diagram
• to generate the layer we want, to have a single diagram source, but multiple output depending on the location in the documentation. with an attribute, let's say { target="scenario_id } for example.

I find the second use case more interesting. The only other way to do that, is to duplicate the diagram, just to display a bit more information. and it breaks the only one golden source rule.

But I guess it still requires a fix on d2 side. Thanks for creating the #4 issue! :)