Issue: I find using the help style guide (Node help style guide : Node-RED) cumbersome. It takes time to document about the node using html tags.
Ask: Since the documentation is converted into markdown anyway, is there a way I can use markdown directly within <script type="text/html" data-help-name="jwt-gen1">....?
Since the documentation is converted into markdown anyway,
No it isn't. The HTML you provide is presented as-is.
I'm fairly sure there's nothing stopping you from using raw markdown in the help. The problem being it just won't get styled properly.
The key thing with the HTML is the style guide - the specific css classes you apply to different elements so they are presented properly.
We're happy to look at suggestions to make that easier - so that the markdown gets styled properly.
Oh yes, its not converted into markdown.
Well, if I place markdown into <script type="text/html" data-help-name="jwt-gen1">... it doesnt render as markdown (obviously).
What do you mean by that?
I am thinking on the lines of using RED.utils.renderMarkdown(...) somehow, but not sure how (yet).
Any ideas?
I don't think the editor currently has any mechanism to do that.
For uibuilder, I have a user API that delivers a set of documentation separately with the help of docsify. Docsify renders markdown to html dynamically and you only need to serve it's index.html.
I'm not certain (haven't tried either) but as the nodes/flows built in markdown documenter is displayed as HTML in the side-bar there is at least a possibility (just might not be hooked up to the custom nodes documentation or might require some tag to indicate markdown)?
I do wish the tables had some styling and the code was colourised but otherwise, it is fantastic that you thought to support markdown in the node help 
But the point remains, the style guide exists to ensure a consistent format of help for users. You cannot adhere to the style guide with plain markdown.
If you are writing a node, the help isn't meant to be an inconvenience to spend time on. It's a critical part of your node and worth putting effort in for users of your node.
I'm open to suggestions for how to improve it, but don't forget why the style guide exists.
Sure. It would require custom markup parsing (i believe?) .
Totally agree (I do extensive help & try to adhere 
)
I think what might be interesting would be an easy way to have some extended documentation in the sidebar. I'd not really thought about that. I was delighted when I discovered how easy it was to serve up a docs folder containing markdown as a website accessible directly from the editor.
I would indeed be interesting to serve that straight into the sidebar. Then the current help could be left alone to give the nice formatted summary help with tons more available if the node called for it.
Totally agree with you. The documentation is v important, consistency is the key and it shoudn't be inconvenient. But you also have to agree that markdown is quicker to adopt as compared to html tags for someone like me who isnt a front end dev.
Hi Nick, marked (v2.1.0+) supports extensions.
I had a bit play and it is possible to support existing style guide. Here is 2 quick demos...
Send data via a local serial port.
### Inputs
: payload (string | buffer) : data to be sent via the serial port
: *baudrate* (string) : baudrate of the serial port (optional)
<script type="text/markdown" data-help-name="C-Mode Command">
OMRON C-Mode Command builder.
### Inputs
: payload (string | buffer) : data to be sent with the command
: *hostNumber* (string) : The host number to send this command to (optional, defaults to 00)
: *headerCode* (string) : The header code (command) to issue (optional, defaults to RR)
</script>
JSFiddle marked playground for node-red markdown
Obviously it is just a first stab but it demonstrates feasibility of using markdown for easier node documenting.
If you or anyone has a proposed markdown format/syntax I would be happy to try and massage it into the dt/dd style guide?
Do you mean you added this to the backlog? Where can I see the backlog?
No, nothing has been added to the backlog yet, but I'd be happy to see this move forward in someway.
@Steve-Mcl that looks good in principle. We just need to think through how it works in practice. For example, whether this should be applied globally to any and all markdown we render in the editor, or should it be limited to node help in some way?
Good point. Not 100% certain we can switch extensions on and off. Assuming we can, I think we would need an options object in the renderMarkdown function to indicate we want to parse the extended markup (or not).
While on this, how do you feel about adding some table style (current a markdown table renders very much un-styled and is hard to tell it is even a table) and code colourisation?
One piece at a time. If you're going to move this forward, then let's move the discussion onto GitHub. Please raise a new discussion here: node-red/designs · Discussions · GitHub
(Just be aware I'm away for a few days so responses will be limited)
I'll take a look at those things separately.
Hi Nick, Everyone.
The discussion has started here: Using markdown to document the nodes while adhering to node-red style guide · Discussion #60 · node-red/designs · GitHub
This has been very productive. Thanks all for accepting my suggestion.
Closing this topic now.
This topic was automatically closed 14 days after the last reply. New replies are no longer allowed.
Just a note for information/feedback - pull request added: Render node documentation to node-red style guide when written in markdown. by Steve-Mcl · Pull Request #3169 · node-red/node-red · GitHub
Copyright OpenJS Foundation and Node-RED contributors. All rights reserved. The OpenJS Foundation has registered trademarks and uses trademarks. For a list of trademarks of the OpenJS Foundation, please see our Trademark Policy and Trademark List. Trademarks and logos not indicated on the list of OpenJS Foundation trademarks are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.
The OpenJS Foundation | Terms of Use | Privacy Policy | OpenJS Foundation Bylaws | Trademark Policy | Trademark List | Cookie Policy