JSON flows in node description README.md - how resp. howto

Developing Nodes
1

I have difficulties embedding JSON flows in the node description.

1. What do I know about JSON embedding in the markdown text?

  • JSON or javascript (and also other languages) code can be embedded into the README.md via triple backquotes ```
  • The triple backquotes (starting and ending) must be in a single line
  • I use the keyword 'javascript' at the starting to get a coloured display, e.g. when displaying a Node-RED function node contents.
    • This works at least in GitHub.com, npmjs.com and also in most Markdown-Editors
    • Example: ```javascript
    • See also there: https://github.com/windkh/node-red-contrib-telegrambot, e.g. chapter "Sending live locations"
    • Remark: Coloured output does not work on flows.nodered.org (not a big problem for me)
  • You can generate collapsed sections via the <details> option

2. Beside: What do I know about image embedding in the markdown text (important for later question)?

  • Images can be embedded, e.g. via an '!'
    • Example: ![echo flow](images/TelegramBotEcho.png?raw=true "Echo Flow")
  • These images can be seen in the flows.nodered.org, because they are embedded via this type of link: https://raw.githubusercontent.com/
    • Example: This image: https://raw.githubusercontent.com/windkh/node-red-contrib-telegrambot/master/images/TelegramBotEcho.png is embedded Fig. 1 here: https://github.com/windkh/node-red-contrib-telegrambot
  • Important: These images can also seen on the flows.nodered.org pages, e.g. there: https://flows.nodered.org/node/node-red-contrib-telegrambot

3. Beside: What do I know about JSON flow examples?

  • If you have a subdirectory named 'examples' in your flow, then JSON files located there are shown in the vertical tab 'examples' in the Node-RED importing dialog. This is a nice feature

4. What is a problem?

Embedding JSON files with a relative link in the .md file does only work in GitHub.com and npmjs.com, but not on flows.nodered.org

  • Example: See there: https://github.com/windkh/node-red-contrib-telegrambot, e.g. Fig. 1:
    grafik

  • The flow is defined by this markdown code: [**echo flow**](examples/echo.json)

  • Klicking the link 'echo flow' leads to a page where you can copy the flow text (e.g. for importing it via the clipboard).

  • Problem: On flows.nodered.org an error message occurs: 404 - Thing not found

    • The not found link is: https://flows.nodered.org/node/examples/echo.json
    • It could be (comparable to images): https://raw.githubusercontent.com/windkh/node-red-contrib-telegrambot/master/examples/echo.json

  • Question: Is there a solution for that, that flows.nodered.org treats these flow links identical like images? Any ideas?

2

The Flow Library has to do a lot of work to spot relative links and to rewrite them to use the GitHub url equivalent. It was only doing that for images - not links to other files. I've just pushed a fix to handle links - reload the page and you should find your links work as you'd want now.

1 Like
3

Brilliant. Many thanks.
Now it works.

4

@knolleary
What about adding a subpage about the README.md there?
Describe about generating the node documentation as Markdown and some of the stuff described above. I would offer to start with parts of the description.

5

@knolleary
There: How to share code or flow json you mentioned not to use the ```javascript expression for embedding code.
I thought that worked a couple of weeks ago, but not it does not work. It would be nice if the javascript syntax highlighting would be active, this is useful when you describe the contents of a function node.

For an example see https://flows.nodered.org/node/node-red-contrib-telegrambot and go to Fig. 11. Below this figure click to expand the function node contents.

6

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