Site icon Mike's Software Blog

mdcheckr: Practical testing for Markdown files

If you are a continuous integration enthusiast, you might be annoyed by preventable errors in project documentation.

I recently found a broken link in one project’s documentation, and a syntax error in an example on another project. I quickly wrote up a simple tool to detect this type of issue, solving the problem for me.

$ mdcheckr README.md
Checking README.md ..
- Code block starting line 21 (language: bash) [ OK ]
- Link https://travis-ci.org/receipt-print-hq/escpos-tools [ OK ]
- Link https://getcomposer.org/ [ OK ]
- Link doc/esc2text.md [ OK ]
- Link doc/esc2html.md [ OK ]
- Link doc/escimages.md [ OK ]
- Link CONTRIBUTING.md [ OK ]
- Link LICENSE.md [ OK ]
- Image https://travis-ci.org/receipt-print-hq/escpos-tools.svg?branch=master [ OK ]

I disregarded some existing “linter” tools. I don’t believe that it is necessarily productive for small projects to enforce a style-based quality gate for Markdown, but you may be able to configure these tools to be less pedantic. My goal here was to simply churn out a script which could reject objectively broken Markdown files.

I’ve posted this project to GitHub as mdcheckr. It is available as a package for Debian, Ubuntu, and RHEL/CentOS. Travis CI users may be interested to check out this pull request, where mdcheckr is added to the project’s build.

Exit mobile version