support mermaid

[LuisBL]

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.

[welcome]

Thanks for opening your first issue here! Engagement like this is essential for open source projects! 🤗

If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.

If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).

Welcome to the EBP community! 🎉

[chrisjsewell]

Hey @LuisBL, from https://github.com/mgaitan/sphinxcontrib-mermaid, mermaid is a directive (not a code-block) so you have use it with braces

```{mermaid}
graph LR
a --> b
```

I'm a little unclear how this would have worked in recommonmark, since that does not support directives. Are you sure you didn't use it before inside an eval-rst?

[LuisBL]

Hey @LuisBL, from https://github.com/mgaitan/sphinxcontrib-mermaid, mermaid is a directive (not a code-block) so you have use it with braces

```{mermaid}
graph LR
a --> b

I'm a little unclear how this would have worked in recommonmark, since that does not support directives. Are you sure you didn't use it before inside an `eval-rst`?

Sorry my issue was not clear/compleat, updated.

[chrisjsewell]

Sorry my issue was not clear/compleat, updated.

Cheers, but what happens now if you add?

```{mermaid}
graph LR
  a --> b
```

(with extensions = [ 'myst_parser', 'sphinxcontrib.mermaid'])

[LuisBL]

with

```{mermaid}
graph LR
  a --> b
```

It render perfectly well and there is no need to add a def setup(app): to conf.py

so I can close this and open an issue to improve the documentation with the above exemple.

[chrisjsewell]

so I can close this and open an issue to improve the documentation with the above exemple.

brilliant 😄

[LuisBL]

Note: The

```mermaid::

  graph LR
    a --> b
```

syntax has the advantage that is render with the gitlab.com markdown renderer, that is not the case with the MyST-Parser syntax

```{mermaid}
graph LR
  a --> b
```

[chrisjsewell]

FYI, If you want to show nested code blocks you can just use more surrounding `

````
```{mermaid}
graph LR
  a --> b
```
````

[chrisjsewell]

syntax has the advantage that is render with the gitlab.com markdown renderer

You can always use:

```{eval-rst}
.. mermaid::

   graph LR
     a --> b
```

that would show up as:

.. mermaid::

   graph LR
     a --> b

[LuisBL]

great I will add it to the documentation too.

BTW: your https://aiida.readthedocs.io/projects/aiida-core/en/latest/intro/tutorial.html documentation is awesome I guess it's your own sphinx theme ?

[chrisjsewell]

oh thanks! No its just https://pydata-sphinx-theme.readthedocs.io

[LuisBL]

On my gitlab the below:

```{eval-rst}
.. mermaid::

   graph LR
     a --> b
```

```mermaid::

  graph LR
     a --> b
```

produce this:

so no real rendenring on gitlab using {mermaid} ;( neither on github

So we can conclude (I think) that

```mermaid::

  graph LR
     a --> b
```

render both on sphinx and on gitlab/github with the following conf.py:

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

[chrisjsewell]

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)