node-red-contrib-markdown-note 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ted Lanham
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,53 @@
+# Node-RED Markdown Note
+
+[![NPM Version](https://img.shields.io/npm/v/node-red-contrib-markdown-note.svg)](https://www.npmjs.com/package/node-red-contrib-markdown-note)
+[![Downloads](https://img.shields.io/npm/dt/node-red-contrib-markdown-note.svg)](https://www.npmjs.com/package/node-red-contrib-markdown-note)
+[![License](https://img.shields.io/npm/l/node-red-contrib-markdown-note.svg)](LICENSE)
+
+A Node-RED node for adding **Markdown-formatted notes** directly on the flow canvas.  
+Designed for inline documentation, design notes, and contextual explanations that remain visible while editing or reviewing flows.
+
+![Node Preview](screenshots/hero.png)
+
+---
+
+## Why use Markdown Note?
+
+The standard Comment node hides content by default. Markdown Note keeps your notes **always visible**, making it easier to:
+
+- Document flow logic inline  
+- Highlight important information  
+- Include structured content with headings, lists, and code blocks  
+
+| Feature | Comment Node | Markdown Note |
+|---------|-------------|---------------|
+| Visibility | Collapsed by default | Always visible |
+| Formatting | Plain text | Markdown (headers, lists, code, blockquotes) |
+| Structure | Minimal | Suitable for detailed documentation |
+
+---
+
+## Features
+
+- **Always-visible notes** – No need to click to expand.  
+- **Markdown rendering** – Support for headers, lists, emphasis, code blocks, quotes.  
+- **Task lists** – Track TODOs or action items inline.  
+- **Resizable & readable layout** – Automatically adjusts to content size.  
+- **Developer-focused** – Document payload formats, API contracts, assumptions, or edge cases directly on the flow.  
+
+---
+
+
+## Known Issues
+
+- **Links are not clickable**: Due to Node-RED's security restrictions on SVG content in the flow editor, hyperlinks rendered in the markdown cannot be clicked.
+- **Visual jump on edit**: When closing the edit dialog, the node may appear slightly displaced or "jump" until you click away (deselect the node). This is a rendering artifact of the flow editor's redraw cycle.
+
+---
+
+## Installation
+
+Run this in your Node-RED user directory (`~/.node-red`):
+
+```bash
+npm install node-red-contrib-markdown-note

package/markdown.html

@@ -0,0 +1,361 @@
+<script type="text/javascript">
+  RED.nodes.registerType("note", {
+    category: "common",
+    color: "#F3E5AB",
+    defaults: {
+      content: { value: "" },
+    },
+    inputs: 0,
+    outputs: 0,
+    icon: "font-awesome/fa-file-text-o",
+    label: function () {
+      // Convert actual newlines to literal \n that Node-RED interprets as line breaks
+      if (this.content) {
+        return this.content.replace(/\n/g, "\\n ");
+      }
+      return "note";
+    },
+
+    oneditprepare: function () {
+      var content = this.content || "";
+
+      // Capture top-left anchor position before editing
+      // This ensures the node stays in place after edits
+      if (
+        this._noteTopY === undefined &&
+        this.y !== undefined &&
+        this.h !== undefined
+      ) {
+        this._noteTopY = this.y - this.h / 2;
+        this._noteLastY = this.y;
+      }
+
+      // Create the ACE editor with markdown mode
+      this.editor = RED.editor.createEditor({
+        id: "node-input-content-editor",
+        mode: "ace/mode/markdown",
+        value: content,
+      });
+
+      this.editor.focus();
+    },
+    oneditsave: function () {
+      this.content = this.editor.getValue();
+      $("#node-input-content").val(this.content);
+      this.editor.destroy();
+      delete this.editor;
+
+      // Reposition node after Node-RED finishes its layout
+      var node = this;
+      if (node._noteTopY !== undefined) {
+        setTimeout(function () {
+          // Re-render to get correct height
+          renderNoteNode(node);
+
+          // Anchor top edge
+          if (node.h !== undefined) {
+            node.y = node._noteTopY + node.h / 2;
+            node._noteLastY = node.y;
+            RED.view.redraw(true);
+          }
+        }, 0);
+      }
+    },
+    oneditcancel: function () {
+      this.editor.destroy();
+      delete this.editor;
+    },
+    oneditresize: function (size) {
+      var rows = $("#dialog-form>div:not(.node-text-editor-row)");
+      var height = $("#dialog-form").height();
+      for (var i = 0; i < rows.length; i++) {
+        height -= $(rows[i]).outerHeight(true);
+      }
+      var editorRow = $("#dialog-form>div.node-text-editor-row");
+      height -=
+        parseInt(editorRow.css("marginTop")) +
+        parseInt(editorRow.css("marginBottom"));
+      $(".node-text-editor").css("height", height + "px");
+      this.editor.resize();
+    },
+  });
+
+  // Render markdown content inside nodes on the workspace
+  RED.events.on("nodes:add", function (node) {
+    if (node.type === "note") {
+      setTimeout(function () {
+        renderNoteNode(node);
+      }, 100);
+    }
+  });
+
+  RED.events.on("nodes:change", function (node) {
+    if (node.type === "note") {
+      // Delay to allow Node-RED to recalculate size
+      setTimeout(function () {
+        renderNoteNode(node);
+      }, 100);
+    }
+  });
+
+  RED.events.on("view:redraw", function () {
+    // Single redraw after view settles
+    setTimeout(function () {
+      RED.nodes.eachNode(function (node) {
+        if (node.type === "note") {
+          renderNoteNode(node);
+        }
+      });
+    }, 100);
+  });
+
+  function renderNoteNode(node) {
+    var nodeEl = document.getElementById(node.id);
+    if (!nodeEl) return;
+
+    var g = d3.select(nodeEl);
+
+    // Clear any previous custom content FIRST
+    g.selectAll(".note-overlay").remove();
+
+    // CSS-BASED HIDING: Apply class to parent group
+    g.classed("note-hidden-content", true);
+
+    // Get the node's main rect to determine size
+    var rect = g.select("rect.node");
+    // Fallback if class .node doesn't exist
+    if (rect.empty()) rect = g.select("rect");
+    if (rect.empty()) return;
+
+    var bbox = rect.node().getBBox();
+    var w = bbox.width;
+    var h = bbox.height;
+
+    // INSET: Render overlay slightly smaller than rect to reveal the border stroke
+    // Node-RED standard nodes have rounded corners.
+    // By insetting 1px, we sit "inside" the stroke.
+    var inset = 1;
+
+    // Pre-process content: convert single newlines to markdown line breaks
+    // In markdown, single \n doesn't create a line break - need "  \n" (two spaces + newline)
+    //
+    // We also need to preserve blank lines intentionally entered.
+    // Standard markdown often collapses consecutive blank lines.
+    // We replace empty or whitespace-only lines with a Non-Breaking Space (\u00A0).
+    // This forces the renderer to draw a line of height, which in turn
+    // allows the node to resize correctly for "visual" blank space.
+
+    var rawContent = node.content || "";
+
+    // Sanitize FIRST so we don't accidentally escape our injection or leave an opening for injection
+    var sanitized = RED.utils.sanitize(rawContent);
+
+    // Split into lines
+    var lines = sanitized.split("\n");
+
+    // Process each line: if empty/whitespace, replace with &nbsp; (unicode \u00A0)
+    var processedLines = lines.map(function (line) {
+      if (!line.trim()) {
+        return "\u00A0";
+      }
+      return line;
+    });
+
+    // Join back with markdown hard break (space space newline)
+    var finalMarkdown = processedLines.join("  \n");
+
+    // Render markdown to HTML
+    var html = RED.utils.renderMarkdown(finalMarkdown);
+
+    // Create foreignObject to hold the HTML content
+    var fo = g
+      .append("foreignObject")
+      .attr("class", "note-overlay")
+      .attr("x", inset)
+      .attr("y", inset)
+      .attr("width", w - inset * 2)
+      .attr("height", h - inset * 2)
+      .attr("pointer-events", "none");
+
+    var contentDiv = fo
+      .append("xhtml:div")
+      .attr("class", "note-node-content")
+      .attr("xmlns", "http://www.w3.org/1999/xhtml")
+      .style("width", w - inset * 2 + "px")
+      .style("overflow", "hidden")
+      .html(html);
+
+    // Measure actual content height and resize node to fit
+    var contentNode = contentDiv.node();
+    if (contentNode) {
+      // Minimum height of one line (14px font * 1.5 line-height + padding)
+      var minHeight = 28;
+      var actualHeight = Math.max(
+        contentNode.scrollHeight + inset * 2,
+        minHeight,
+      );
+
+      // Use the smaller of Node-RED's allocation or our measured height
+      // SNAP TO GRID: Round up to nearest 40px (double grid size)
+      // Node-RED nodes align to center.
+      // Height 20px (1 unit) -> top edge is at -10px (mid-grid).
+      // Height 40px (2 units) -> top edge is at -20px (on-grid).
+      // To ensure consistent edge alignment, we enforce 40px increments.
+      var snappedHeight = Math.ceil(actualHeight / 40) * 40;
+
+      // We use snappedHeight directly to allow expansion beyond initial 'h'
+      var finalHeight = Math.max(snappedHeight, Math.ceil(minHeight / 40) * 40);
+
+      // Track top edge position to anchor the node
+      // If this is first render OR user has moved the node, recalculate anchor
+      var currentTopY = node.y - h / 2;
+      if (node._noteTopY === undefined || node._noteLastY === undefined) {
+        // First time: store current top edge as anchor
+        node._noteTopY = currentTopY;
+      } else if (Math.abs(node.y - node._noteLastY) > 1) {
+        // User moved the node - update anchor
+        node._noteTopY = currentTopY;
+      }
+
+      // Set y so top edge stays at _noteTopY
+      var newY = node._noteTopY + finalHeight / 2;
+      node.y = newY;
+      node._noteLastY = newY;
+
+      rect.attr("height", finalHeight);
+      fo.attr("height", finalHeight - inset * 2);
+      contentDiv.style("height", finalHeight - inset * 2 + "px");
+
+      // Update Node-RED's internal dimensions
+      node.h = finalHeight;
+    }
+  }
+</script>
+
+<script type="text/html" data-template-name="note">
+  <div class="form-row node-text-editor-row">
+    <input type="hidden" id="node-input-content" />
+    <div
+      style="height: 250px; min-height:150px;"
+      class="node-text-editor"
+      id="node-input-content-editor"
+    ></div>
+  </div>
+</script>
+
+<script type="text/html" data-help-name="note">
+  <p>A node for displaying markdown-formatted notes in your flow.</p>
+  <h3>Usage</h3>
+  <p>
+    Use this node to add documentation, instructions, or annotations directly in
+    your Node-RED flows.
+  </p>
+  <p>
+    Double-click to edit. Use the toolbar buttons or type markdown syntax
+    directly:
+  </p>
+  <ul>
+    <li><b>Headers:</b> # H1, ## H2, ### H3</li>
+    <li><b>Bold:</b> **text**</li>
+    <li><b>Italic:</b> _text_</li>
+    <li><b>Code:</b> `code`</li>
+    <li><b>Lists:</b> - item or 1. item</li>
+    <li><b>Links:</b> [text](url)</li>
+    <li><b>Quote:</b> > text</li>
+  </ul>
+
+</script>
+
+<style>
+  /* Markdown content rendered inside the node */
+  .note-node-content {
+    font-size: 14px;
+    line-height: 1.5;
+    color: #333;
+    font-family:
+      -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+    padding: 0 8px;
+    background: #f3e5ab;
+    border-radius: 4px;
+  }
+
+  .note-node-content h1 {
+    font-size: 18px;
+    font-weight: bold;
+    margin: 0 0 8px 0;
+    border-bottom: 1px solid #ccc;
+    padding-bottom: 4px;
+  }
+
+  .note-node-content h2 {
+    font-size: 16px;
+    font-weight: bold;
+    margin: 8px 0 6px 0;
+  }
+
+  .note-node-content h3 {
+    font-size: 15px;
+    font-weight: bold;
+    margin: 6px 0 4px 0;
+  }
+
+  .note-node-content p {
+    margin: 4px 0;
+  }
+
+  .note-node-content ul,
+  .note-node-content ol {
+    margin: 4px 0;
+    padding-left: 18px;
+  }
+
+  .note-node-content li {
+    margin: 2px 0;
+  }
+
+  .note-node-content code {
+    background: rgba(0, 0, 0, 0.08);
+    padding: 2px 5px;
+    border-radius: 2px;
+    font-family: monospace;
+    font-size: 13px;
+  }
+
+  .note-node-content pre {
+    background: rgba(0, 0, 0, 0.08);
+    padding: 3px;
+    border-radius: 2px;
+    overflow-x: auto;
+    margin: 2px 0;
+  }
+
+  .note-node-content pre code {
+    background: none;
+    padding: 0;
+  }
+
+  .note-node-content a {
+    color: #0066cc;
+    text-decoration: underline;
+  }
+
+  .note-node-content blockquote {
+    border-left: 2px solid #ccc;
+    margin: 2px 0;
+    padding-left: 6px;
+    color: #666;
+    font-style: italic;
+  }
+
+  /*
+       CSS Hiding Logic for Sticky Note
+       Hide Node-RED's default label text, icons, etc.
+    */
+  g.note-hidden-content text,
+  g.note-hidden-content .node_icon_group,
+  g.note-hidden-content .node_icon,
+  g.note-hidden-content image {
+    display: none !important;
+    visibility: hidden !important;
+  }
+</style>

package/markdown.js

@@ -0,0 +1,7 @@
+module.exports = function(RED) {
+    function NoteNode(config) {
+        RED.nodes.createNode(this, config);
+        // UI-only node - no message processing
+    }
+    RED.nodes.registerType("note", NoteNode);
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "node-red-contrib-markdown-note",
+  "version": "1.0.0",
+  "description": "A Node-RED node for displaying markdown notes as annotations",
+  "keywords": [
+    "node-red",
+    "markdown",
+    "note",
+    "comment",
+    "annotation",
+    "documentation"
+  ],
+  "author": "Ted Lanham <tedlanham@gmail.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/Backroads4Me/node-red-contrib-markdown-note",
+  "bugs": {
+    "url": "https://github.com/Backroads4Me/node-red-contrib-markdown-note/issues"
+  },
+  "main": "markdown.js",
+  "files": [
+    "markdown.js",
+    "markdown.html",
+    "package.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "node-red": {
+    "version": ">=3.0.0",
+    "nodes": {
+      "note": "markdown.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Backroads4Me/node-red-contrib-markdown-note.git"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}