Linting Markdown files in GitLab CI
A while ago I was looking for a way to lint Markdown files and came across markdownlint in my search.
There are two CLI tools for it, markdownlint-cli and markdownlint-cli2.
Based on the comparison and rationale by one of the authors I gave markdownlint-cli2 a try first.
It is node-based and has lots of supported ways of invocation, such as a pre-commit hook, works well with the markdownlint vscode extension, and can be run as a container (including an image containing custom rules).
We are using GitLab which has code quality scanning support. You can import code quality results from a CI/CD job. Depending on the tier you have, you can see code quality findings in various places in the merge request UI helping the merge request author and reviewer(s). The code quality findings are provided as a JSON file during a CI/CD job. The report format is based on the CodeClimate report specification.
There was unfortunately no support for this yet.
At first, I wrote a custom formatter that lived in our private repo.
But instead of leaving it buried in a private repo, I wanted to make it available to all our own repositories and the markdownlint-cli2 community.
I checked if there was appetite for integrating this into markdownlint-cli2 and ended up contributing a code quality formatter.
It is published as an npm package: https://www.npmjs.com/package/markdownlint-cli2-formatter-codequality.