Add markdown examples to help style guide

Author: knolleary

_includes/header.html

@@ -15,7 +15,7 @@
 	<link href="/css/front.css?d=20200825" rel="stylesheet" media="screen">
 	<link href="/css/docs.css?d=20200825" rel="stylesheet" media="screen">
 	<link href="/css/blog.css?d=20200825" rel="stylesheet" media="screen">
-	<link href="/css/syntax.css?d=20200825" rel="stylesheet" media="screen">
+	<link href="/css/syntax.css?d=20211008" rel="stylesheet" media="screen">
 	<link type="application/atom+xml" rel="alternate" href="{{ site.url }}/feed.xml" />
 	{% if page.layout == 'blog' %}<meta name="twitter:card" content="summary" />
 	<meta name="twitter:site" content="@nodered" />

css/syntax.css

@@ -60,6 +60,6 @@
 .highlight .il { color: #ae81ff } /* Literal.Number.Integer.Long */
 
 .highlight .gh { } /* Generic Heading & Diff Header */
-.highlight .gu { color: #75715e; } /* Generic.Subheading & Diff Unified/Comment? */
+.highlight .gu { color: #efe4ac; } /* Generic.Subheading & Diff Unified/Comment? */
 .highlight .gd { color: #dc8f8f; } /* Generic.Deleted & Diff Deleted */
 .highlight .gi { color: #a6e22e; } /* Generic.Inserted & Diff Inserted */

docs/creating-nodes/help-style-guide.md

@@ -11,14 +11,17 @@ should provide the user with all the information they need in order to use the n
 The following style guide describes how the help should be structured to ensure
 a consistent appearance between nodes.
 
+*Since 2.1.0* : The help text can be provided as markdown rather than HTML. In this
+case the `type` attribute of the `<script>` tag must be `text/markdown`.
+
 <hr/>
 
 <link href="/css/node-help.css" rel="stylesheet">
 
 <div class="grid" style="min-height:auto; padding:5px 0 5px; border-bottom: 1px solid #f0f0f0;">
     <div class="col-1-2">
         This section provides a high-level introduction to the node. It should be
-        no more than 2 or 3 <code>&lt;p&gt;</code> long. The first <code>&lt;p&gt;</code>
+        no more than 2 or 3 lines long. The first line (<code>&lt;p&gt;</code>)
         is used as the tooltip when hovering over the node in the palette.
     </div>
     <div class="col-1-2 node-help" style="padding-right: 5px; background: #f9f9f9;">
@@ -106,9 +109,10 @@ a consistent appearance between nodes.
 
 <hr/>
 
-The above example was created with the following HTML.
+The above example was created with the following:.
 
-~~~~~html
+{:.code-tab-html}
+```html
 <script type="text/html" data-help-name="node-type">
 <p>Connects to a MQTT broker and publishes messages.</p>
 
@@ -153,22 +157,70 @@ The above example was created with the following HTML.
         <li><a>GitHub</a> - the nodes github repository</li>
     </ul>
 </script>
-~~~~~
+```
+
+{:.code-tab-md}
+```markdown
+<script type="text/markdown" data-help-name="node-type">
+Connects to a MQTT broker and publishes messages.
+
+### Inputs
+
+: payload (string | buffer) :  the payload of the message to publish.
+: *topic* (string)          :  the MQTT topic to publish to.
+
+
+### Outputs
+
+1. Standard output
+: payload (string) : the standard output of the command.
 
+2. Standard error
+: payload (string) : the standard error of the command.
+
+### Details
+
+`msg.payload` is used as the payload of the published message.
+If it contains an Object it will be converted to a JSON string before being sent.
+If it contains a binary Buffer the message will be published as-is.
+
+The topic used can be configured in the node or, if left blank, can be set
+`msg.topic`.
+
+Likewise the QoS and retain values can be configured in the node or, if left
+blank, set by `msg.qos` and `msg.retain` respectively.
+
+### References
+
+ - [Twitter API docs]() - full description of `msg.tweet` property
+ - [GitHub]() - the nodes github repository
+</script>
+```
 
 #### Section headers
 
 Each section must be marked up with an `<h3>` tag. If the `Details` section needs
 sub headings, they must use `<h4>` tags.
 
-~~~~~html
+{:.code-tab-html}
+```html
 <h3>Inputs</h3>
 ...
 <h3>Details</h3>
 ...
  <h4>A sub section</h4>
  ...
-~~~~~
+```
+
+{:.code-tab-md}
+```markdown
+### Inputs
+...
+### Details
+...
+#### A sub section
+...
+```
 
 #### Message properties
 
@@ -183,8 +235,8 @@ the `<dt>` should have a class attribute of `optional`.
 
 Each `<dd>` contains a brief description of the property.
 
-
-~~~~~html
+{:.code-tab-html}
+```html
 <dl class="message-properties">
     <dt>payload
         <span class="property-type">string | buffer</span>
@@ -195,7 +247,13 @@ Each `<dd>` contains a brief description of the property.
     </dt>
     <dd> the MQTT topic to publish to.</dd>
 </dl>
-~~~~~
+```
+
+{:.code-tab-md}
+```markdown
+: payload (string | buffer) :  the payload of the message to publish.
+: *topic* (string)          :  the MQTT topic to publish to.
+```
 
 #### Multiple outputs
 
@@ -209,7 +267,8 @@ by a `<dl>` message property list.
 <b>Note</b>: if the node has a single output, it should not be wrapped in such a list and
 just the `<dl>` used.
 
-~~~~~html
+{:.code-tab-html}
+```html
 <ol class="node-ports">
     <li>Standard output
         <dl class="message-properties">
@@ -224,7 +283,16 @@ just the `<dl>` used.
         </dl>
     </li>
 </ol>
-~~~~~
+```
+
+{:.code-tab-md}
+```markdown
+1. Standard output
+: payload (string) : the standard output of the command.
+
+2. Standard error
+: payload (string) : the standard error of the command.
+```
 
 
 #### General guidance
@@ -233,11 +301,66 @@ When referencing a message property outside of a message property list described
 above, they should be prefixed with `msg.` to make it clear to the reader what
 it is. They should be wrapped in `<code>` tags.
 
-~~~~~html
+{:.code-tab-html}
+```html
 The interesting part is in <code>msg.payload</code>.
-~~~~~
+```
+
+{:.code-tab-md}
+```markdown
+The interesting part is in `msg.payload`.
+```
 
 No other styling markup (e.g. `<b>`,`<i>`) should be used within the body of the help text.
 
 The help should not assume the reader is an experienced developer or deeply familiar
 with whatever the node exposes; above all, it needs to be helpful.
+
+<style>
+
+.format-button {
+    padding: 2px 8px;
+    border: 1px solid #666;
+    margin-right: 8px;
+    background: #bbb;
+}
+.format-button.active {
+    background: white;
+    pointer-events: none;
+
+}
+.code-example-switcher pre {
+    margin-top: 0;
+}
+</style>
+
+<script>
+$(function() {
+    $(".code-tab-html").each(function() {
+        let htmlBlock = $(this);
+        let mdBlock = $(this).next(".code-tab-md").hide();
+        htmlBlock.wrap("<div></div>");
+        let container = htmlBlock.parent();
+        mdBlock.appendTo(container);
+
+        container.wrap('<div class="code-example-switcher"></div>');
+        let toplevel = container.parent();
+        let toolbar = $('<div></div>').prependTo(toplevel);
+
+        let htmlButton = $('<a href="#" class="active format-button">HTML</a>').appendTo(toolbar).on("click", function(evt) {
+            evt.preventDefault();
+            mdBlock.hide();
+            htmlBlock.show();
+            htmlButton.addClass('active');
+            mdButton.removeClass('active')
+        });
+        let mdButton = $('<a href="#" class="format-button">Markdown</a>').appendTo(toolbar).on("click", function(evt) {
+            evt.preventDefault();
+            mdBlock.show();
+            htmlBlock.hide();
+            htmlButton.removeClass('active');
+            mdButton.addClass('active')
+        });
+    })
+})
+</script>