Improve markdown linter; Optimize for human time vs brittle manual markdown formatting.

[bwplotka]

Hello 👋🏽

I like the fact that this project has a markdown linter that enforces some consistent styling. We do that in projects we maintain e.g Thanos (e.g here). However, I think there is some room to improve. As an author of the proposal or some markdown document, I want to focus on the content, not on formatting. Yet I literally spent ~2h in a total of my time on fixing my proposal #866 formatting (not mentioning context switches). I think that's not the smartest way to spend my paid work time, and I think there are alternatives that will minimize human time but enforce good styling which is aiming to improve maintenance and readability.

Let's enumerate why I had to spend so much time (and my PR at the time of writing is still failing #866):

• Linter is giving me only snippets of errors, not all the errors (or I cannot use the output), this means I have to push and check if it passes to learn there is a bunch of errors in another place.
• Almost 99% of errors I fixed was arguably useful. Things like:
  • Line length does not matter these days. Most editors can wrap lines on certain width and markdown format does not care either.
  • Why do spaces inside linked item matters? or code spans?
  • Language in code spans having to be specified is also a bit too strict

Anyway, those are just opinions, but there is something that will satisfy everyone. If we lint on some problem, why not.. fixing this automatically?

Proposal

1. Introduce a proper markdown formatter that fixes all problems and produces formatted markdown or fails if it cannot fix it.
2. Run it in CI, if produced output by formatter is different then what was committed then fail. If formatter fails, fail.
3. Allow users easily install and run formatter without extra configuration

We did that in https://github.com/bwplotka/mdox if we want to use it here too. Just run mdox fmt of mdox fmt --check if we want to validate if things are formatted.

We use https://github.com/Kunde21/markdownfmt internally.

Hope that will help future designers and authors of markdown in this project (:

[openshift-bot]

Inactive enhancement proposals go stale after 28d of inactivity.

See https://github.com/openshift/enhancements#life-cycle for details.

Mark the proposal as fresh by commenting /remove-lifecycle stale.
Stale proposals rot after an additional 30d of inactivity and eventually close.
Exclude this proposal from closing by commenting /lifecycle frozen.

If this proposal is safe to close now please do so with /close.

/lifecycle stale

[openshift-bot]

Stale enhancement proposals rot after 7d of inactivity.

See https://github.com/openshift/enhancements#life-cycle for details.

Mark the proposal as fresh by commenting /remove-lifecycle rotten.
Rotten proposals close after an additional 7d of inactivity.
Exclude this proposal from closing by commenting /lifecycle frozen.

If this proposal is safe to close now please do so with /close.

/lifecycle rotten
/remove-lifecycle stale

[openshift-bot]

Rotten enhancement proposals close after 7d of inactivity.

See https://github.com/openshift/enhancements#life-cycle for details.

Reopen the proposal by commenting /reopen.
Mark the proposal as fresh by commenting /remove-lifecycle rotten.
Exclude this proposal from closing again by commenting /lifecycle frozen.

/close

[openshift-ci]

@openshift-bot: Closing this issue.

In response to this:

Rotten enhancement proposals close after 7d of inactivity.

See https://github.com/openshift/enhancements#life-cycle for details.

Reopen the proposal by commenting /reopen.
Mark the proposal as fresh by commenting /remove-lifecycle rotten.
Exclude this proposal from closing again by commenting /lifecycle frozen.

/close

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.