Looks pretty interesting. It aims to be like markdown, but for diagrams.
http://knsv.github.io/mermaid/
Wonder how one would support this within commonmark, even if it’s as an extension hook. If using custom containers like in https://markdown-it.github.io/ , then it may look like this:
::: mermaid [ Diagram Description/Title ] :::
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
:::::::::::::::
If anyone’s wondering, yes, people have pointed out the similarities to GraphViz’s DOT format: https://github.com/knsv/mermaid/issues/5
The discussion seems to be still open, but stalled since the end of 2014 (with a single comment in May of this year).
I think this kind of thing is best handled using fenced code blocks that are marked in a special way, plus some kind of filter on the AST, as in the gitit wiki.
That brings to mind the question of if commonmark has a way to marking a fenced block as something that should be treated differently if a AST filter is present, else display as a marked up syntax. (e.g. runnable python code, or dot diagrams)
There’s the “info string,” which can contain just about anything. So your AST filter just needs to look for a marker in the info string. For example:
``` dot
-- put your dot diagram here
```so the info string is any text after the ``` but with a space? If so then there would be a distinction between:
No Space:
```dot
-- put your dot diagram here
```
and With Space
``` dot
-- put your dot diagram here
```
Where the first one would be rendered as just “block code” but with dot syntax markup and the second as a “dot diagram”? So with that logic, to have a “dot diagram” with “dot code fallback”, it would look like?:
```dot dot
-- put your dot diagram here
```With its many English keywords, Mermaid fails to actually be like Markdown which doesn’t use keywords at all (although several extended flavors do).
I’m not saying a generic graph description language could or should be done without keywords, DOT uses them, too.
The leading space is trimmed. See http://spec.commonmark.org/0.22/#info-string
Dot diagram with dot code fallback could just be
``` dot
...
```
because the first word of the info string is used by default for the code syntax class.
and if you want just the dot code without the dot diagram? (Specifically say… the author is illustrating how to write dot code?). Perhaps .dot instead of dot in infotext indicate that it must be displayed as code?
This could be a difference between backtick and tilde fences. Tilde would be parsed if possible, backtick was always displayed source code.
It is quiet difficult syntax./mermaid is overtly complicated.
http://bramp.github.io/js-sequence-diagrams/ is much true to markdown.
and if you want just the dot code without the dot diagram? (Specifically say… the author is illustrating how to write dot code?). Perhaps .dot instead of dot in infotext indicate that it must be displayed as code?
Well, it’s up to the particular application to define this. (There are so many special purpose things like this you might want to do, it would not make sense to build them into the spec.) An application could use anything it likes in the info string to trigger dot rendering. If you want to mix dot syntax examples with rendered diagrams, then you might want to use a different convention than the one used in gitit.
That sounds rather fair. I can imagine the spec would have a section on recommendation for trigger words to always be provided e.g.diagram like:
``` dot diagram
...
```
And if diagram is not in infostring, then the plugin would simply ignore it and let it fall to code block mode.
Which would mean that by convention, the plugin will not activate without seeing the diagram keyword in the info-string (could be other keywords as it’s only a recommendation, not a standard).
I cannot and don’t want to see CM adopting English trigger words.
However, there’s syntax precedent for embedding instead of more or less verbatim rendering: the exclamation mark in image syntax vs. normal hyperlinks. I could see extensions adopting this letter for the info string, e.g.:
``` dot!
or
```! dotThose are totally different graph types, though. As an example of syntax, it’s interesting but not very closely related.
I totally agree with embracing the exclamation point as a generic marker of embedding content in commonmark, and this aligns with what I suggested elsewhere to disambiguate image link syntax and convert alt text into a visible caption.
Keep in mind that Mermaid, Viz.js (Graphviz), et al. are one of those things that should work fine today as embedded HTML with not much more syntax burden than fenced code blocks would require.
Whether that translates into usable graphing behavior when exporting to PDF or ePub, e.g., from a given implementation may be a different, more difficult, story.
If web-components will become a thing, and we use the ! as the trigger char for codeblocks then we could just make it so that:
``` !mermaid A Demo Diagram { .diagramStyle id=demoChart }
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
```
<mermaid class=diagramStyle id=demoChart alt="A Demo Diagram" >
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
</mermaid>
Essentially a no-markdown island. Of course, you could also have a filter in front of the AST to catch and modify the behaviour before it defaults back to webcomponent mode.
Using Concepts from:
Note, until the official mermaid supports webcomponents, if the above approach is adopted… you will need to type like this:
``` !div { .mermaid }
CHART DEFINITION GOES HERE
```
To render as in this official example :
<div class="mermaid">
CHART DEFINITION GOES HERE
</div>
Alternatively, you can have a official commonmark-mermaid plugin that captures the web-component and output the correct html code for the mermaid engine (at least until they switch to webcomponents).
class=dot or id=dot. ( e.g. .mermaid is equiv to !div { .mermaid } )If people like this idea and it has not been discussed before, I could probbly paste this into it’s own thread. Or maybe slip it into the “no markdown island” if relevant.
I don’t like the generic attribute syntax with curly braces at all, but I could live with special-casing strings that are introduced by dot . or hash # in places that don’t get rendered. The exact treatment depends on the output format, HTML attributes id and class are obviously the default case. Other places than the info string of a start fence are the location and reference parts of links, but it’s not as compatible with existing implementations, e.g.:
[text](location .class #id)
[text][reference .class #id]
[reference]: location
[text][reference]
[reference]: location .class #id
So I presume you mean something like this? Crissov?
``` !mermaid A Demo Diagram { key=value }
...
```
``` ! .mermaid A Demo Diagram { key=value }
...
```
``` ! #mermaid A Demo Diagram { key=value }
...
```
``` ! #mermaid .mermaid A Demo Diagram { key=value }
...
```
``` !mermaid #mermaid .mermaid A Demo Diagram { key=value }
...
```
<mermaid key=value alt="A Demo Diagram" >...</mermaid>
<div class=mermaid key=value alt="A Demo Diagram" >...</div>
<div id=mermaid key=value alt="A Demo Diagram" >...</div>
<div class=mermaid id=mermaid key=value alt="A Demo Diagram" >...</div>
<mermaid class=mermaid id=mermaid key=value alt="A Demo Diagram" >...</mermaid>
In most cases the generic attribute syntax can be omitted if you do not need to set any values in html (or plugin/extention settings). (basically I know it’s ugly, but it helps avoid overloading the most common commonmark syntax, by moving the cruft to an optional {}.
On the question of compatibility. This is what it would generally look like (in current commonmark):
<pre><code class="language-!mermaid">...</code></pre>
Edit: Added ! .mermaid to .mermaid and others, to account for the case that people want to style “code blocks” rather than styling web-components.