Skip to content

Markdown Lint Tool (mdl)

Markdown is a popular markup language for creating documentation, README files, and other forms of plain text content. However, maintaining consistent formatting and style in Markdown documents can be challenging, especially when collaborating with a team. To address this issue, we use a tool called mdl (Markdown lint) to help ensure the quality and consistency of our Markdown files.

What is mdl?

mdl is a command-line tool that analyzes Markdown documents and checks them against a set of predefined rules. It helps identify and highlight issues such as formatting inconsistencies, broken links, and other potential problems. By using mdl, we can maintain a uniform style across our Markdown files and catch errors early in the documentation process.

Why Use mdl?

Here are some key reasons why we use mdl in our daily work:

  1. Consistency: mdl enforces a consistent Markdown style across all our documentation, making it easier for team members to read and contribute to Markdown files.

  2. Error Prevention: It helps catch errors and formatting issues before they become problems, reducing the chances of publishing inaccurate or poorly formatted documentation.

  3. Improved Collaboration: By adhering to a common style guide, team members can work more seamlessly together on Markdown files.

  4. Automated Checks: mdl automates the process of checking Markdown files, saving time and effort compared to manual inspections.

How to Install mdl

To use mdl, you’ll need to install it on your local development environment. You can install it using RubyGems, a package manager for Ruby:

gem install mdl

Once installed, you can run mdl on your Markdown files from the command line.

Running mdl

To check a Markdown file named example.md, you can use the following command:


mdl example.md

mdl will provide a list of any issues it finds in the file, along with suggestions for fixing them.

Customizing mdl Rules

While mdl comes with a set of default rules, you can also customize its behavior by creating a .mdlrc configuration file in your project directory. This allows us to tailor mdl to our specific needs and style preferences.

Integrating with Our Workflow

We encourage all team members to run mdl on Markdown files before committing changes. You can also consider integrating mdl into your continuous integration (CI) pipeline to automatically check Markdown files as part of your development process.

Resources