New Node: node-red-contrib-static-markdown - Now Published v0.0.14

Share Your Nodes
1

Hi all,

I've been doing a lot of work with Markdown recently and it occurred to me that Node-RED would make a nice platform for serving up a Markdown web.

So I've started to put together a new node to do that. No code yet, just getting warmed up and I need to finish off uibuilder v2. However, I thought I would share with the community to see if anyone has any feedback.

The code will be posted to: https://github.com/TotallyInformation/node-red-contrib-static-markdown

You can install it from GitHub the usual way but it doesn't actually do anything yet :slight_smile:

Here is the current README - please leave any comments and ideas in this thread if you have any.

Note that, at least to begin with, the node will not accept any inputs or have any outputs.

node-red-contrib-staticMarkdown

Serve up a folder of static markdown files from Node-RED

In the admin panel for the node instance, provide a url path and a source folder.

The source folder can contain sub-folders. Files with an extension of .md will be served as web pages.

Each folder may contain a file named index.md and if so, this will be used as the default page for that folder.

Markup

The source files can contain any valid CommonMark markup and may also contain metadata in a YAML header. e.g.

---
title: This is the title for my markdown file
---

# My markdown file

This file will be served as HTML with the help of Node-RED.

Templates

The source files folder may contain a sub-folder named .templates. If it does, it should contain a Handlebars template called default.hba.

If the .templates folder does not exist, a default template will be used.

Dependencies

  • Glob - Recursively read a directory, returning an array with all files that match an specified pattern.

  • marked - Compile Markdown to HTML.

  • front-matter - Extract meta data (front matter) from documents.

  • fs-extra - Adds new functions to Node’s native file-system module (fs) and add promise support for the existing ones.

Inspiration

3 Likes
2

I know this is going against the whole name (static) but I'd really like it if your node could provide md editing. I'm in the process of looking for a md, file based replacement for an old wiki.

I get its out of scope but if you come across something simple to weave into your node that could provide a wikilike experience, I'd be up for that.

Other thoughts...
Again, I know the title is "static" but perhaps some way of having replaceable content? To make (mostly static) content mix with dynamic content, passed in. Kinda like mustache replacements?

Another...
Will your MD to html handle special tags e.g. _TOC_ to build table of contents from Headings?

Good luck in your endeavours.

3

And going the other way... as most of those libraries are already in Node-RED, as is the ability to serve static folders, would it not make sense to just handle .md files anyway (without needing a node).

4

I'm open to suggestions :slight_smile:

This could certainly be an extension to Node-RED's existing static serving capability but I wouldn't really know where to start to make that happen. If you were to send some pointers my way though, I'd be more than happy to try and create something if you think it a worthwhile addition to Node-RED.

Yes, something I'd be more than open to. But I think that I need to get the basics right first.

Indeed, that is one of my thoughts.. At the moment, I'm using either VScode or Typora to edit md files. But the ability to run from a server, especially one as versatile as Node-RED is intriguing.

Yes, I've also thought about that. Again, I need to get the basic concept working first I think. Also, we would need to think a bit more about what dynamic content might look like in relation to markdown.

Some initial thoughts have revolved around what can be done with tools like Hugo and Jekyll. Combining data-driven content with static content is certainly interesting but I've not yet really thought that through.

Keep the ideas coming though, I think this has legs. Thanks for the ideas and input.

The more I think about it, the more I think that markdown based content is a good fit for the low-code ideology that is inherent in Node-RED.

2 Likes
5

Following Dave's lead, the editor is already reading (and editing) project README.md files and pushing html to the browser. It seems like all the necessary infrastructure is there, although possibly not in the runtime.

6

Well, I'll see if Dave & Nick want this to go into core, I'm open to the idea. In the meantime, I'll continue working on the node as I've a long way to go before anything is usable.

I would in any case be using the built-in http(s) server and the ACE editor could be pressed into service too as I already know how to do that from uibuilder v2 which has a file editor built in - albeit from the admin ui, not and end-user ui. Adding an end-user accessible ui would be a much harder ask and I'm not sure how much use the built-in libraries would be for that. I think I would have to load my own versions anyway - though npm is good at reusing packages.

7

Not having defined what "this" is - it's hard to say yes :slight_smile:
but the httpStatic config is set around line 271 of red.js in /packages/node_modules/node-red in latest dev branch. Having an extra option to enable handling .md files as markdown would not be the worst.

PS - we already have a built in markdown editor (see latest comment node) - but that is a different topic to serving pages.

8

I think that "this" would be a simple extension to serve .md files as html. Not sure whether that would need to be from a separate folder or whether it could be integrated to the current static folder setting.

There would also need to be a template which would be used to wrap around the markdown - I propose to use handlebars/mustache for that since Node-RED already uses it. My thought would be to have a default template but then to allow an optional .templates folder in the static folder that would be used for overrides allowing different visuals for different folders and files at need while keeping everything nicely together.

It would also involve the inclusion of at least 1 additional library. So probably sensible to make it an option controlled from settings.js as usual.

When I get time, I will have a play with the red.js file and see how easy it is.

I will probably continue to use the node-red-contrib-static-markdown (not a mouthful at all!) node to experiment with, will also make it easier for people to try it out.

If we can then agree on the basics, you can then consider whether you would welcome a PR or would prefer it to stay as something separate.

Even if the delivery is included in Node-RED core, there is probably still room for a separate node but that could then be focused on the editing side of things.

9

UPDATE: For those new to this thread. Please note that v0.0.14 is now published to npm and is available from the pallet manager.

The current version includes:

  • Select folder and url to use (url respects the httpNodeRoot setting). Not only are markdown files served but also other files including html, css, javascript, images, etc.
  • Uses the CommonMark standard.
  • Handlebars templating.
  • Has a number of extensions including:
    • HTML tags
    • Syntax highlighting (using Prism)
    • Table of Contents via [[toc]] tag
    • YAML frontmatter support which exposes the frontmatter fields to the Handlebars templates. You can also use this to override the template, css and Prism css used for a file.
    • A full list of included extensions is found here.

There are still things that I'd like to do and they are listed in the README file.

There are also a few further extensions I'd like to add if I can get them working:

  • Diagrams
  • TeX
  • Math expressions

Hope you find this useful, drop me a note if you do, if you have any problems or if you think of something I've missed.

For anyone following along, I've just pushed a beta to GitHub so please feel free to install from there and give it a go!

In the meantime, Dave is working on a simple markdown parsing node for use with Dashboard, etc. which will be added to the core nodes.

I believe it is likely he will also add basic markdown support into the static server available in Node-RED core. But there are other priorities right now for core.

Meanwhile this node will give you something very comprehensive should you need it.

Check out the README to see what's been implemented so far.

Some goodies yet to come include:

  • Diagrams
  • Syntax highlighting
  • HTML tags support
  • TOC support

Maybe much more. I'm using the markdown-it library and there are lots of extensions available.

Markdown editing is some way off though I'm afraid. I'm sure I'll get to it eventually though, seems like an obvious enhancement.

By the way, if you want a decent markdown file editor, Typora seems to be the best of the free tools that I've found. It has the major advantage of offering WYSIWYG editing.

2 Likes
10

So as Julian reported i have now pushed out node-red-node-markdown to the flows site / node catalogue.

It is a very simple node that accepts a markdown string on msg.payload and returns html - suitable for feeding to a ui_template node for example a simple flow.

image
image.png1258Ă—150 16.2 KB

can produce
image
image.png692Ă—1080 72.8 KB

1 Like
11

And not to be outdone! I've now pushed node-red-contrib-static-markdown@0.0.14 to GitHub and published to npm.

It should hopefully appear in the flows catalogue before too long.