Add linting for markdown files

[kate-osborn]

Proposed changes

Problem: The markdown files in the repo were not linted.

Solution: Add markdownlint step to pre-commit. All markdown files except the .github files will be linted before every commit. Markdownlint will attempt to fix the linting errors and will report any errors it cannot fix. Linting rules are in the .markdownlint-cli2.yaml file in the root of the repo. For details on the linting rules, see: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md

Testing: Verified markdown files are linted on pre-commit.

Closes #555

Checklist

Before creating a PR, run through this checklist and mark each as complete.

• I have read the CONTRIBUTING doc
• I have added tests that prove my fix is effective or that my feature works
• I have checked that all unit tests pass after adding my changes
• I have updated necessary documentation
• I have rebased my branch onto main
• I will ensure my PR is targeting the main branch and pulling from my branch from my own fork

[lucacome]

Thanks for adding this!
I left a comment about markdown-cli vs markdown-cli2. Also do we want the CI to autofix the problems? Or just flag them like the other linters?
If it's the latter we can add https://github.com/xt0rted/markdownlint-problem-matcher or https://github.com/marketplace/actions/markdownlint-cli2-action to the linter workflow.

[kate-osborn]

Thanks for adding this! I left a comment about markdown-cli vs markdown-cli2. Also do we want the CI to autofix the problems? Or just flag them like the other linters? If it's the latter we can add https://github.com/xt0rted/markdownlint-problem-matcher or https://github.com/marketplace/actions/markdownlint-cli2-action to the linter workflow.

Good question about autofix in the pipelines. I think we just want to flag them in the pipeline. @sjberman @pleshakov what do you think?

[sjberman]

Thanks for adding this! I left a comment about markdown-cli vs markdown-cli2. Also do we want the CI to autofix the problems? Or just flag them like the other linters? If it's the latter we can add https://github.com/xt0rted/markdownlint-problem-matcher or https://github.com/marketplace/actions/markdownlint-cli2-action to the linter workflow.

Good question about autofix in the pipelines. I think we just want to flag them in the pipeline. @sjberman @pleshakov what do you think?

As long as it's consistent, that's all that matters to me!

[pleshakov]

Good question about autofix in the pipelines. I think we just want to flag them in the pipeline. @sjberman @pleshakov what do you think?

@kate-osborn
I'd prefer flagging. I'd rather retain control over the contents of my PR. I think that will be consistent with our other checks, that do not add any commits/fix problems in place.

[lucacome]

🚀