support mermaid diagram block syntax within markdown for documentation

[heckj]

Feature Name

mermaid support

Description

Mermaid is a javascript library, MIT licensed, that takes block text declarative configurations and renders them as diagrams - UML, Sequence, and others. I was recently asked if DocC supported mermaid, which led to me inquiring what it might take to trial it out and consider it. Per a conversation on the forums about Mermaid.js, I wanted to open a feature request for the DocC renderer to support mermaid diagrams.

Motivation

The primary goal would be to present diagrams (flowcharts, sequence diagrams, class or state diagrams, etc) as additional content within documentation based on a bit of declarative text rather than generating images for any of these relevant diagrams. The use case in particular that stirred the initial conversation was focused on adding sequence diagrams into internal app documentation for an iOS project.

Importance

The feature unlocks new use cases, and more specifically greater information sharing by developers without the resources to freely generate and include diagrams into their content.

Alternatives Considered

No response

[mportiz08]

Thanks for opening this @heckj. It might take a little time for us to properly investigate this, but I want to make sure we're tracking it since I imagine this could add a lot of value in supporting diagrams in documentation.

[bdrelling]

Love the idea of this! This would add some major value to DocC.

[benrimmington]

MermaidJS is the only diagram language I've used. It has the advantage of GitHub integration.

D2 appears to be a better language. Its creators have made a comparisons site:

https://text-to-diagram.com

[Panajev]

D2 seems monumentally more expressive to be fair. Want to put it through its paces, but it seems leagues above the competition. Any reason we could not support both? If so, any reason not to push D2?

[d-ronnqvist]

I feel like there's a lot to explore here. Diagrams can be a great addition to written documentation and built-in support for diagrams of some sort in DocC could have a big impact.

That said, for the type of code diagrams that I create I haven't had much luck with any text-to-diagram tools. I abandon most of my attempts due to lack of control over alignment. As an example, I tried just now to recreate this diagram from the Swift-DocC code but couldn't get either Mermaid or D2 to produce a layout that I felt made the illustrated flow easy to understand.

I'm personally somewhat hesitant towards adding direct support for any specific diagramming tool or framework in DocC. My main concern would be that it's hard remove that support once developers rely on it and I don't see either tool as a clear long term solution for documentation diagrams. A better design may be to allow for diagrams to be rendered via plugins somehow but that design discussion would require a lot more input.

For developers who want to use Mermaid or D2 to create diagrams for documentation today; my recommendation would be to use their respective command line tools to create images (e.g. PNGs or SVGs) and use those images in the documentation.

[sigsbeym]

I'm not sure exactly which type of UML diagram you're trying to make here, but it looks like a sort of activity diagram. I created a diagram detailing the process here using Mermaid markdown:
https://gist.github.com/sigsbeym/384816422c593118de3a7061a5bb8e5c

The benefit for me of using one of these markdown tools is not having to readjust all the dashes and pipes when updates are made. It just reshapes itself.

I understand the hesitance to bring on a specific diagramming renderer as a dependency, and understand why you wouldn't want to build that in directly.

Storing images is far more expensive than storing some lines of markdown. Additionally, a developer would have to store both the markdown and the images, otherwise someone can't come in and quickly modify the diagram as updates to the code are made.

For now, I've resorted to storing my diagram markdown in a markdown file in the repository to take advantage of the GitHub Mermaid renderer, but then it's not available in the DocC output.

[d-ronnqvist]

I'm not sure exactly which type of UML diagram you're trying to make here, but it looks like a sort of activity diagram. I created a diagram detailing the process here using Mermaid markdown:
https://gist.github.com/sigsbeym/384816422c593118de3a7061a5bb8e5c

I'm not sure if my idea for that diagram translates well to one of the diagrams types that Mermaid supports. It's possible that it's closer to a sequence diagram in spirit — trying to describe how bridging with other documentation systems fit into the flow of the broader documentation convert process. I don't remember which diagram types I tried when I attempted to recreate that diagram last year but my results were roughly the same as the one you linked to. In my opinion all of those diagram were not suitable replacements since I feel that they imply a different flow than the manual diagram.

If you have a text-based diagraming tool that works for you, you could use a CI action or script to generate SVG files from a collection of diagram files. Depending on how the documentation is hosted, it's possible that the generated files don't even need to be committed to the repo.

[sigsbeym]

Yeah, I agree. I don't typically make activity diagrams. I also wondered if this would make more sense as a sequence diagram, but was just trying to mimic what you had. I mainly stick to class, sequence, or component, which I feel can be represented very well with these generators.

A CI process is an option I've started looking into but requires a fair bit of tooling I'd have to get set up. Currently not hosting the documentation since it's for private use only and opens a whole other can of worms, but that's an avenue I might consider given the lack of other options. I just want to be able to build documentation locally and keep the markdown inline with the code to enable developers to build documentation when they want it and see the diagrams there in the docs.

It feels like a code documentation tool should have some kind of UML diagramming support. Document code to cover classes, functions, and variables. Diagrams to cover behavior, and structure of components and systems. It's all code documentation to me, just at different levels and perspectives. 🤷‍♂️

[natikgadzhi]

I was researching SymbolKit, and stumbled at this from a different angle. @d-ronnqvist, how do you feel about adding an exporter to SymbolKit that could output Mermaid (or D2) format, so folks can then add a script to generate diagrams automatically?

Perhaps, DocC could generate the graphs in Mermaid format, but docc-render could output them in an HTML comment, so they don't just show up as text, and the user has a choice to run a rendering step on their own?

Hypothetically, for small modules, that could be useful, but I fear that for larger modules, not having control over layout of the diagram will ultimately ruin the fun. That, and the maintenance costs of adding anything like that to SymbolKit.

I'll play around with the idea, see if I can show a proof of concept. If I can render a SymbolKit graph into a Mermaid spec, I'll include a script or GH action that renders Mermaid into an SVG, and then runs docc.

[DatBlaueHus]

Actually, I won't ask so much for support for a specific diagramming tool, as tools come and go, and most of them provide decent export.

What would be immensely useful though would be to have the option to integrate SVG or PDF.