[feature] mermaid.js

[kjellkvinge]

Integrate mermaid into gitea

mermaid claims to "Generate diagrams and flowcharts from text in a similar manner as markdown."

A diagram might be worth more than 1000 words. Even if I see some reasons not to have it, I think this could be a nice feature to have. - So i put this out there and see what happens :)

I have made a simple hack, so this:

```mermaid
graph TD;
    A(stuff)-->B[one];
    A-->C[two];
    A-->D[three];
```

Can look like this:

I have not figured out how to do this whithout toucing source in /vendor.

Heres a sample from a Hugo template:
http://docdock.netlify.com/shortcodes/mermaid/

Regards.

Kjell

[thehowl]

Thank you for your proposal! Unfortunately, I don't think it's a good fit for Gitea.

First of all, you are right saying that a diagram is worth more than a thousand words, and indeed, this would be "handy" in some cases. However, I think those cases can be very easily covered by a simple image (or SVG file) instead of a client-side generated diagram.

Since for many users the use-case for Gitea, and specifically markdown files inside of gitea, is that to document or otherwise describe their projects, almost always these do not involve diagrams; which is why, I think, this would not be suited for Gitea.

[lafriks]

Graphviz?

[sapk]

@kjellkvinge You can use external render via mermaid cli (https://github.com/mermaidjs/mermaid.cli). Implemented in #2570

[kjellkvinge]

Thank you all for reply to this. I guess there is not much interest to a feature like this based on the comments.
As mentioned, I have a working solution for this, so I raised this issue to see if I should crate a PR from this.
I will close this issue for now :)

regards.
kk

[sapk]

@kjellkvinge I use mermaid also for other things but for gitea and more for markdown we try to keep only the common base for everyone and provide easy customization for everyone via external markup render support. This permit to not bloat and limit the code we have to maintain. But feel free to suggest any improvement you can find/code using gitea ;-)

PS: If your solution is only based on JS you can edit file inside custom/templates/custom/header.tmpl to add custom js. In this case we can add your js file under contrib/ or just a link to your solution for mermaid in the documentation for any user that would need it.

[kjellkvinge]

@sapk thank you. I have no problems with the decision to not bloat the markdown feature. It makes sense. I will be happy to contribute later :)

My current solution require change in the vendored blackfriday package. No change in JS, except serving mermaid. - So I would not suggest this as a solution, but if I solve this using JS or the external markdown support, I will put this in the documentation.

thank you.

[rbong]

@sapk I am not sure you can use external renderers for this. Outputting to svg strips the output and attempts to render it as html, outputting to png appears to have no effect.

[rprieto]

I understand that external renderers might make this possible.

I still think it would be a nice built-in addition. It's very common to want to add diagrams to a README, and embedding a PNG does not encourage contributors to keep them up to date. A text-to-diagram syntax is ideal for that.

For what it's worth, GitLab supports it out of the box: https://docs.gitlab.com/ee/user/markdown.html#diagrams-and-flowcharts-using-mermaid (I only bring it up to show it's not an unusual feature to support).

[laoshaw]

all git webui nowadays supports source code well, markdown is now the dominant format for documents, adding mermaid and other markdown features into gitea will be great, inserting svg/png/etc works but not as easily as mermaid

[zeripath]

So I'm actually not against this. The only issue is that we have to be careful not to end up including the world. We really only should load mermaid if we need it too.

I suspect the best way of getting this included in Gitea is to create a feature that requires it - then it's there and we may aswell provide it.

Failing that, it would be genuinely interesting to know how difficult it is for users to add this to their Gitea or other markdown plugins. (For example jsMath)

[laoshaw]

how to submit a request as such? to me gitea is a code repo and markdown repo, the only weaker part is markdown side that could at least support mermaid some some math equations, with mermaid more urgent.