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.

There is some excellent open source packages ready to be used for this purpose. Remark and Remark-lint is fitting the requirement perfectly.

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

  ...
"scripts": {
"lint-md": "remark ."
},
...
"remarkConfig": {
"plugins": ["remark-preset-lint-recommended"]
}
...

now simply running npm run lint-md will run linting with the ruleset remark-preset-lint-recommended

This approach works fine as long as your markdown files is part of your repository where package.json resides.

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.

The full example can be seen on my Github and I have published the package on npm.

Conclusion

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.

One clap, two clap, three clap, forty?

By clapping more or less, you can signal to us which stories really stand out.