search

speced / bikeshed

:bike: A preprocessor for anyone writing specifications that converts source files into actual specs.
https://speced.github.io/bikeshed
Creative Commons Zero v1.0 Universal
1.06k stars 196 forks source link

Support mermaid diagrams #2539

Open jyasskin opened 1 year ago

jyasskin commented 1 year ago

Either Mermaid or PlantUML would work, but Github picked Mermaid, so it probably makes sense to follow them.

tabatkins commented 1 year ago

Yeah, if there's a Python library for such I'd love to support this, akin to my support for railroad diagrams.

Right now, afaict, that isn't the case - I'd have to link in the mermaid JS lib, and it would result in document shift as the diagrams are rendered.

tabatkins commented 1 year ago

...well, hm, there is https://mermaid.js.org/config/Tutorials.html#jupyter-integration-with-mermaid-js which shows off using a live-rendering service to generate the images directly. I suppose that works, especially if I do some content-aware caching to avoid pinging it when you've already generated a given image.

tabatkins commented 1 year ago

I guess it would have to be a bikeshed source command, tho, which requires you to run things locally. bikeshed spec can't easily return a bunch of images alongside your spec. Tho I could embed it as base-64 instead, hmmmmmm.

jyasskin commented 1 year ago

https://mermaid.ink/svg will return SVG that we could embed directly.

jyasskin commented 1 year ago

Also https://github.com/mermaid-js/mermaid-cli#run-with-npx when Bikeshed notices that npx is available.

tabatkins commented 1 year ago

Ooooooh, I didn't see the /svg option, that's neat.

sirex commented 1 month ago

There is a command line interface to generate SVG files from Mermaid: https://github.com/mermaid-js/mermaid-cli

mmdc -i input.mmd -o output.png -t dark -b transparent

I guess, Bikeshed could save Mermaid code snippets to a separate file and generate SVG files, that can be embedded into the output.

There is also an option to replace Mermaid code block with links to images directly in Markdown files:

mmdc -i readme.template.md -o readme.md