Add markdown support for diagrams using js-sequence style blocks

[jcollins-g]

Allowing inline diagram support from comment text to markdown (and indirectly, dartdoc), would be a nice thing to have for doc writers, so they don't have to have opaque image links in the source code when a simple diagram would suffice.

https://support.typora.io/Draw-Diagrams-With-Markdown
https://github.com/bramp/js-sequence-diagrams

[srawlins]

Isn't this something that could be done (or would have to be done) as a post processing? Like the js-sequence library would, in the browser, find HTML like <pre class="language-sequence">...</pre>, and turn it into an image/svg/mathml/whatever?

[jcollins-g]

@srawlins I don't know enough javascript to know without some research, but that doesn't sound unreasonable. In that case all markdown would need to do is generate that when it sees the appropriate markdown and leave it to the js-sequence library?

[srawlins]

Yeah, I think Markdown provides good enough support for this out-of-the-box:

$ cat a.md 
Text

```sequence
Alice->Bob: More text.
```
$ dart bin/markdown.dart a.md 
<p>Text</p>
<pre><code class="language-sequence">Alice-&gt;Bob: More text.
</code></pre>

So the js-sequence library could work on that output.

[srawlins]

Mermaid might be the new way to do this. https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/ Supported on GitHub out of the box.

[timmaffett]

I created a interop wrapper package for mermaid.js and have submitted a PR to illustrate the changes needed to the markdown example code to support mermaid diagrams.

Here is an example illustrating a number of Mermaid diagram types

See PR dart-archive/markdown#429 for more details.

Mermaid was generally impressive, and in conjunction with Markdown seems to make a fast combo. You can see how fast real time editing in the example above is, even with an example of every diagram type re-rendering with every key stroke.