Using markdown to document the nodes while adhering to node-red style guide

[Steve-Mcl]

Request

As raised by mannharleen in the forum...

I find using the help style guide (Node help style guide : Node-RED 5) cumbersome. It takes time to document about the node using html tags.

Additional info

Node documentation already supports markdown documentation via a script tag with type attribute set to "text/markdown"...

<script type="text/markdown" data-help-name="my-node">
  Short description of my-node
  ### Inputs
  payload  (string)  the text to convert
</script>

...however, there is currently no means of styling the markdown to node-red documentation style guildlines.

Proposed Solution

• Add a custom marked extensions to convert markup from markdown text to generate HTML that adheres to the Node help style guide
• The markup should be kept simple to leave un-rendered markdown human readable

Proposed markup

<script type="text/markdown" data-help-name="my-node">
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)  

### Outputs

1. Standard output  
:   payload   (string | buffer) :  the standard output of the command.  
:   rc        (object)          :  exec mode only, a copy of the return code object (also available on port 3)  

2. Standard Error  
:   payload   (string)          :  the standard error of the command.  
:   rc        (object)          :  exec mode only, a copy of the return code object (also available on port 3)  
</script>

Result before custom extensions...

Result after custom extensions...

Issues / Hurdles

• marked adds a <p> to ordered lists. This causes the text after a number in the numbered list to be on a new line. To fix this, a new style rule is required...

.red-ui-help ol.node-ports p {
    display: inline;
}

• There is no obvious way to enable/disable extensions. A workaround is to use a boolean flag enableExtensions in the custom extensions callbacks and return tokens/renderings based on its state.

Working demo

http://jsfiddle.net/4uwfeb6n/6/

Additional

Tables are currently rendered with very little style making them hard to read. This proposal would also like to include CSS for node-help tables...

Markdown (standard table syntax)...

|msg property | description                                                 |
|------------:|:------------------------------------------------------------|
| stopbits    | set `msg.stopbits` to change stop bits                      |
| parity      | set `msg.parity` to change parity                           |
| options     | a JSON object containing extra options (see example below)  |

Current rendering of table in node-red help side-bar...

With proposed CSS...

.red-ui-help table {
  border-collapse: collapse;
  margin: 8px 0 8px 0;
  min-width: 300px;
  box-shadow: 0 0 2px rgb(0 0 0 / 15%);
  overflow: hidden;
  border-radius: 4px;
}

.red-ui-help table thead tr {
  background-color: #555;
  color: #ffffff;
  text-align: left;
}

.red-ui-help table th,
.red-ui-help table td {
  padding: 6px 8px;
}

.red-ui-help table tbody tr {
  border-bottom: 1px solid #dddddd;
}

.red-ui-help table tbody tr:nth-of-type(even) {
  background-color: #f3f3f3;
}

.red-ui-help table tbody tr:last-of-type {
  border-bottom: 2px solid #555;
}

[TotallyInformation]

Like it 😊

Will it be possible to break into html as well if needed?

[Steve-Mcl]

@TotallyInformation I didn't fully test whether all embedded html works but I did some and it did render correctly. Give the jsfiddle a go.

[knolleary]

Will it be possible to break into html as well if needed?

It's just same as the existing parsing of a node/flows description in the sidebar. So you can try it out there.

[Steve-Mcl]

@knolleary what are you thoughts on this making its way into 2.1? Is there time?

Regarding the question about enabling/disabling/globally applied to markdown, I think the syntax is sufficiently specific (see example below) as to not be stumbled upon by accident. Also, as we would want this to work in the node description markdown, there are not may other places this would cause a problem

example...
: var_name (type) : desc_desc_desc
...Any deviation from this and the tokenising does not occur.

[knolleary]

If you can get it into a PR we can review the specifics there.

[Steve-Mcl]

If you can get it into a PR we can review the specifics there.

PR Here