Scanning Markdown Files For Stylistic Errors

Introduction

There are several static code analyzer tools like SonarQube, Raxis, Coverity, and others to scan the source code during development and report security vulnerabilities. These tools won’t scan the markdown files used for readability. This article will explain how to use markdown lint tool for scanning markdown (.md) files and report style issues.

There are other lint tools available for scanning markdown files to identify grammar issues, spellings, and clarity of the statements. This article specifically will show how to install Ruby Markdown lint, integrate with Azure DevOps pipeline and identify stylistic issues in the markdown files

Install markdown lint

Markdown lint can be installed as ruby gem, have the latest version of Ruby, and follow the below steps to install in local machine

gem install mdl
gem install rake
gem install bundler

For latest development version clone from github

Commands to scan markdown files

To scan individual markdown files use mdl with file name

mdl <<markdown file name>> 
mdl README.md

To scan markdown files in a specific directory, use below command

mdl <<directory name>>/
mdl files/

The tool will list all the stylistic issues with line numbers as shown below

To understand each issue reported and remediate refer RULES.md

As per requirements, the rules can be enabled or disabled by creating style files. If there is a need in the project to allow trailing spaces in the documentation, the rule can be disabled by defining a style file. This makes the lint tool to flexible to report stylistic issues as per rules defined in style files based on project requirements. Refer styles document for more details.

To remediate stylistic issues during development, install markdownlint extensions from marketplace in Visual Studio Code. After installing the extension, execute mdl command with file name or directory in the terminal window in VS code.

Integrate markdown lint with Azure DevOps pipeline

Let’s see how to integrate markdownlint tool with ADO pipeline so that the scanning task is automated whenever the build runs and reports the stylistic errors. If there are any errors reported in the tool, then the build would fail and has to be remediated.

Create or open existing yaml file, use the latest version of Ubuntu pool to run this job

Add job steps and multiple steps if needed for installing lint tool and running the mdl command. For the sake of simplicity, I have used only one job steps for installing and scanning the markdown files.

Below are the scripts to be added in the job steps for scanning

1. Install markdownlint tool
2. Add the Github repository to be scanned, if the repository is same as yaml file repo no need to mention the checkout command
3. Script to scan all markdown files in the repository

steps:
    - script: sudo gem install mdl      
    - script: sudo gem install rake
    - script: sudo gem install bundler  
    # mention the repository to scan 
    - checkout: git://ADO project name/repository name
    # command to scan markdown in the directory including nested directories
    - script: sudo mdl ./ *.md 

When the pipeline executes, if there are any style issues in markdown files those will be listed in pipeline job steps and the build would fail.

mdl command can be used with different options based on the need, refer markdown lint configuration for options

Conclusion

There are many lint tools available for scanning markdown files, like checking style issues, spelling, and grammar. Integrate multiple markdown scanning tools as per requirements with customized style files.