Each node in Node-RED flow can be given its description in Markdown.
Including figures in the document really help the reader to understand what the flow developer wants to describe. However, current Node-RED editor does not provide supporting mechanisms for including figures in the Markdown documents.
Therefore, I would like to propose adding the following two extensions to the Markdown editor.
This is something I've thought about in the past - I can definitely see the benefits. So apart from the extra package for the browser to download, I personally have no problem with this.
The minified dist library is about 900KB ... not exactly lightweight for something most people won't see most of the time. Are there any lighter weight alternatives ? What is the advantage of including mermaid vs standard inages ?
Mermaid is stored inline as editable text, rather than having to figure out how to inline an image.
I've found it super useful since GitHub added support for it in issues etc.
The size of the library is a bit of a concern. We may be able to do some sort of lazy loading on it, so it only gets loaded if a mermaid block is detected...
Thanks for your comments. And sorry for the late reply.
Mermaid is supported in many services and tools such as GitHub and VSCode. So I think being able to copy and paste between them is an advantage over other extension syntax.
Regarding the memory footprint of the Mermaid library, as you written, it needs to be addressed.
Mermaid supports server-side rendering with mermaid-cli, so I thought about using it. Unfortunately, it uses puppeteer and chromium internally, and there are concerns that it may not be available in some environments.
Therefore, as @knolleary suggested, it seems better to make the library loaded on demand when mermaid extension is used in markdown document. Also, it would be better to be able to select the use of mermaid rendering in setting.js.
Yes puppeteer and chromium would be even worse. (Even if serverside - when the server is a pi).
As for settings. Not sure how that helps. If a node has the markup in and the setting is off then it will render badly. I don’t think we could skip the “unknown” tags can we ?
We can control and skip rendering of unknown/unsupported tag by Marked.js used in Node-RED editor. So, if disabled in settings.js, mermaid code block is supposed to be displayed as the original code as-is.
There appear to be several online sites that render mermaid charts (e.g. mermaid.live and markdown monster)... so just thinking out load, would it be possible to pass the mermaid text to one of those online sites, and either receive an image or embed an iframe to show the diagram?
I admit I have not looked to see if it's even feasible, but that seems like a good way to avoid loading the libraries and still see the drawings.
Or perhaps a third-party contrib node (like swagger-ui) that brings it's own version of the mermaid lib to do the rendering in the browser? But then I guess you still have the challenge of what to show when that lib is not available...
I'm not finding help that often in the help pane, other than to refresh my memory about specific message properties expected by a node. I tend to use the npm or github readme to get the big picture. Why not put the diagrams there? Maybe the flow editor could be enhanced to link to or iframe the package's page from the flow library? That could be a full-page pop-over iframe so one can read the page and then go back to coding business?
This is more related to a user being able to document their own flows, rather than node help.
Given the general popularity of mermaid, I'd be wary of adopting a different library at this point. Nor would we want to introduce a dependency in an external service to do the rendered.
I don't see a compelling reason not to at least explore the feasibility with a prototype.
Oh, I see, I had completely missed the the fact that this is supposed to be for comment nodes. Then IMHO implement a contributed diagram-comment node. I mean, the NR flow editor is already 5MB+...
(This is tangential, but I'm always frustrated by the comment node. I wish it had a simple pop-up or even on-hover to display its content. Or an option to show the content right there in the flow.)
Yes, just starting to make better use of that for examples. Unfortunately, it isn't all that discoverable right now so not many people using it. What might be nice would be some kind of visual indicator in the Editor if the description tab has content (maybe just changing the colour of the icon in the node's editor panel?).
It has a lot of potential.
Certainly, I use the mermaid plugin in my Docsify tech docs for uibuilder. But that only loads the library direct from the Internet when you access the uibuilder tech docs site (either via GitHub or locally from a uibuilder node).
And for anyone like me, a bit slow, a Group can also be coloured & have a name (as mentioned in the Documentation - Documenting Flows) but what it didn't say was how to do it. So - the trick is to place the cursor over a Group boundary line and double click. (I am sure that this has been mentioned somewhere, but it flew right by me)
That would indeed save duplicating a lot of deep technical data ( albeit at the expense of having to be online to see it ), and if I understood mermaid support is already built into GitHub ?
Of course we can still try a local prototype, but adding an extra 3mb to the client seems wanton, but a good excuse to try last loading I suppose.
