Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Integrate mermaid or another type of diagram generator in zmarkdown #171

Open
artragis opened this issue Oct 9, 2017 · 12 comments
Open
Labels
misc/help wanted This issue needs help semver/major This is a breaking change status/verified This has been checked by a maintainer type/request This is great to have

Comments

@artragis
Copy link
Member

artragis commented Oct 9, 2017

It should be useful for authors to create diagrams only by typing texts.
For this purpose, we can use mermaid which is a very common tool for such purpose.

We can also mention graphviz that has a remark integration.

@arobase-che
Copy link
Contributor

arobase-che commented Feb 10, 2018

Mermaid is very specialized. It can create Flowchart, Sequence diagram and Gantt diagram (and so, not graph).

The sequence diagrams are hard to read but the flowcharts and Gantt diagram look good.

I will try remark-graphviz the dot language is a well-known language.

@artragis
Copy link
Member Author

we can integrate both. sequence diagram is pretty cool with mermaid. So is flow chart.

I think having many tools can be the best way of building a good redaction interface. So if you can add graphviz to zmd & rebber let's do it

@nils-van-zuijlen
Copy link
Contributor

I think the syntax for integrating mermaid should be the same as on gitlab.
So it should be the following and look like if it were code with the syntax mermaid

```mermaid
graph TB
A((round)) --> B(Rounded)
B --> C[Square]
C --> D{Diamond}
C --> E>Strange]
```

And if mermaid uses this syntax, it seems logic to me to use the same kind of syntax for graphviz.

@vhf
Copy link
Contributor

vhf commented Apr 11, 2018

@nils-van-zuijlen see https://github.com/temando/remark-mermaid

@artragis
Copy link
Member Author

Hi @vhf I've ssen your PR on their upstream (which does not pass). I do hope it will be merged quickly so that we can integrate mermaid in zmd.

@artragis
Copy link
Member Author

for this issue the main bottleneck seems to be ternando as they "officialy" maintain remark-mermaid and remark-graphviz but do not review nor accept pr from extern contributors.
VHF had an interresting PR to ease the use of remark-mermaid in zmarkdown use case but they did not do anything for two years. Another pr to create an "inline svg" exist in remark-graphviz since februray 2019 without any feedback of ternando. Would it be a good thing for zestedesavoir and zmarkdown to create a fork of those two repo and maintain them?

@StaloneLab
Copy link
Member

The way these plugins work now are quite unsustainable I'd say:

  • at first, everything is in a single file, which I would not recommend as a project architecture (well, you can't call utils.js a real file;
  • the mermaid diagram generator uses a binary system call to generate the diagram, which involves globally installing mermaid; once more, bad practice, especially when you consider that mermaid exposes a Javascript API;
  • the graphviz util is based on viz.js which is an Emscripten-compiled project, making it... huge; furthermore, it's developpement has ceased; we would need to replace it by an alternative, dagre seems to be the standard in Javascript.

Forking these utils would add a lot of work to refactor them, in order to make them clean. Once it will be done, we will also need to maintain them. I'm currently working on something else, so I'll not have time to do this anytime soon, but if somebody wants to work on it, he needs to know the work is quite important. We need to fork these if we want to use them, so guess it is not a problem if someone adds them to the packages/ directory and pull them here after a refactor; maybe we could also contact the original developpers to get the package name on NPM (these are unique, so we can't reuse it without permission, unfortunately...).

@vhf
Copy link
Contributor

vhf commented Aug 25, 2019

IMO remark-mermaid code structure isn't that bad. It does spawn a child process but that's to an npm package that we could depend on, not to a completely foreign binary.

The one thing we need first and foremost is temando/remark-mermaid#5

If the package could be refactored in a way that doesn't need to shell out it would be a bit better I agree.

And if it could be made not to rely on a filesystem being available that would be even better because we could then use it client side, but that's another topic and not a hard requirement. The bundle size would probably be too big anyway.

@firm1
Copy link

firm1 commented Jan 8, 2020

Hi,

The remark-mermaid project has not been maintained for more than two years. I think it might be interesting for us to fork this project.

This feature would be really good for zmarkdown.

@StaloneLab StaloneLab added misc/help wanted This issue needs help semver/major This is a breaking change status/verified This has been checked by a maintainer type/request This is great to have labels Feb 3, 2020
@artragis
Copy link
Member Author

artragis commented Nov 3, 2020

It appears that mermaid-js project released a way to render code into svg => https://mermaid-js.github.io/mermaid/getting-started/usage.html#example-of-a-marked-renderer when zmarkdown uses next remark api #416 we should be able to create a good plugin

@StaloneLab
Copy link
Member

Your link is 404 for me. Anyway, nice if we can now render SVG, will have to see how this work.

@artragis
Copy link
Member Author

artragis commented Nov 6, 2020

Il fact I made more research and the libraries they use in background to generate a readable svg need a browser to be used (headless or not). The "API" is just a way to ask the browser to render a code. The only way to "integrate mermaid" on zmd is therefore to just create a <div class="mermaid">${innerText}</div> when code language is mermaid. I will try to find an alternative

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
misc/help wanted This issue needs help semver/major This is a breaking change status/verified This has been checked by a maintainer type/request This is great to have
Projects
None yet
Development

No branches or pull requests

6 participants