MARKDOWNLINT(1)

NAME
markdownlint - Markdown lint tool

SYNOPSIS
mdl [ options ] [FILE.md|DIR ...]

DESCRIPTION
markdownlint checks an individual markdown file, or a directory of markdown files against a set of rules for syntax consistency. In its report back to the CLI, the Ruby based implementation reports the line(s) with an issue identified and how to improve it.

OPTIONS

-c, --config FILE
    The configuration file to use

-g, --git-recurse
    Only process files known to git when given a directory

-i, --[no]-ignore-front-matter
    Ignore YAML front matter

-j, --json
    JSON output

-l, --list-rules
    Don't process any files, just list enabled rules

-r, --rules RULE1,RULE2
    Only process these rules

-u, --rulesets RULESET1,RULESET2
    Specify additional ruleset files to load

-S, --sarif
    SARIF output

-a, --[no]show-aliases
    Show rule aliases instead of rule ID when viewing rules

-w, --[no]warnings
    Show kramdown warnings

-d, --skip-default-ruleset
    Don't load the default markdownlint ruleset

-s, --style STYLE
    Load the given style

-t, --tags TAG1,TAG2
    Only process rules with these tags

-v, --[no-]verbose
    Increase verbosity

-h, --help
    Show this message

-V, --version
    Show version

EXAMPLES
Equally visit folders docs and example of the GitHub repository.

  use rules by a flag
List the objectives of rules MD012, MD022, MD031 and MD032:

        mdl -r MD012,MD022,MD031,MD032 -l

Scrutinize file example.md only by rules MD012, MD022, MD031 and MD032:

        mdl -r MD012,MD022,MD031,MD032 example.md

Scrutinize file example.md by all rules available except MD033 and MD034:

        mdl -r ~MD033,~MD034 example.md

List all rules associated to the tag indentation:

        mdl -t indentation -l

Scrutinize file example.md by all rules without tag indentation:

        mdl -t ~indentation example.md

By default, markdownlint reports sort the issues by their rule. With GNU coreutils, your shell may resort the output by the corresponding line number of the file:

        mdl example.md | sort -t ":" -k 2 -n

  use rules by a local style file

Recurrent (personalized) check criteria can be saved as a style file, for instance mystyle.rb. The snippet below illustrates the syntax available. Instead of pairs of single quotes, pairs of double quotes may be used, too.

        all  # initiate with all rules implemented

        rule 'MD013', :line_length => 100, :ignore_code_blocks => true
        exclude_rule 'MD014'

        # tag :blockquote
        exclude_tag :indentation

List the rules a local style file activates:

        mdl -s mystyle.rb -l

A personalized local style then is used by

        mdl -s mystyle.rb example.md

Local flags are of higher priority than a local style file. Therefore, the next command removes rule MD013 from consideration, regardless of any definition about said rule in mystyle.rb:

        mdl -s mystyle.rb -r ~MD013 example.md

  use rules by a global style file

To deploy a markdownlint style all across your computer, set up a style file (e.g., mystyle.rb). Second, add a .mdlrc file to your home directory to indicate the location of said style file by

        style "#{File.dirname(__FILE__)}/{your_markdown_rule_file_path}.rb"

Subsequently, a call by

        mdl example.md

then applies the global style set. In similar logic as above, a local style file overrules definitions of a global style, i.e.

        mdl example.md -s local_style.rb

  use rules for a project with continuous integration

The setup of a markdownlint style per project equally consists of two files. As an example, define .exclude_example.rb with

        # First, include all rules:
        all
        # Then, exclude MD013 (long lines), with:
        exclude_rule 'MD013'

as a style file, and a .mdlrc as indicator of its location with

        #The custom style file is referenced by .mdlrc as below
        style ".exclude_example.rb"

at the current root. Again, a call like

        mdl example.md

then applies the rules defined.

AUTHOR
Mark Harrison, Ciro Santilli, Making GitHub Delicious., Brandon High, Matt Jankowski, David Anson, Tobias Bengfort, Loic Nageleisen, Will Fleming, Jean-Christophe GAY, sudodoki, David Rodríguez, Garth Braithwaite, garthdb, Alexander Köplinger, Simon Symeonidis, psyomn, Jakub Wilk, Eitan Adler, Phil Dibowitz, David Somers-Harris, copperwalls, John Trammell, Waylan Limberg, Ash, Paul B, Andrew Janke, Adam Strickland, Naomi Reeves, Olle Jonsson, Lauritz Hilsøe, Roman Kolesnev, Alex Harvey, Tim Smith, tsuburin, Mikael Kjaer, Caleb Buxton, Mark E. Schill, Waldir Pimenta, Jose Angel Pardillo Vela, androidseb, jtcarnes, Gene Gotimer, Sami Ahmed Siddiqui, Karol Babioch, Eric Knibbe, Alexander Jaust, orviz, Lennart Jern, Benjamin Quorning, Ting Chen, Kai, adamroyjones, Bengt Lüers, JP Hastings-Spital, nbehrnd, iafelix, ColemanTom, Levente Polyak, Gunes Bayir, Mathieu Rul, Markus Lehtonen, Matthias Thym, Benjamin Bannier, AJRepo, Ulysses Zhan, Lucas Ventura.

LICENSE
MIT

REPORTING BUGS
Report bugs to and suggest improvements on the project page,
https://github.com/markdownlint/markdownlint

VERSION
This is about markdownlint version 0.17.0 (June 13, 2026).