# Using markdown directly to document the nodes

**URL:** <https://discourse.nodered.org/t/using-markdown-directly-to-document-the-nodes/49592>\
**Category:** Developing Nodes\
**Created:** [11 August 2021 04:42 UTC](https://discourse.nodered.org/t/using-markdown-directly-to-document-the-nodes/49592 "2021-08-11T04:42:38Z")\
**Posts on this page:** 20\
**Page:** 1

<div class="post-metadata">

**Author:** ![mannharleen](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/mannharleen/32/25594_2.png) [@mannharleen](https://discourse.nodered.org/u/mannharleen)\
**Post date:** [11 August 2021 04:42 UTC](https://discourse.nodered.org/t/using-markdown-directly-to-document-the-nodes/49592/1 "2021-08-11T04:42:38Z")

</div>

Issue: I find using the help style guide ([Node help style guide : Node-RED](https://nodered.org/docs/creating-nodes/help-style-guide)) 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">....`?

---

<div class="post-metadata">

**Author:** ![knolleary](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/knolleary/32/3_2.png) [@knolleary](https://discourse.nodered.org/u/knolleary)\
**Post date:** [11 August 2021 08:22 UTC](https://discourse.nodered.org/t/using-markdown-directly-to-document-the-nodes/49592/2 "2021-08-11T08:22:04Z")

</div>

> 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.

---

<div class="post-metadata">

**Author:** ![mannharleen](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/mannharleen/32/25594_2.png) [@mannharleen](https://discourse.nodered.org/u/mannharleen)\
**Post date:** [11 August 2021 10:48 UTC](https://discourse.nodered.org/t/using-markdown-directly-to-document-the-nodes/49592/3 "2021-08-11T10:48:48Z")

</div>

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).

> [@knolleary](#):
>
> I'm fairly sure there's nothing stopping you from using raw markdown in the help

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?

---

<div class="post-metadata">

**Author:** ![TotallyInformation](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/totallyinformation/32/31_2.png) [@TotallyInformation](https://discourse.nodered.org/u/TotallyInformation)\
**Post date:** [12 August 2021 01:31 UTC](https://discourse.nodered.org/t/using-markdown-directly-to-document-the-nodes/49592/4 "2021-08-12T01:31:47Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![Steve-Mcl](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/steve-mcl/32/4826_2.png) [@Steve-Mcl](https://discourse.nodered.org/u/Steve-Mcl)\
**Post date:** [12 August 2021 06:55 UTC](https://discourse.nodered.org/t/using-markdown-directly-to-document-the-nodes/49592/5 "2021-08-12T06:55:11Z")

</div>

> [@TotallyInformation](#):
>
> I don't think the editor currently has any mechanism to do that.

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)?

---

<div class="post-metadata">

**Author:** ![Steve-Mcl](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/steve-mcl/32/4826_2.png) [@Steve-Mcl](https://discourse.nodered.org/u/Steve-Mcl)\
**Post date:** [12 August 2021 07:17 UTC](https://discourse.nodered.org/t/using-markdown-directly-to-document-the-nodes/49592/6 "2021-08-12T07:17:37Z")

</div>

> [@Steve-Mcl](#):
>
> or might require some tag to indicate markdown

### And as if by magic 🧙

Custom node code...

 ![image](https://us1.discourse-cdn.com/flex026/uploads/nodered/original/3X/3/6/368bfba8d42a9296dd1270fecb0120f699500029.png)

The result...  
 ![RO5R2RTKQM](https://us1.discourse-cdn.com/flex026/uploads/nodered/original/3X/c/9/c91f8034a05f097cc430930ff37a8a720ae55c75.gif)

---

<div class="post-metadata">

**Author:** ![Steve-Mcl](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/steve-mcl/32/4826_2.png) [@Steve-Mcl](https://discourse.nodered.org/u/Steve-Mcl)\
**Post date:** [12 August 2021 07:20 UTC](https://discourse.nodered.org/t/using-markdown-directly-to-document-the-nodes/49592/7 "2021-08-12T07:20:47Z")

</div>

> [@knolleary](#):
>
> We're happy to look at suggestions to make that easier - so that the markdown gets styled properly.

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 🙂

---

<div class="post-metadata">

**Author:** ![knolleary](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/knolleary/32/3_2.png) [@knolleary](https://discourse.nodered.org/u/knolleary)\
**Post date:** [12 August 2021 07:23 UTC](https://discourse.nodered.org/t/using-markdown-directly-to-document-the-nodes/49592/8 "2021-08-12T07:23:08Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![Steve-Mcl](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/steve-mcl/32/4826_2.png) [@Steve-Mcl](https://discourse.nodered.org/u/Steve-Mcl)\
**Post date:** [12 August 2021 07:26 UTC](https://discourse.nodered.org/t/using-markdown-directly-to-document-the-nodes/49592/9 "2021-08-12T07:26:32Z")

</div>

> [@knolleary](#):
>
> You cannot adhere to the style guide with plain markdown.

Sure. It would require custom markup parsing (i believe?) .

> [@knolleary](#):
>
> If you are writing a node, the help isn't meant to be an inconvenience to spend time on

Totally agree (I do extensive help & _try_ to adhere 😉 )

---

<div class="post-metadata">

**Author:** ![TotallyInformation](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/totallyinformation/32/31_2.png) [@TotallyInformation](https://discourse.nodered.org/u/TotallyInformation)\
**Post date:** [12 August 2021 14:31 UTC](https://discourse.nodered.org/t/using-markdown-directly-to-document-the-nodes/49592/10 "2021-08-12T14:31:33Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![mannharleen](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/mannharleen/32/25594_2.png) [@mannharleen](https://discourse.nodered.org/u/mannharleen)\
**Post date:** [12 August 2021 23:34 UTC](https://discourse.nodered.org/t/using-markdown-directly-to-document-the-nodes/49592/11 "2021-08-12T23:34:07Z")

</div>

> [@knolleary](#):
>
> the help isn't meant to be an inconvenience to spend time on

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.

---

<div class="post-metadata">

**Author:** ![Steve-Mcl](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/steve-mcl/32/4826_2.png) [@Steve-Mcl](https://discourse.nodered.org/u/Steve-Mcl)\
**Post date:** [15 August 2021 07:49 UTC](https://discourse.nodered.org/t/using-markdown-directly-to-document-the-nodes/49592/12 "2021-08-15T07:49:37Z")

</div>

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...

#### The markdown entered in function node description...

```auto
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)

```

#### The rendered html...

 ![image](https://us1.discourse-cdn.com/flex026/uploads/nodered/original/3X/2/c/2cd96f8b0fdbc56ea93463940e25e799397980e1.png)

#### The markdown entered in custom nodes HTML file...

```html
<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>

```

#### The rendered html...

 ![image](https://us1.discourse-cdn.com/flex026/uploads/nodered/original/3X/9/6/96eb6f2834b3b7a64ad9d60c0c4af3d33205dc23.png)

#### A playground...

[JSFiddle marked playground for node-red markdown](http://jsfiddle.net/r5wvpeLo/)

* * *

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?

---

<div class="post-metadata">

**Author:** ![mannharleen](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/mannharleen/32/25594_2.png) [@mannharleen](https://discourse.nodered.org/u/mannharleen)\
**Post date:** [18 August 2021 06:08 UTC](https://discourse.nodered.org/t/using-markdown-directly-to-document-the-nodes/49592/13 "2021-08-18T06:08:55Z")

</div>

> [@Steve-Mcl](#):
>
> marked (v2.1.0+) supports extensions.

Do you mean you added this to the backlog? Where can I see the backlog?

---

<div class="post-metadata">

**Author:** ![knolleary](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/knolleary/32/3_2.png) [@knolleary](https://discourse.nodered.org/u/knolleary)\
**Post date:** [18 August 2021 08:07 UTC](https://discourse.nodered.org/t/using-markdown-directly-to-document-the-nodes/49592/14 "2021-08-18T08:07:08Z")

</div>

> [@mannharleen](#):
>
> Do you mean you added this to 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?

---

<div class="post-metadata">

**Author:** ![Steve-Mcl](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/steve-mcl/32/4826_2.png) [@Steve-Mcl](https://discourse.nodered.org/u/Steve-Mcl)\
**Post date:** [18 August 2021 17:58 UTC](https://discourse.nodered.org/t/using-markdown-directly-to-document-the-nodes/49592/15 "2021-08-18T17:58:27Z")

</div>

> [@knolleary](#):
>
> 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?

---

<div class="post-metadata">

**Author:** ![knolleary](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/knolleary/32/3_2.png) [@knolleary](https://discourse.nodered.org/u/knolleary)\
**Post date:** [18 August 2021 18:39 UTC](https://discourse.nodered.org/t/using-markdown-directly-to-document-the-nodes/49592/16 "2021-08-18T18:39:20Z")

</div>

> [@Steve-Mcl](#):
>
> 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).

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](https://github.com/node-red/designs/discussions)

(Just be aware I'm away for a few days so responses will be limited)

> [@Steve-Mcl](#):
>
> 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?

I'll take a look at those things separately.

---

<div class="post-metadata">

**Author:** ![Steve-Mcl](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/steve-mcl/32/4826_2.png) [@Steve-Mcl](https://discourse.nodered.org/u/Steve-Mcl)\
**Post date:** [21 August 2021 16:04 UTC](https://discourse.nodered.org/t/using-markdown-directly-to-document-the-nodes/49592/17 "2021-08-21T16:04:41Z")

</div>

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](https://github.com/node-red/designs/discussions/60)

---

<div class="post-metadata">

**Author:** ![mannharleen](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/mannharleen/32/25594_2.png) [@mannharleen](https://discourse.nodered.org/u/mannharleen)\
**Post date:** [22 August 2021 00:53 UTC](https://discourse.nodered.org/t/using-markdown-directly-to-document-the-nodes/49592/18 "2021-08-22T00:53:43Z")

</div>

This has been very productive. Thanks all for accepting my suggestion.  
Closing this topic now.

---

<div class="post-metadata">

**Author:** ![system](https://us1.discourse-cdn.com/flex026/uploads/nodered/original/1X/d073cd938eafa2e558d7c2cd59003b3ef4963033.png) [@system](https://discourse.nodered.org/u/system)\
**Post date:** [5 September 2021 00:54 UTC](https://discourse.nodered.org/t/using-markdown-directly-to-document-the-nodes/49592/19 "2021-09-05T00:54:37Z")

</div>

This topic was automatically closed 14 days after the last reply. New replies are no longer allowed.

---

<div class="post-metadata">

**Author:** ![Steve-Mcl](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/steve-mcl/32/4826_2.png) [@Steve-Mcl](https://discourse.nodered.org/u/Steve-Mcl)\
**Post date:** [4 October 2021 22:12 UTC](https://discourse.nodered.org/t/using-markdown-directly-to-document-the-nodes/49592/20 "2021-10-04T22:12:03Z")

</div>

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](https://github.com/node-red/node-red/pull/3169)