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/mermaid@9.2.2";
    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.

[github-actions]

🤖 This is an automated response from Repo Assist.

Following the discussion here (especially nojaf's suggestion about a docs recipe), I've opened a draft PR that adds a Mermaid recipe page to the docs — similar to the existing MathJax example.

The recipe shows how to add Mermaid to any fsdocs site by dropping a single (script type="module") tag into _head.html, with three worked examples (flowchart, sequence diagram, class diagram).

No changes to the fsdocs tool itself are needed for this approach.

Generated by Repo Assist

To install this workflow, run gh aw add githubnext/agentics/workflows/repo-assist.md@077cdbca7864e820e3425e9598cf1269d3dce05a. View source at https://github.com/githubnext/agentics/tree/077cdbca7864e820e3425e9598cf1269d3dce05a/workflows/repo-assist.md.

[dsyme]

Fixed in docs