Mermaid - Generation of diagrams and flowcharts from text in a similar manner as markdown

47

Yes it’s too far late to dictate a rule that says a fenced code block without some new signifier must only render as source. And adding modifiers to the first info string token such as !mermaid will break too many things as well.

The simplest most backward compatible solution would be to establish a standard around an optional second token of the info string that, if used, makes explicit whether the code block should be rendered as source code or “executed”. It could work like this:

  1. an = second token is an explicit declaration that the content should be rendered literally, as source code.

    ``` mermaid =
show the mermaid diagram source code here, 
perhaps with syntax highlighting
```

  2. a ( or () second token is an explicit declaration that the content should be “executed” (interpreted, rendered or otherwise processed) if possible.

    ``` mermaid ()
render the diagram described here
```

    ``` markdown ()
render the markdown source here
```

  3. If neither of the above tokens occurs in the second position, you get todays behavior, thus backward compatibility.

    ``` mermaid theme:dark
whatever happens today for the above info string
```

    :triangular_flag_on_post: The above form also serves as the “user friendly” form, meaning that, for the given content type named by the first token, the most natural thing should happen. For Mermaid, what most users expect is that a diagram is rendered.

  4. The remainder of the info string is passed thru to the syntax highlighter or extension determined by the first token, i.e. with the = or ( and ) removed. Calls to existing libraries will continue to work without changes.

    ``` mermaid ( width:300px height:300px )
invoke the diagram renderer with the
following args:
   width:300px height:300px
```

    ``` javascript = numberedLines:true
configure the syntax highlighter with:
   numberedLines:true
```

backward compatibility

The only case where backward compatibility might be lost is when all of the following are true:

  • the renderer doesn’t know about the above tokens and does not remove them from the info string before passing it to the extension or syntax highlighter
  • that extension looks beyond the first token
  • and has brittle expectations for the second token (it isn’t designed to skip unknown tokens in the info string) and fails hard

I think this will be rather rare and mostly limited to power users, who will figure it out and update their software or demand that it gets updated.

The other proposals mod the first token. They won’t degrade gracefully.

1 Like