[General Documentation] Could/Should we add a markdownlint config?

[Confectrician]

I am working with markdownlint in the docs repository for a while now, to get some consistency into the docs writing.
It is configured via yaml file and runs as GitHub Action for Pull Requests and commits to the main branch and can also be executed while developing locally.

Currently i am working on a pull request to update several docs files, to get consistent contents and the number of errors is pretty big after running the linter locally for the first time.
Maybe it could be useful to share the docs linting config here too and get the ability to lint doc contributions directly.

I am planning to make linting updates from time to time after getting a defined status now on the first run.
Anyway it's alway nice if the incoming quality can be checked already in an early state and a proper linting is way better than tons of (boring) rule files nobody wants to read anyway.
(That's at least my impression from working with it for a while now.)

I can copy the config into the addons repository if @openhab/add-ons-maintainers are interested in adding it here. 🙂
And of course i would take care of keeping it in sync with the docs, if any changes are made.

[wborn]

It might save time on reviewing and rework too if the linter also gives feedback on pull requests. Do you also plan on configuring a GHA workflow that runs the linter in the openhab-docs repo?

[Confectrician]

Can you clarify this?
A GHA workflo that runs in th edocs repo when an addon pr is created?
Or am i getting this wrong now?

[wborn]

I meant using a GHA workflow in both the docs/addons repo that checks the Markdown in PRs using "GitHub Super-Linter Action" and/or "GitHub Actions problem matcher for markdownlint-cli", see Related/GitHub.

If that works well we won't have to spend time on manually adding review comments for linting issues in the Markdown and you won't have to create big PRs like #13859/#13866 every now and then to fix the linting issues. 😉

[Confectrician]

Ah ok, then i missunderstood it a bit.

Yes, that would be suitable.
I am already using markdownlint for PRs, but will have a look at superlinter.
Mayber we can get some more useful output out of it.

every now and then to fix the linting issues

Would be ok for me to not have to do this manully. 😄
Anyway we will need some effort to bring it on a usable base for a linting automation.

I would like to not force regular contributors to adapt like 60 to 70% of the current readme files.
So the inital work can failry be done by me, who knows/defines the rules.

[wborn]

Perhaps we could also use the Markdown formatter in Spotless. It is based on flexmark which is also used in the SAT MarkdownCheck.

Flexmark also has several formatting options but unfortunatly currently it is not yet possible to configure the formatting options in Spotless (see docs).

I gave it a try by adding the config (9d2bc5e) to see what the results are (f9ab88a). I think with the right config options it could save a lot of time. It is also nice that it can format tables. 🙂

[lsiepel]

Perhaps we could also use the Markdown formatter in Spotless. It is based on flexmark which is also used in the SAT MarkdownCheck.

Flexmark also has several formatting options but unfortunatly currently it is not yet possible to configure the formatting options in Spotless (see docs).

I gave it a try by adding the config (9d2bc5e) to see what the results are (f9ab88a). I think with the right config options it could save a lot of time. It is also nice that it can format tables. 🙂

@Confectrician it would be greatly appreciated if you can assist in determining the right options. Together we managed to fix many documentation issues in the past year and it would be nice to perpetuate.
Especially with new contributions alot of time is 'wasted' by going back and forth to the documentation formatting. Let me know if i can do anything to move this forward.