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}.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.

Automatic correction / Markdown reformat¶

For some of the rules, the syntax checker can correct issues identified. If used (flag --fix or -f), the feedback on the CLI follows the pattern of

$ mdl -f example.md
example.md:1: MD009 Trailing spaces (corrected)
    

This action overwrites the version of file example.md submitted without an optional dryrun, preview, nor backup. Below, the rule code and reformat (fix) by the syntax checker are described:

• MD009, trailing white space: trailing white space is removed
• MD010, hard tabs: each tab is replaced by four spaces
• MD012, Multiple consecutive blank lines: retains one blank line
• MD018, No space after hash on atx style header: inserts a single space
• MD019, Multiple spaces after hash on atx style header: retains one space
• MD021, Multiple spaces inside hashes on closed atx style header: retains one space
• MD023, Headers must start at the beginning of the line: leading white space is removed
• MD027, Multiple spaces after blockquote symbol: retains one space

Similar to a syntax check, you can adjust the scope of a syntax reformat. An example is

$ mdl example.md
example.md:1: MD009 Trailing spaces
example.md:3: MD010 Hard tabs
$ mdl -r ~MD010 -f example.md
example.md:1: MD009 Trailing spaces (corrected)
    

to explicitly exclude fixes according to rule MD010. Because the syntax checker does not write backup files (vide supra), a consolidation of Markdown files with specific increments similar to the one above can be advantageous compared to an application of all fixes available at once.