Recipe header styling and content convention

[justparking]

Hi all,

I'm discussing conventions to use within the header part of the recipe. It's at the top of recipes, supports MarkDown and is displayed when a node is viewed.

This is not about enforcement, feel free to be creative however I'm just submitting a convention which establishes some consistency when viewing simple nodes written by different people. It's about sections and the use of Markdown formatting. Some of these ideas are mine, some I've cherry picked from others.

My proposal has these sections:

1. Title
2. Revision stamp
3. Description of behaviour
4. Lists of notable features, set up instructions, cautions, etc.
5. changelog (revision history)

Here's an example below which includes the related MarkDown.

(As you probably know, the MarkDown rendering done in Nodel is slightly different from github's so this looks slightly different when browser in nodel)

**Recipe title** in a declarative manner using MarkDown formatting for emphasis

`rev 11.240410`

Optionally add anything here in plain language which describes important behaviour. Keep this short and concise.

* use a bullet list of notable features
* here's another feature
* here's a description of behavour or set up instruction

_changelog_

* _rev 11 feature: brief changelog, most recent at top, keep declaretive, not too wordy_
* _rev 10 bugfix: use keywords like bugfix, feature etc._
* _rev 7 full sentences can be avoided_
* _rev 4 revision history does not have to be complete; older entries can be rolled off; keep less than ~8 entries or so if possible_
* _rev 3 complete revision history is always available via git anyway_
* _rev 1.230114 JP created_

In Nodel it renders like this:

The revision stamp rev 11.240410 consists of an integer number as the major revision and a suffix that make up a patch number. If more than one patch is made on the same day, simply add an extra digit, e.g. rev 11.2404101. Full timestamps (include time-of-day) are not necessary and tend to cause unwieldy version stamps. As a reserved future feature, presume that these revision stamps might be parsed/intpretted by nodel as part of some kind of version management in the future.

Having the rev 1 listed in the changelog is useful.

If this discussion goes well I'd like to add it to a page on the /wiki and also update the template used when a new node is created from scratch.

[scroix]

This is more or less consistent with what I've been using for new recipes. It's been rather helpful.

[thefennecdeer]

I'd also like to propose the style of using H4 headers for Node names with superscript version numbering:

Written as:

#### **Brightsign Node** <sup>v1.2.0</sup> 

Requires the [Nodel Brightsign Plugin](https://github.com/museumsvictoria/nodel-recipes/tree/master/Brightsign)

---

Monitors state of Brightsign, and allows remote control of actions:

* Playback Control
* Muting
* Sleep

This helps draw my eye to a stronger landmark and I've had an easier time distinguishing outdated nodes

[scroix]

I like the use of the line to delineate between the recipe name and the description. You could imagine this being executed as a dropdown if the front end supported it.

But I disagree that the recipe name should be larger than the node name in the header. If I'm working across multiple nodes the thing I care about most is the unique identifier of the node I'm currently browsing.

[thefennecdeer]

ah thats a good point!