markdownlint

A Node.js style checker and lint tool for Markdown/CommonMark files.

[![npm version][npm-image]][npm-url] [![License][license-image]][license-url]

Install

npm install markdownlint --save-dev

Overview

The Markdown markup language is designed to be easy to read, write, and understand. It succeeds - and its flexibility is both a benefit and a drawback. Many styles are possible, so formatting can be inconsistent; some constructs don't work well in all parsers and should be avoided.

markdownlint is a static analysis tool for Node.js with a library of rules to enforce standards and consistency for Markdown files. It was inspired by - and heavily influenced by - Mark Harrison's markdownlint for Ruby. The initial rules, rule documentation, and test cases came from that project.

markdownlint uses the micromark parser and honors the CommonMark specification for Markdown. It additionally supports popular GitHub Flavored Markdown (GFM) syntax like autolinks and tables as well as directives, footnotes, and math syntax - all implemented by micromark extensions. (Note that inline directives are not supported to avoid confusion due to over-matching.)

Related

• CLI
• markdownlint-cli command-line interface for Node.js (works with pre-commit)
• markdownlint-cli2 command-line interface for Node.js (works with pre-commit)
• GitHub
• GitHub Action for markdownlint-cli2
• GitHub Super-Linter Action
• GitHub Actions problem matcher for markdownlint-cli
• Editor
• vscode-markdownlint extension for VS Code
• Sublime Text markdownlint for Sublime Text
• coc-markdownlint extension for Vim/Neovim
• flymake-markdownlint-cli2 extension for Emacs
• Tooling
• eslint-plugin-markdownlint for the ESLint analyzer
• grunt-markdownlint for the Grunt task runner
• Cake.Markdownlint addin for Cake build automation system
• Lombiq Node.js Extensions for MSBuild (.NET builds)
• Ruby
• markdownlint/mdl gem for Ruby

References

The following specifications are considered authoritative in cases of ambiguity:

• CommonMark
• GitHub Flavored Markdown Spec

Demonstration

markdownlint demo, an interactive, in-browser playground for learning and exploring.

Rules / Aliases

• MD001 heading-increment - Heading levels should only increment by one level at a time
• MD003 heading-style - Heading style
• MD004 ul-style - Unordered list style
• MD005 list-indent - Inconsistent indentation for list items at the same level
• MD007 ul-indent - Unordered list indentation
• MD009 no-trailing-spaces - Trailing spaces
• MD010 no-hard-tabs - Hard tabs
• MD011 no-reversed-links - Reversed link syntax
• MD012 no-multiple-blanks - Multiple consecutive blank lines
• MD013 line-length - Line length
• MD014 commands-show-output - Dollar signs used before commands without showing output
• MD018 no-missing-space-atx - No space after hash on atx style heading
• MD019 no-multiple-space-atx - Multiple spaces after hash on atx style heading
• MD020 no-missing-space-closed-atx - No space inside hashes on closed atx style heading
• MD021 no-multiple-space-closed-atx - Multiple spaces inside hashes on closed atx style heading
• MD022 blanks-around-headings - Headings should be surrounded by blank lines
• MD023 heading-start-left - Headings must start at the beginning of the line
• MD024 no-duplicate-heading - Multiple headings with the same content
• MD025 single-title/single-h1 - Multiple top-level headings in the same document
• MD026 no-trailing-punctuation - Trailing punctuation in heading
• MD027 no-multiple-space-blockquote - Multiple spaces after blockquote symbol
• MD028 no-blanks-blockquote - Blank line inside blockquote
• MD029 ol-prefix - Ordered list item prefix
• MD030 list-marker-space - Spaces after list markers
• MD031 blanks-around-fences - Fenced code blocks should be surrounded by blank lines
• MD032 blanks-around-lists - Lists should be surrounded by blank lines
• MD033 no-inline-html - Inline HTML
• MD034 no-bare-urls - Bare URL used
• MD035 hr-style - Horizontal rule style
• MD036 no-emphasis-as-heading - Emphasis used instead of a heading
• MD037 no-space-in-emphasis - Spaces inside emphasis markers
• MD038 no-space-in-code - Spaces inside code span elements
• MD039 no-space-in-links - Spaces inside link text
• MD040 fenced-code-language - Fenced code blocks should have a language specified
• MD041 first-line-heading/first-line-h1 - First line in a file should be a top-level heading
• MD042 no-empty-links - No empty links
• MD043 required-headings - Required heading structure
• MD044 proper-names - Proper names should have the correct capitalization
• MD045 no-alt-text - Images should have alternate text (alt text)
• MD046 code-block-style - Code block style
• MD047 single-trailing-newline - Files should end with a single newline character
• MD048 code-fence-style - Code fence style
• MD049 emphasis-style - Emphasis style
• MD050 strong-style - Strong style
• MD051 link-fragments - Link fragments should be valid
• MD052 reference-links-images - Reference links and images should use a label that is defined
• MD053 link-image-reference-definitions - Link and image reference definitions should be needed
• MD054 link-image-style - Link and image style
• MD055 table-pipe-style - Table pipe style
• MD056 table-column-count - Table column count
• MD058 blanks-around-tables - Tables should be surrounded by blank lines
• MD059 descriptive-link-text - Link text should be descriptive
• MD060 table-column-style - Table column style

See Rules.md for more details.

Custom Rules

In addition to built-in rules, custom rules can be used to address project-specific requirements. To find community-developed rules use keyword markdownlint-rule on npm. To implement your own rules, refer to CustomRules.md.

Tags

Tags group related rules and can be used to enable/disable multiple rules at once.

• accessibility - MD045, MD059
• atx - MD018, MD019
• atx_closed - MD020, MD021
• blank_lines - MD012, MD022, MD031, MD032, MD047
• blockquote - MD027, MD028
• bullet - MD004, MD005, MD007, MD032
• code - MD014, MD031, MD038, MD040, MD046, MD048
• emphasis - MD036, MD037, MD049, MD050
• hard_tab - MD010
• headings - MD001, MD003, MD018, MD019, MD020, MD021, MD022, MD023, MD024, MD025, MD026, MD036, MD041, MD043
• hr - MD035
• html - MD033
• images - MD045, MD052, MD053, MD054
• indentation - MD005, MD007, MD027
• language - MD040
• line_length - MD013
• links - MD011, MD034, MD039, MD042, MD051, MD052, MD053, MD054, MD059
• ol - MD029, MD030, MD032
• spaces - MD018, MD019, MD020, MD021, MD023
• spelling - MD044
• table - MD055, MD056, MD058, MD060
• ul - MD004, MD005, MD007, MD030, MD032
• url - MD034
• whitespace - MD009, MD010, MD012, MD027, MD028, MD030, MD037, MD038, MD039

Configuration

Text passed to markdownlint is parsed as Markdown, analyzed, and any issues reported. Two kinds of text are ignored by most rules:

• HTML comments
• Front matter (see options.frontMatter below)

All rules are enabled by default. Rules can be enabled, disabled, and configured for each call to the lint API by passing an options.config object (described below). To enable or disable rules within a file, use one of the following HTML comments (which are not rendered):

• Disable all rules: ``
• Enable all rules: ``
• Disable all rules for the current line: ``
• Disable all rules for the next line: ``
• Disable one or more rules by name: ``
• Enable one or more rules by name: ``
• Disable one or more rules by name for the current line: ``
• Disable one or more rules by name for the next line: ``
• Capture the current rule configuration: ``
• Restore the captured rule configuration: ``

For example:

space * in * emphasis

Or:

space * in * emphasis 

Or:

space * in * emphasis

To temporarily disable rule(s), then restore the former configuration:

any violations you want

The initial configuration is captured by default (as if every document began with ``), so the pattern above can be expressed more simply:

any violations you want

Changes take effect starting with the line a comment is on, so the following has no effect:

space * in * emphasis  

To apply changes to an entire file regardless of where the comment is located, the following syntax is supported:

• Disable all rules: ``
• Enable all rules: ``
• Disable one or more rules by name: ``
• Enable one or more rules by name: ``

This can be used to "hide" markdownlint comments at the bottom of a file.

In cases where it is desirable to change the configuration of one or more rules for a file, the following more advanced syntax is supported:

• Configure: ``

For example:

or

```markdown <!-- markdownlint-configure-file { "hr-s