Consider using a linter for markdown files

[colin-axner]

Summary

It can be useful to lint our markdown files for consistency. Adding this tooling into our workflow would prevent reviewing unnecessary diffs when a linter is run on the markdown files.

see related comment thread

---

For Admin Use

• Not duplicate issue
• Appropriate labels applied
• Appropriate contributors tagged/assigned

[DimitrisJim]

We do already have a docs-lint rule in the Makefile and its a suggestion in the Development Setup. Frankly, I also just learned it exists 😄

[colin-axner]

Should we add this to our ci checks?

[DimitrisJim]

we should ask @damiannolan since we know how much love he has for linters complaining to him (but yeah, I'd say it would be a good idea).

[damiannolan]

We have make docs-lint and make docs-lint-changed, both of which use this markdownlint tool afaik.

IMO adding a CI check for this might be a little overkill, especially since we're already pushing limits on GH runners. We could enforce a pre-commit hook, I think @chatton already uses one in his local setup which makes use of docs-lint-changed as well as lint-fix-changed (for golangci-lint)

[DimitrisJim]

IMO adding a CI check for this might be a little overkill, especially since we're already pushing limits on GH runners

Can't we set it to only run when changes to docs/ are triggered?

[damiannolan]

Yeah true

[srdtrk]

Most files are already linted. The real issue is that we don't have a custom ruleset for our project. Markdownlinter's default settings will result in markdown files that reflect the author's preferred markdown authoring preferences. This is what causes inconsistency in our docs. I think we can rename this issue to something like Define custom markdownlint ruleset configuration

[DimitrisJim]

do we not have .markdownlint.jsonc for the rules? The idea of the issue as I understood it is to have markdownlint run on new changes to guarantee consistency.

[srdtrk]

We do @DimitrisJim, however, it is not customised enough. It just tells the linter to ignore some settings. Currently the style settings are still set to default. This includes things like heading style, indentations, unordered list style and more. For example, the fix to the comment thread @colin-axner linked in this issue would be to add

  "MD004": {
    "style": "dash"
  },

This is why Colin noticed some files being changed * => - and others - => * by the linter.

[srdtrk]

I'm addressing this issue in the next docs PR

[srdtrk]

I've factored this out of the docs PR, and instead, linter/workflow related changes will have their own PR

[crodriguezvega]

Closed by #3805