docs: add mdbook-mermaid plugin #1382
Conversation
docs/spec/mermaid.min.js
Outdated
There was a problem hiding this comment.
Unreviewable, gargantuan js files like this make me a bit nervous from a security perspective.
Is it worth having something like this, just to render a few sequence diagrams that could simply be screenshotted for the docs?
There was a problem hiding this comment.
Good callout... there's like 5 diagrams so it would definitely be a bit annoying to have to generate them and keep them updated if we have to copy-paste images. But I guess even with this mdbook-mermaid plugin we're still far from the nice WYSIWYG UI of notion... I think it makes sense to remove this then. @anupsv thoughts?
There was a problem hiding this comment.
Is there a way, as part of build workdlow or something that you can generate the images using the plugin, export it and commit to the PR branch? That way no need to upload the JS file and you don't inherit the hassle of keeping it updated ?
There was a problem hiding this comment.
The way I've seen it done in the past is to have a script committed, which uses mermaid cli to generate the diagrams. So, if you make an update to the mermaid file, you just run that script and commit.
There was a problem hiding this comment.
Looked into this. Didn't find any way to achieve that result. It would necessitate updating the markdown files replace the mermaid diagrams with image links, and mdbook-mermaid doesn't seem to support that. At least I documented the dependency, pinned mdbook-mermaid to v0.14.1. Also now that the js files are installed they won't ever be updated, so we are trusting that this js file is correct. I looked around and most other projects depend on it as well:
Why are these changes needed?
Closes EGDA-1073
Currently mdbook mermaid diagrams are not being generated, and look like:
This PR fixes this, by using the mdbook-mermaid preprocessor to mdbook.
Checks