support mermaid

Describe the solution you’d like

support mermaid

Describe alternatives you’ve considered

The conf.py I used to make work mermaid with recommonmark:

$ tail conf.py
extensions = [ 'recommonmark', 'sphinxcontrib.mermaid']
from recommonmark.transform import AutoStructify
def setup(app):
    app.add_transform(AutoStructify)
$

This mermaid is rendered

```mermaid::

  graph LR
    a --> b
\```

Note that the above need to have a new line after mermaid:: and graph need to start with a space.

[brianv0]

Just to add a bit of context which may be helpful. Mermaid itself already has directives that are relevant for rendering a figure. Those are already passed through to e.g. mmdc and sphinxcontrib-mermaid, for example. sphinxcontrib-mermaid supports a few extra parameters for it’s directive.

I’d like to request that mermaid-tagged fenced code blocks, specifically, and possibly others down the road, be treated as directives instead of languages.

You could do so here, by detecting “special” languages that should be interpreted as directives instead of languages to highlight.

https://github.com/executablebooks/MyST-Parser/blob/310580730652f3b84da3868f2a886ef9fc743959/myst_parser/mdit_to_docutils/base.py#L596-L603

A hacky version I did was able to deal with this:

 info = token.info.strip() if token.info else token.info 
 language = info.split()[0] if info else "" 
 if language in ["mermaid", ...]:
     # update language to mimic directive
     language = "{%s}" % language
     # rewrite token.token.info for render_directive
     token.token.info = language + (" %s" + ' '.join(info.split()[1:]) if info.split()[1:] else "")
  
 if (not self.md_config.commonmark_only) and (not self.md_config.gfm_only): 
     if language == "{eval-rst}": 
         return self.render_restructuredtext(token) 
     if language.startswith("{") and language.endswith("}"): 
         return self.render_directive(token) 

[ajcerejeira]

Oh so you are talking about this Gitlab only feature: https://docs.gitlab.com/ee/user/markdown.html#mermaid? This won’t work on Github (unless perhaps you have a browser extension https://github.com/BackMarket/github-mermaid-extension), and kind of works more by luck, than by design on Gitlab (it seems to be ok ignoring the :: at the end)

It works now on GitHub as well: https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/

Here an example:

```mermaid
graph TD;
  A-->B;
  A-->C;
  B-->D;
  C-->D;
 ```

It produces:

  graph TD;
      A-->B;
      A-->C;
      B-->D;
      C-->D;