Add Support for Previewing Mermaid Diagrams

[1eyewonder]

Summary

I wanted to open this issue in order to start a discussion for potentially adding support for previewing mermaid diagrams using FsDocs. I think this would be a great addition to the tooling so users/developers can stay within the bounds of fsdocs and navigate any visualizations created by the mermaid syntax.

Applicable Areas

There are the areas I see as being applicable if we wanted to pursue this functionality

1. Literate scripts
2. Markdown docs

Areas of Inspiration

The reason I point to these is these two sites have a much better user experience in terms of panning and zooming. While GitHub has a built in previewer, in my opinion, their panning and zooming is not ideals for larger mermaid diagrams.

1. https://mermaid.live/
2. https://github.com/newmo-oss/mermaid-viewer

[nojaf]

I've used this in the past. In _body.html add

<script type="module">
    import mermaid from "https://esm.sh/[email protected]";
    mermaid.initialize({
        startOnLoad: true,
        theme: "base",
        themeVariables: {
            primaryColor: '#ffdd59'
        }
    });
</script>

and then use in Markdown:

<div class="mermaid text-center">
graph TD
    D[Teplin.Core]
    E[Telplin]
    F[Telplin.Lambda]
    G[Telplin.Core.Tests]
    D --> E
    D --> F
    D --> G
    H[Telplin.Deploy]
    I[OnlineTool]
 </div>

It makes me wonder if this should be an out of the box thing or not. Perhaps adding this recipe to the docs is good enough to start out.

[nhirschey]

I like @nojaf’s idea. A docs recipe like the latex MathJax one could be nice https://fsprojects.github.io/FSharp.Formatting/sidebyside/sideextensions.html

[1eyewonder]

I can add this to my docs to-do list. Thanks for the code snippet!

[houstonhaynes]

Has anyone checked out Siren as an option? https://github.com/Freymaurer/Siren

[IanWitham]

It would be great to be able to generate a mermaid diagram from a code snippet in a literate script -- essentially parsing output as markdown content. Can anyone tell me if that's possible? (Or rather, having output end up as unescaped html in the built page)

[simontreanor]

Based on https://mermaid.js.org/config/usage.html the script to use in the _head.html template file should be:

<script type="module">
  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
</script>

This then works with any html element with a "mermaid" class as in the example above.