Markdown linter

[chevdor]

Description

Mentioned in #1181, this PR introduces linting for the markdown files using markdownlint.

It does:

• add a set of linter rules (more on that below)
• adapt the rules to match our current codebase
• fix the required markdown
• add a new CI check for PRs

At that point, the goal is not to define the final set of rules but to bring everything to a coherent state and start with a set of rules that is close to our current practises so far:

• started from default rules
• disabled contentious rules triggering lots of errors
• set max length to 120 for text and 150 for code + fixes (we had lines over 800+ chars). Why 120/150? we had a mix of very long lines, 80 and 120. 120/150 remains a rather big value but bring already an improvement of some 800+ chars lines. Files already using cut at 80 are not affected
• focus on "consistency" vs defining hard rules. For instance, no rule is forcing the usage of * vs - for lists but the current list enforce that we use either one or the other within a file
• the ruleset has been built while reading the current content and trying to match the current state as close as possible

Some rules have been disabled to limit the number of initial fixes but should likely be re-introduced. For instance:

• MD025
• MD051
  That can be the object and discussed in a follow up PR.

Remaining todos

• remove settings used for testing
• document

fix #1243

[juangirini]

Currently our style guideline states that preferred comment length is 100

polkadot-sdk/docs/STYLE_GUIDE.md

Lines 11 to 12 in 43c0c09

	- Lines should be longer than 100 characters long only in exceptional circumstances and certainly
	no longer than 120. For this purpose, tabs are considered 4 characters wide.

Can we make it so comments that have a length less than 120 are not forced to 120?

[chevdor]

Thanks for the review @juangirini.

I initilly thought we don't need to have the same rules for Rust code and Markdown but it could make it easier for dev to have the same limit.

The suggestion of 100 and "no longer than" 120 actually matches the current limit of 120. We could mention in the suggestion in the guidelines for Markdown as well but the linter can only set a hard limit.

[chevdor]

Can we make it so comments that have a length less than 120 are not forced to 120?

Yes! This is the case today. We have file where devs formatted all with 80 chars.
Those make the linter happy with the 120 limits and are left untouched by the tools such doing auto rewrap.

[paritytech-cicd-pr]

The CI pipeline was cancelled due to failure one of the required jobs.
Job name: test-linux-stable 2/3
Logs: https://gitlab.parity.io/parity/mirrors/polkadot-sdk/-/jobs/3546209