StatiqMermaid - Pipeline and modules for rendering Mermaid diagrams to SVG

[ociaw]

I just published StatiqMermaid (NuGet). It adds a module to build Mermaid definitions from type hierarchies and two to render definitions to SVG - the first pulls definitions from a document, and the other is a post-process module that renders Mermaid definitions found in HTML files.

I've also modified _TypeDiagram.cshtml in Docable so that it's essentially just:

@{
    var svg = await Context.Outputs.FromPipeline("Mermaid")
        ?.FirstOrDefault(doc => doc.Source == Model.Source)
        ?.GetContentStringAsync();
    }
}

<div class="mermaid svg">
    @Html.Raw(svg ?? "")
</div>

This lets me remove Mermaid entirely from the theme, saving each new visitor a 1.1 MB download.

I'd be interested in seeing if/how this can be incorporated into Statiq. The main hurdle is that it relies on mermaid-cli, a very heavy NPM module. Try as I might, mermaid can't be executed with a built-in JS engine since it needs a full browser; mermaid-cli spawns a headless chrome instance.

I'm also not sure of the best way to launch an executable per-document in Statiq. External Processes aren't a good fit, as far as I can tell, and ProcessLauncher doesn't support feeding documents into the process via STDIN. Right now I'm starting them in an ad-hoc sort of way, capping the number of simultaneous processes to a hardcoded limit of 16. But it's not great, and something more robust is definitely needed.

[daveaglick]

I just published StatiqMermaid (NuGet).

Very cool! It's been in my plans for a long time to add a "gallery" feature to the Statiq documentation site that can be used to showcase addins, sites, blog posts, etc. related to the tool. I'd love to see community extensions like this catch on.

I'd be interested in seeing if/how this can be incorporated into Statiq.

I don't know that we want this exact change upstream in Docable, but I'd venture that the extensibility of Docable is working very well here - you were able to swap out a portion of the theme for something else more customized without having to make big changes to other files. When the theme gets updates, you should be able to bring those in and keep the changes you made to this one file too.

Now if we're talking a bigger-picture upstream support, that's a whole other thing :). I'd be happy to get rid of the runtime Mermaid rendering and (optionally) allow generation-time rendering. As you noted, interacting with external processes (especially per-document) isn't ideal, at least not right now. Doubly-so when those are part of Node/npm infrastructure. That said, I'd love to hear ideas on how we could make this better in the engine.

ProcessLauncher doesn't support feeding documents into the process via STDIN

This seems like a fantastic idea, both the ability to feed arbitrary content to a process over stdin, and also a module that hooks that up to per-document processing with throttling. That would certainly open up some interesting integration scenarios and is probably a good first step to better Statiq support of scenarios like this.

I've created statiqdev/Statiq.Framework#261 to track this enhancement.