# Documentation: example flows for contributed nodes

**URL:** <https://discourse.nodered.org/t/documentation-example-flows-for-contributed-nodes/44198>\
**Category:** Developing Nodes\
**Created:** [14 April 2021 20:11 UTC](https://discourse.nodered.org/t/documentation-example-flows-for-contributed-nodes/44198 "2021-04-14T20:11:31Z")\
**Posts on this page:** 7\
**Page:** 1

<div class="post-metadata">

**Author:** ![drmibell](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/drmibell/32/8424_2.png) [@drmibell](https://discourse.nodered.org/u/drmibell)\
**Post date:** [14 April 2021 20:11 UTC](https://discourse.nodered.org/t/documentation-example-flows-for-contributed-nodes/44198/1 "2021-04-14T20:11:31Z")

</div>

I like to provide example flows in the package when I publish a node, and I usually include the same example(s) in the README.md file. This has caused some difficulties lately, mainly in keeping the two copies of a flow synchronized. (There does not seem to be a way to include an external text file in a markdown file, which might be the neatest solution.) What I plan to do going forward is to omit the JSON from the README file, include a reminder that the flow can be loaded from the Import menu, and give a link to the `examples` directory on GitHub. Can anyone see a down side to this or suggest a better way to handle it?

---

<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:** [14 April 2021 20:57 UTC](https://discourse.nodered.org/t/documentation-example-flows-for-contributed-nodes/44198/2 "2021-04-14T20:57:24Z")

</div>

Hi Mike, I mostly put examples in the `examples` directory & put a message in the built in help...

![image](https://us1.discourse-cdn.com/flex026/uploads/nodered/original/3X/7/1/7121f19d82dfcb1d2c894461fc37a0f53ab98f40.png)

Also, I have attached an `onclick` to that `<a>` icon that calls `RED.actions.invoke('core:show-import-dialog');` as a quick action to get the user to the import dialog.

---

<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:** [14 April 2021 21:11 UTC](https://discourse.nodered.org/t/documentation-example-flows-for-contributed-nodes/44198/3 "2021-04-14T21:11:04Z")

</div>

I'm still working through ideas on documentation and examples as uibuilder continues to mature so I share your experiences. Here is what I have in-play at the moment though I realise that I really need to simplify things a bit.

- The examples folder contains "working" examples - ones that I know will work if the matching version is installed. Two types of example: ones that demonstrate simple concepts and ones that demonstrate complex configurations.

- The WIKI has traditionally held the uibuilder examples and this has served well but is now too large and complex to really want to continue with. Really, it needs translating to a proper website.

- The docs folder has taken on a much more important role and the discovery of `docsify` has meant that I can expose the collection of markdown files as a proper website with minimal effort. That site is now available _BOTH_ from within Node-RED and as the GitHub pages website. So you can access it both online and offline. The GitHub version showing the docs from the development version and the Node-RED version showing the docs from the installed version.

- The final part isn't live yet but I am quite excited by - but this is more uibuilder specific I think.

> [@Steve-Mcl](#):
>
> Also, I have attached an `onclick` to that `<a>` icon that calls `RED.actions.invoke('core:show-import-dialog');` as a quick action to get the user to the import dialog.

Oh, nice! I like that and will shamelessly nick it 😀

Being added to the project plan as we speak!

---

<div class="post-metadata">

**Author:** ![drmibell](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/drmibell/32/8424_2.png) [@drmibell](https://discourse.nodered.org/u/drmibell)\
**Post date:** [14 April 2021 23:12 UTC](https://discourse.nodered.org/t/documentation-example-flows-for-contributed-nodes/44198/4 "2021-04-14T23:12:38Z")

</div>

> [@Steve-Mcl](#):
>
> I have attached an `onclick` to that `<a>` icon

Very clever... and I had completely forgotten the built-in help as a place for this information. Thanks.

---

<div class="post-metadata">

**Author:** ![drmibell](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/drmibell/32/8424_2.png) [@drmibell](https://discourse.nodered.org/u/drmibell)\
**Post date:** [14 April 2021 23:33 UTC](https://discourse.nodered.org/t/documentation-example-flows-for-contributed-nodes/44198/5 "2021-04-14T23:33:41Z")

</div>

> [@TotallyInformation](#):
>
> I really need to simplify things a bit.

I doubt I will ever write anything as complex as uibuilder, but I think we have run into similar issues. The detailed documentation is most needed while the user is using Node-RED, but it is not directly accessible from inside NR. The `docsify` approach doesn't address this directly and may be over-kill for me, but it's a neat tool worth knowing about.

---

<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:** [15 April 2021 08:30 UTC](https://discourse.nodered.org/t/documentation-example-flows-for-contributed-nodes/44198/6 "2021-04-15T08:30:49Z")

</div>

> [@drmibell](#):
>
> The `docsify` approach doesn't address this directly and may be over-kill for me, but it's a neat tool worth knowing about.

In fact, making the docs available within Node-RED turned out to be really very easy. Since Node-RED already has an admin ExpressJS app server and it is accessible to you as a node author, you can simply add the docs folder as a static resource and link to the docsified index.html page. That's it, your nice docs website is now available from within Node-RED.

If you have the current version of uibuilder installed, give it a go. There is both a button in the editor config panel and a link in the help panel.

Making that folder into the GitHub website for your node is also trivial, just one of the settings in your repo.

---

<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:** [14 June 2021 08:31 UTC](https://discourse.nodered.org/t/documentation-example-flows-for-contributed-nodes/44198/7 "2021-06-14T08:31:27Z")

</div>

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