Linting markdown files
If you have your documentation in markdown files it can be beneficial to use linting as part of your build to ensure a standard approach to the markdown syntax across the team.
Installing them is easy enough
npm install --save remark-cli remark-preset-lint-recommended
With Remark installed you can setup your
package.json to use the library
"lint-md": "remark ."
now simply running
npm run lint-md will run linting with the ruleset
This approach works fine as long as your markdown files is part of your repository where
Creating a library
You can build on top of these libraries to create your own small library that can be run from inside other repositories as part of your build process. I have written about such an approach using docker before.
Since most build engines allow you to install npm modules globally you can also use this abstraction instead of docker and create a small cli tool for this purpose.
Here is an example of a small script that will use remark and remark-lint to lint all markdown files
I’m using Filehound to help with finding the markdown files I want to lint.
This can now be packaged and published on npmjs.org. In your build you can take a dependency on the package and run it as part of your build process.
If your documentation is in markdown you can take advantage of the js ecosystem and use the many small open source libraries created by others.
This can help you keep a consistency in your markdown syntax across the team.