Update remark-lint config

[ThomDietrich]

Remark Lint is a remark linter and should help checking our Markdown syntax from here on out. The settings configured here check almost everything important to us / .... me. 😄

To get a quick overview, the following rules are included in that overwrite order:

• https://github.com/wooorm/remark-lint/tree/master/packages/remark-preset-lint-consistent#rules
• https://github.com/wooorm/remark-lint/tree/master/packages/remark-preset-lint-recommended#rules
• https://github.com/wooorm/remark-lint/tree/master/packages/remark-preset-lint-markdown-style-guide#rules
• "remark-lint-maximum-line-length", 240 - I chose this number as a sain compromise. Why? It's not nothing but caps at exactly two lines here on GitHub
• "remark-lint-no-missing-blank-lines" - Makes sure code blocks (and others) are surrounded by blank lines needed by jekyll
• "remark-lint-no-tabs" - sure thing
• "remark-lint-unordered-list-marker-style", "-" - The only one I might need to explain. Up to this point I've used asterisks for lists. Because of this I decided to go with "-" for our style guide. I would be interested in your opinion!

The only rule currently not in here (because it's currently broken) is the one some of you might think is the one most dear to me.

With the remark-lint settings in place I'm seeing the following:

I'll start looking into these step by step. The hardest challenge will be to unify all the Addons readmes.

While going through the articles, I'll also make sure to build a short article to aid as a style guide description.

Before I start to invest any further effort I'd be interested in your feedback. Let me know if you are unsure about one of the settings described above.

Ping @thorsten Confectrician @bgilmer77

Signed-off-by: Thomas Dietrich [email protected]

[bgilmer77]

Hi Thom, Just so I understand what this is, I am familiar with nslint for checking nameserver configurations, so I assume this is a *nix-based tool to perform a similar check against the openhab documentation. Do I understand correctly? FWIW, I am happy to chip in where I can in order to knock down the number of warnings, especially on areas of the documentation where I am actively contributing.

[ThomDietrich]

Yes more or less. With the configuration available you can run style guide checks about the way the markdown files are structured. This will avoid malformed output.

I'm using the excellent editor Atom with the linter-markdown plugin (and the markdown preview plugin). The result will for example look like this:

https://atom.io/packages/linter-markdown

Thanks for the offer! I'll contact you as soon as this PR was merged. We can divide the work. Maybe you want to combine this with a general rewrite of one of the articles. Transformations would be something...

[ThomDietrich]

I'll go ahead and merge. We can still add improvements at a later point.

[ThomDietrich]

For whom it may concern: I've added a few lines of usage hints to the file.

[Confectrician]

Hey @ThomDietrich,

Since VsCode is trending parallel to this effort here,
https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint
could be interesting too.

I have not worked with the linting feature yet, but understand the purpose behind it.
Could you test, if this is working too fpr the openhab docs, since it is using another linter engine behind the surface (?!)

[ThomDietrich]

First and foremost I'd say that one could use different editors for different tasks. Just because you can now comfortably build your openHAB config thanks to @kubawolanin, editing of docs doesn't need to happen there as well...

That said: remark/remark-lint are command line tools and plugins for a few environments are available. See: https://marketplace.visualstudio.com/items?itemName=mrmlnc.vscode-remark

[BClark09]

Always helps to have familiar tools for people who are new to the scene. Ive been using markdown mode for emacs but am keen to try out everything mentioned here!!

[ThomDietrich]

Definitely! It would be amazing if the vscode extension does the job, I've not tested it yet.

[Confectrician]

You're definitely right.
One can use more than one editor for sure.
But in my view it worth to discuss this point and maybe safe some disk space later^^

Thanks for the marketplace link.
I will try to test the extension.

[bgilmer77]

@ThomDietrich, Thank you, thank you. As someone just getting into contributing to this project, you can't imagine how helpful just a few comments on usage added to a README can be. For example, I did not realize that this could be run from the command line as well as used inside of Atom.
Personally, I live and breath VI, so using this on the command line is excellent.

[Confectrician]

Seems to work for me within VSCode with
https://marketplace.visualstudio.com/items?itemName=mrmlnc.vscode-remark

[ThomDietrich]

@Confectrician looks amazing! Does the extension use the RemarkConfig provided via package.json?
Using beautify is nice and all but be careful, remark could easily something it doesn't like mistake for something other than intended...

[Confectrician]

I have configured exactly nothing.
Just installed the extension and tested it like shown in the image.
So the remark config must have been used through the contents of package.json

I will do some further testing, but wanted to share the first impression.

[ThomDietrich]

Okay sounds like the config is not used :) That could be an issue because different settings preferences will be applied. That's not a big problem at first but would be great to eliminate.
Looking at the readme of the extension it seems to be possible. I'll have a look when the time is right.

[Confectrician]

No need to hurry.
For me it ws important to have it documented somewhere and have a place to discuss about it. :)