mgaitan / sphinxcontrib-mermaid

Mermaid diagrams in yours sphinx powered docs
http://sphinxcontrib-mermaid-demo.readthedocs.io/en/latest/
Other
325 stars 91 forks source link

Enable myst-parser mermaid rendering without curly braces in markdown #99

Open d33bs opened 1 year ago

d33bs commented 1 year ago

Thank you for the great work within this project! In working with mermaid diagrams through this extension and myst-parser within markdown files I've noticed a minor detail which might assist developers as they draft or review content.

When using this extension via myst-parser in markdown files, one is required to use the following format:

```{mermaid}
<diagram content>

Some editors and interfaces, such as Github ([see here](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams#creating-mermaid-diagrams)), enable the rendering of mermaid without building it Sphinx. This format relies on a similar codeblock that does not use curly braces, as seen below:
````markdown
```mermaid
<diagram content>


Using a format which does not rely on curly braces would allow developers referencing mermaid content on platforms like Github to easily view both the rendered output and the code which rendered the output. Is this something which is possible through additional configuration or code with this extension? Thank you in advance for your thoughts and feedback on this topic.

Please note: I was unsure whether it'd be more appropriate to open an issue here or with the myst-parser project. Please don't hesitate to let me know if I may reference this topic elsewhere, or upvote an existing issue, thank you!
bilderbuchi commented 1 year ago

I agree, this would indeed be useful to have! It would make collaborating and reviewing/discussing PRs much more streamlined if the mermaid diagrams were rendered in the PR files/diff view, and I think using the brace-less syntax should achieve that. Right now we can either open parallel issues where we copy/paste diagrams, or render the whole documentation and inspect that.

bilderbuchi commented 1 year ago

See also https://github.com/executablebooks/MyST-Parser/issues/366#issuecomment-1239679922

ggydush commented 1 year ago

+1 to this feature, would be a great improvement!

vppillai commented 1 year ago

+1 to this feature.

dustinlagoy commented 1 year ago

Note https://github.com/executablebooks/MyST-Parser/issues/366 has been fixed by https://github.com/executablebooks/MyST-Parser/pull/742 which I believe also fixes this issue.

rjohnkraemer commented 3 months ago

+1 to this, would also like to see

::: mermaid \<diagram content> :::