↓Skip to main content
Dev Blog Dev Blog
  1. All Posts/

markdownlint

Tools JavaScript

markdownlint

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


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. The
CommonMark specification standardizes
parsers – but not authors.
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 directly from that project.

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 Super-Linter Action
    • GitHub Actions problem matcher for markdownlint-cli
  • Editor
  • 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

Demonstration

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

Rules / Aliases

  • MD001 heading-increment/header-increment – Heading levels should only increment by one level at a time
  • MD002 first-heading-h1/first-header-h1 – First heading should be a top-level heading
  • MD003 heading-style/header-style – Heading style
  • MD004 ul-style – Unordered list style
  • MD005 list-indent – Inconsistent indentation for list items at the same level
  • MD006 ul-start-left – Consider starting bulleted lists at the beginning of the line
  • 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/blanks-around-headers – Headings should be surrounded by blank lines
  • MD023 heading-start-left/header-start-left – Headings must start at the beginning of the line
  • MD024 no-duplicate-heading/no-duplicate-header – 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/no-emphasis-as-header – 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-headers – 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 should be consistent
  • MD050 strong-style – Strong style should be consistent
  • 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

See Rules.md for more details.
Struck through rules are deprecated, and provided for backward-compatibility.

All rules with heading as part of their name are also available as
header aliases (e.g. heading-increment is also available as header-increment).
The use of header is deprecated and provided for backward-compatibility.

Tags

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

  • accessibility – MD045
  • atx – MD018, MD019
  • atx_closed – MD020, MD021
  • blank_lines – MD012, MD022, MD031, MD032, MD047
  • blockquote – MD027, MD028
  • bullet – MD004, MD005, MD006, MD007, MD032
  • code – MD014, MD031, MD038, MD040, MD046, MD048
  • emphasis – MD036, MD037, MD049, MD050
  • hard_tab – MD010
  • headers – MD001, MD002, MD003, MD018, MD019, MD020, MD021, MD022,
    MD023, MD024, MD025, MD026, MD036, MD041, MD043
  • headings – MD001, MD002, MD003, MD018, MD019, MD020, MD021, MD022,
    MD023, MD024, MD025, MD026, MD036, MD041, MD043
  • hr – MD035
  • html – MD033
  • images – MD045, MD052, MD053
  • indentation – MD005, MD006, MD007, MD027
  • language – MD040
  • line_length – MD013
  • links – MD011, MD034, MD039, MD042, MD051, MD052, MD053
  • ol – MD029, MD030, MD032
  • spaces – MD018, MD019, MD020, MD021, MD023
  • spelling – MD044
  • ul – MD004, MD005, MD006, 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:

Rules can be enabled, disabled, and configured via options.config
(described below) to define the expected behavior for a set of inputs.
To enable or disable rules at a particular location within a file, add
one of these markers to the appropriate place (HTML comments don’t
appear in the final markup):

  • Disable all rules: <!-- markdownlint-disable -->
  • Enable all rules: <!-- markdownlint-enable -->
  • Disable all rules for the current line: <!-- markdownlint-disable-line -->
  • Disable all rules for the next line: <!-- markdownlint-disable-next-line -->
  • Disable one or more rules by name: <!-- markdownlint-disable MD001 MD005 -->
  • Enable one or more rules by name: <!-- markdownlint-enable MD001 MD005 -->
  • Disable one or more rules by name for the current line:
    <!-- markdownlint-disable-line MD001 MD005 -->
  • Disable one or more rules by name for the next line:
    <!-- markdownlint-disable-next-line MD001 MD005 -->
  • Capture the current rule configuration: <!-- markdownlint-capture -->
  • Restore the captured rule configuration: <!-- markdownlint-restore -->

For example:



↑