What would need to be updated to support mermaid diagrams in the markdown source for docs?

I was recently asked about DocC in the context of adding in a sequence diagram (for internal documentation on an app), and the person called out the mermaid javascript framework, which has recently been enabled on Github - hoping "it would just work".

As I thought about it, I realized I wasn't very sure about what all might need changing, and how "hard" it would be to add support for something like this to the current DocC documentation system.

It seems like all of the critical updates to enable something like this would likely be within the swift-docs-render project, but then I recalled recent threads talking about updating the markdown processor - so I wasn't sure if there wasn't some validation or processing that happened in swift, and would need to be touched, in order to allow for a code block with mermaid to be passed through and rendered correctly. I guess this may be a question for @ethankusters and/or @QuietMisdreavus.

The current system passes through any code blocks like this just as the text version, even without any warnings that the specific type of code block isn't supported, which made me realize I wasn't even sure if there should be a warning when something like an unsupported block is found in markdown content.

2 Likes

From the sounds of GitHub's blog post about its Mermaid integration, it seems like they implemented it in a post-processing step to allow for progressive enhancement in case a client has JavaScript disabled. This may not be a concern for Swift-DocC's case, but it's something to note. In general, their integration of Mermaid and MathJax happen after the Markdown processing - they're not handled in cmark-gfm at all.

I'm not sure about Swift-DocC-Render's policy in adding new dependencies like this, especially something that could create a potentially-expensive post-processing step like this. cc @marcus_ortiz who may know more.

2 Likes

I'm not super familiar with Mermaid myself, so I shouldn't comment on the specific technical question just yet.

In general though, I think we would possibly be open to introducing a new Swift-DocC-Render dependency as long as it provides a lot of value to DocC users without introducing any major performance/stability issues in terms of the added JavaScript bundle size for the built renderer, and it's something non-trivial that couldn't be implemented in the renderer itself. We would also need to make sure that the license is compatible from a legal perspective of course.

This might be a good candidate for opening an issue on the Swift-DocC-Render project since it sounds like the integration would likely be a part of the renderer itself based on the comment from @QuietMisdreavus.

2 Likes

Mermaid JS is popular. Even Azure DevOps supports it Markdown syntax for wikis in Azure DevOps - Azure DevOps | Microsoft Learn

The project is MIT

I opened it as a feature request on swift-docc-render.

4 Likes