feat: add diagram examples

[domWalters]

@hkato I took the basic mermaid examples from the official documentation and made a page in the documentation using your markdown-kroki.

Diagrams work well on the web version. Do you think there is a way to do light vs dark diagrams?

On the PDF version, they all work except the flow charts which lose their labels:

[domWalters]

This is the PDF for reference:

document.pdf

[hkato]

Hi @domWalters

Do you think there is a way to do light vs dark diagrams?

You can add Mermaid configuration like this. However, it is probably difficult to synchronize with the web's light/dark mode.

The theme option is here.
https://mermaid.js.org/config/theming.html

```mermaid theme="dark" 
```

On the PDF version, they all work except the flow charts which lose their labels:

Yes, it seems the problem lies in Mermaid's graph syntax when used with WeasyPrint's SVG rendering.

Please refer to my samples.

• https://hkato.github.io/markdown-kroki/diagrams/mermaid/
• https://github.com/hkato/markdown-kroki/blob/main/docs/diagrams/mermaid.md
• https://github.com/hkato/markdown-kroki/blob/main/docs/diagrams/mermaid.md?plain=1

For a temporary workaround, I used PNG format.

[hkato]

It reproduced using this procedure instead of mkdocs-to-pdf.

Generate an SVG file using mmdc/mermaid-cli.

echo 'graph LR\nhello-->world' | mmdc -i - -o test.svg

Generate a PDF from the SVG file.

weasyprint test.svg test.pdf

with warnings. (I don't know the details)

WARNING: Ignored `stroke-width: 1` at 1:1, unknown property.
WARNING: Ignored `stroke-dasharray: 1, 0` at 1:18, unknown property.
WARNING: Ignored `stroke-width: 1` at 1:1, unknown property.
WARNING: Ignored `stroke-dasharray: 1, 0` at 1:18, unknown property.
WARNING: Ignored `stroke-width: 1` at 1:1, unknown property.
WARNING: Ignored `stroke-dasharray: 1, 0` at 1:18, unknown property.
WARNING: Ignored `stroke-width: 1` at 1:1, unknown property.
WARNING: Ignored `stroke-dasharray: 1, 0` at 1:18, unknown property.
WARNING: Ignored `stroke-width: 2` at 1:1, unknown property.
WARNING: Ignored `stroke-dasharray: 1, 0` at 1:18, unknown property.
WARNING: Ignored `stroke-width: 2` at 1:1, unknown property.
WARNING: Ignored `stroke-dasharray: 1, 0` at 1:18, unknown property.

The PDF does not contain text labels.

However, opening the SVG with Chrome and printing to PDF results in a PDF that contains text labels.

Therefore, it seems that the problem is in WeasyPrint.

[hkato]

@domWalters

The issue was caused by CairoSVG.

Kozea/WeasyPrint#1196

If you use other class, such as flowchart, the generated SVG will contains <foreignObject> which are not rendered by CairoSVG. Check Kozea/CairoSVG#147. Typically, text will not be displayed.

[hkato]

How about adding a comment: "WeasyPrint/CairoSVG does not support flowchart text." Furthermore, as a workaround for this limitation, we can create the diagram in PNG format.

[hkato]

I will be offline a few days. It seems to be good, except for the flowchart issue.

[hkato]

Personally, my colleagues like both PlantUML and the GUI-based diagram tool, draw.io. These seem to be among the top three popular OSS diagram tools. Of course, it depends on the community.
My motivation for developing markdown-kroki is to enable PDF support for these three tools: Mermaid, PlantUML, and draw.io.
How about adding PlantUML and draw.io as examples?

https://hkato.github.io/markdown-kroki/pdf/document.pdf
https://hkato.github.io/markdown-kroki/diagrams/plantuml/
https://hkato.github.io/markdown-kroki/experimental/#drawio

[domWalters]

Personally, my colleagues like both PlantUML and the GUI-based diagram tool, draw.io. These seem to be among the top three popular OSS diagram tools. Of course, it depends on the community. My motivation for developing markdown-kroki is to enable PDF support for these three tools: Mermaid, PlantUML, and draw.io. How about adding PlantUML and draw.io as examples?

https://hkato.github.io/markdown-kroki/pdf/document.pdf https://hkato.github.io/markdown-kroki/diagrams/plantuml/ https://hkato.github.io/markdown-kroki/experimental/#drawio

I'd be happy with any additional diagrams.

I'm familiar with PlantUML and I've heard of draw.io I think.

[domWalters]

@hkato would you be happy with me including markdown-kroki as a submodule to mkdocs-to-pdf, and then we can use the same exact documentation examples as you're using?

I'd keep the top part of diagrams.md to give a brief explainer on markdown-kroki, and then have the different diagram language doc pages as sections under that.

[hkato]

it’s okay 👍 🚀

[hkato]

I'm worried that the public Kroki server might be unavailable. Sometimes the server encounters errors.
Using CI with Docker is reliable.

[domWalters]

@hkato, I've finally done some updates to this.

I recently changed the OS on my main machine and have been having a hard time getting stuff working again, but seems stable-ish now.

I've submoduled markdown-kroki, and directly integrate its diagram docs using markdown-include.

Feel free to ignore the shell.nix file. It's the minimal way I've got a dev environment working on my new machine, and I'll update it as needed.

[hkato]

Thanks for the integration.
I'm concerned about the slow performance of make docs. I believe running a Kroki server with a local Docker container would make it faster.

[domWalters]

Thanks for the integration. I'm concerned about the slow performance of make docs. I believe running a Kroki server with a local Docker container would make it faster.

Ah, I thought that might have been a configuration problem with my new PC.

I'll try do a local server.

[domWalters]

@hkato, yeah you are right. Running a local kroki server gives a 12 second build without the PDF rather than the ludicrous amount of time it was before