Repository files navigation

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

npm install markdownlint --save-dev

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

markdownlint is astatic analysis tool forNode.js with a library of rules to enforce standards and consistencyfor Markdown files. It was inspired by - and heavily influenced by - MarkHarrison'smarkdownlint for Ruby. The initial rules, ruledocumentation, and test cases came from that project.

markdownlint uses themicromark parser and honors theCommonMark specification for Markdown. It additionally supportspopularGitHub Flavored Markdown (GFM) syntax like autolinks and tablesas well as directives, footnotes, and math syntax - all implemented bymicromark extensions.

• 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 formarkdownlint-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

The following specifications are considered authoritative in cases of ambiguity:

• CommonMark
• GitHub Flavored Markdown Spec

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

• MD001heading-increment - Heading levels should only increment by one level at a time
• MD003heading-style - Heading style
• MD004ul-style - Unordered list style
• MD005list-indent - Inconsistent indentation for list items at the same level
• MD007ul-indent - Unordered list indentation
• MD009no-trailing-spaces - Trailing spaces
• MD010no-hard-tabs - Hard tabs
• MD011no-reversed-links - Reversed link syntax
• MD012no-multiple-blanks - Multiple consecutive blank lines
• MD013line-length - Line length
• MD014commands-show-output - Dollar signs used before commands without showing output
• MD018no-missing-space-atx - No space after hash on atx style heading
• MD019no-multiple-space-atx - Multiple spaces after hash on atx style heading
• MD020no-missing-space-closed-atx - No space inside hashes on closed atx style heading
• MD021no-multiple-space-closed-atx - Multiple spaces inside hashes on closed atx style heading
• MD022blanks-around-headings - Headings should be surrounded by blank lines
• MD023heading-start-left - Headings must start at the beginning of the line
• MD024no-duplicate-heading - Multiple headings with the same content
• MD025single-title/single-h1 - Multiple top-level headings in the same document
• MD026no-trailing-punctuation - Trailing punctuation in heading
• MD027no-multiple-space-blockquote - Multiple spaces after blockquote symbol
• MD028no-blanks-blockquote - Blank line inside blockquote
• MD029ol-prefix - Ordered list item prefix
• MD030list-marker-space - Spaces after list markers
• MD031blanks-around-fences - Fenced code blocks should be surrounded by blank lines
• MD032blanks-around-lists - Lists should be surrounded by blank lines
• MD033no-inline-html - Inline HTML
• MD034no-bare-urls - Bare URL used
• MD035hr-style - Horizontal rule style
• MD036no-emphasis-as-heading - Emphasis used instead of a heading
• MD037no-space-in-emphasis - Spaces inside emphasis markers
• MD038no-space-in-code - Spaces inside code span elements
• MD039no-space-in-links - Spaces inside link text
• MD040fenced-code-language - Fenced code blocks should have a language specified
• MD041first-line-heading/first-line-h1 - First line in a file should be a top-level heading
• MD042no-empty-links - No empty links
• MD043required-headings - Required heading structure
• MD044proper-names - Proper names should have the correct capitalization
• MD045no-alt-text - Images should have alternate text (alt text)
• MD046code-block-style - Code block style
• MD047single-trailing-newline - Files should end with a single newline character
• MD048code-fence-style - Code fence style
• MD049emphasis-style - Emphasis style
• MD050strong-style - Strong style
• MD051link-fragments - Link fragments should be valid
• MD052reference-links-images - Reference links and images should use a label that is defined
• MD053link-image-reference-definitions - Link and image reference definitions should be needed
• MD054link-image-style - Link and image style
• MD055table-pipe-style - Table pipe style
• MD056table-column-count - Table column count
• MD058blanks-around-tables - Tables should be surrounded by blank lines
• MD059descriptive-link-text - Link text should be descriptive
• MD060table-column-style - Table column style

SeeRules.md for more details.

In addition to built-in rules, custom rules can be used to addressproject-specific requirements. To find community-developed rules usekeywordmarkdownlint-rule on npm.To implement your own rules, refer toCustomRules.md.

Tags group related rules and can be used to enable/disable multiplerules 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

Text passed tomarkdownlint is parsed as Markdown, analyzed, and anyissues reported. Two kinds of text are ignored by most rules:

• HTML comments
• Front matter (seeoptions.frontMatter below)

All rules are enabled by default. Rules can be enabled, disabled, and configuredfor each call to thelint API by passing anoptions.config object (describedbelow). To enable or disable rules within a file, use one of the following HTMLcomments (which are not rendered):

• 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:

<!-- markdownlint-disable-next-line no-space-in-emphasis-->space * in * emphasis

Or:

space * in * emphasis<!-- markdownlint-disable-line no-space-in-emphasis-->

Or:

<!-- markdownlint-disable no-space-in-emphasis-->space * in * emphasis<!-- markdownlint-enable no-space-in-emphasis-->

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

<!-- markdownlint-capture--><!-- markdownlint-disable-->any violations you want<!-- markdownlint-restore-->

The initial configuration is captured by default (as if every documentbegan with<!-- markdownlint-capture -->), so the pattern above canbe expressed more simply:

<!-- markdownlint-disable-->any violations you want<!-- markdownlint-restore-->

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

space * in * emphasis<!-- markdownlint-disable--><!-- markdownlint-enable-->

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

• Disable all rules:<!-- markdownlint-disable-file -->
• Enable all rules:<!-- markdownlint-enable-file -->
• Disable one or more rules by name:<!-- markdownlint-disable-file MD001 -->
• Enable one or more rules by name:<!-- markdownlint-enable-file MD001 -->

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 ormore rules for a file, the following more advanced syntax is supported:

• Configure:<!-- markdownlint-configure-file { options.config JSON } -->

For example:

<!-- markdownlint-configure-file { "hr-style": { "style": "---" } }-->

or

<!-- markdownlint-configure-file{  "hr-style": {    "style": "---"  },  "no-trailing-spaces": false}-->

These changes apply to the entire file regardless of where the comment islocated. Multiple such comments (if present) are applied top-to-bottom. Bydefault, content ofmarkdownlint-configure-file is assumed to be JSON, butoptions.configParsers can be used to supportalternate formats.

Asynchronous API viaimport { lint } from "markdownlint/async":

/** * Lint specified Markdown files. * *@param {Options | null} options Configuration options. *@param {LintCallback} callback Callback (err, result) function. *@returns {void} */functionlint(options,callback){ ...}

Synchronous API viaimport { lint } from "markdownlint/sync":

/** * Lint specified Markdown files. * *@param {Options | null} options Configuration options. *@returns {LintResults} Results object. */functionlint(options){ ...}

Promise API viaimport { lint } from "markdownlint/promise":

/** * Lint specified Markdown files. * *@param {Options | null} options Configuration options. *@returns {Promise<LintResults>} Results object. */functionlint(options){ ...}

Type:Object

Configures the function. All properties are optional, but at least oneoffiles orstrings should be set to provide input.

Type:Object mappingString toBoolean | "error" | "warning" | Object

Configures the rules to use.

Object keys are rule names/aliases; object values are the rule's configuration.The valuefalse disables a rule. The valuestrue or"error" enable a rulein its default configuration and report violations as errors. The value"warning" enables a rule in its default configuration and reports violationsas warnings. Passing an object enablesand customizes the rule; the propertiesseverity ("error" | "warning") andenabled (false | true) can be used inthis context. The specialdefault rule assigns the default for all rules.Using a tag name (e.g.,whitespace) and a setting offalse,true,"error", or"warning" applies that setting to all rules with that tag. Whenno configuration object is passed or the optionaldefault setting is notpresent, all rules are enabled.

The following syntax disables the specified rule, tag, ordefault:

{"rule_tag_or_default":false}

The following syntax enables the specified rule, tag, ordefault to reportviolations as errors:

{"rule_tag_or_default":true// OR"rule_tag_or_default":"error"}

The following syntax enables the specified rule, tag, ordefault to reportviolations as warnings:

{"rule_tag_or_default":"warning"}

The following syntax enables and configures the specified rule to reportviolations as errors:

{"rule":{"severity":"error"}// OR"rule":{"rule_parameter":"value"}// OR"rule":{"severity":"error","rule_parameter":"value"}}

The following syntax enables and configures the specified rule to reportviolations as warnings:

{"rule":{"severity":"warning"}// OR"rule":{"severity":"warning","rule_parameter":"value"}}

Note that values"error" and"warning" and the propertyseverity are notsupported by library versions earlier than0.39.0. However, the examplesabove behave the same there, with warnings being reported as errors.

The following syntax disables and configures the specified rule:

{"rule":{"enabled":false,"rule_parameter":"value"}// OR  "rule": {    "enabled": false,    "severity": "warning",    "rule_parameter": "value"}}

Note that this example behavesdifferently with library versions earlierthan0.39.0 because the propertyenabled is not supported: itenablesthe rule instead ofdisabling it. As such, this syntax is discouraged wheninteroperability is important.

To evaluate a configuration object, thedefault setting is applied first, thenkeys are processed in order from top to bottom. If multiple values apply to arule (because of tag names or duplication), later values override earlier ones.Keys (including rule names, aliases, tags, ordefault) are not case-sensitive.

Example usingdefault, rule names, and tag names together:

{"default":true,"MD003": {"style":"atx_closed" },"MD007": {"indent":4 },"no-hard-tabs":false,"whitespace":false}

See.markdownlint.jsonc and/or.markdownlint.yaml for an exampleconfiguration object with all properties set to the default value.

Sets of rules (known as a "style") can be stored separately and loadedasJSON.

Example of referencing a built-in style from #"auto" data-snippet-clipboard-copy-content="const options = { "files": [ "..." ], "config": require("style/relaxed.json")};">

constoptions={"files":["..."],"config":require("style/relaxed.json")};

{"extends":"markdownlint/style/relaxed"}

{"default":true}

{"extends":"base.json","line-length":false}

constoptions={"config":markdownlint.readConfigSync("./custom.json")};

constoptions={"config":{"default":true,"line-length":false}};

options.configParsers

[JSON.parse,require("toml").parse,require("js-yaml").load]

options.customRules

constextraRules=require("extraRules");constoptions={"customRules":[extraRules.one,extraRules.two]};

options.files

options.frontMatter

/((^---[^\S\r\n\u2028\u2029]*$[\s\S]+?^---\s*)|(^\+\+\+[^\S\r\n\u2028\u2029]*$[\s\S]+?^(\+\+\+|\.\.\.)\s*)|(^\{[^\S\r\n\u2028\u2029]*$[\s\S]+?^\}\s*))(\r\n|\r|\n|$)/m

---layout: posttitle: Title---

options.fs

options.handleRuleFailures

options.markdownItFactory

importmarkdownItfrom"markdown-it";constmarkdownItFactory=()=>markdownIt({"html":true});

constmarkdownItFactory=()=>import("markdown-it").then((module)=>module.default({"html":true}));

options.noInlineConfig

options.resultVersion

import{convertToResultVersion0,convertToResultVersion1,convertToResultVersion2}from"markdownlint/helpers";

options.strings

{"readme":"# README\n...","changelog":"# CHANGELOG\n..."}

callback

result

Config

/** * Read specified configuration file. * *@param {string} file Configuration file name. *@param {ConfigurationParser[] | ReadConfigCallback} [parsers] Parsing function(s). *@param {Object} [fs] File system implementation. *@param {ReadConfigCallback} [callback] Callback (err, result) function. *@returns {void} */functionreadConfig(file,parsers,fs,callback){ ...}

/** * Read specified configuration file. * *@param {string} file Configuration file name. *@param {ConfigurationParser[]} [parsers] Parsing function(s). *@param {Object} [fs] File system implementation. *@returns {Configuration} Configuration object. */functionreadConfig(file,parsers,fs){ ...}

/** * Read specified configuration file. * *@param {string} file Configuration file name. *@param {ConfigurationParser[]} [parsers] Parsing function(s). *@param {Object} [fs] File system implementation. *@returns {Promise<Configuration>} Configuration object. */functionreadConfig(file,parsers,fs){ ...}

file

parsers

[JSON.parse,require("toml").parse,require("js-yaml").load]

fs

callback

result

Fixing

/** * Applies the specified fix to a Markdown content line. * *@param {string} line Line of Markdown content. *@param {RuleOnErrorFixInfo} fixInfo RuleOnErrorFixInfo instance. *@param {string} [lineEnding] Line ending to use. *@returns {string | null} Fixed content or null if deleted. */functionapplyFix(line,fixInfo,lineEnding="\n"){ ...}/** * Applies as many of the specified fixes as possible to Markdown content. * *@param {string} input Lines of Markdown content. *@param {RuleOnErrorInfo[]} errors RuleOnErrorInfo instances. *@returns {string} Fixed content. */functionapplyFixes(input,errors){ ...}

import{applyFixes}from"markdownlint";import{lintaslintSync}from"markdownlint/sync";constresults=lintSync({"strings":{"content":original}});constfixed=applyFixes(original,results.content);

Miscellaneous

/** * Gets the (semantic) version of the library. * *@returns {string} SemVer string. */functiongetVersion(){ ...}

import{getVersion}from"markdownlint";// Displays the library versionconsole.log(getVersion());

Usage

import{lintaslintAsync}from"markdownlint/async";constoptions={"files":["good.md","bad.md"],"strings":{"good.string":"# good.string\n\nThis string passes all rules.","bad.string":"#bad.string\n\n#This string fails\tsome rules."}};lintAsync(options,functioncallback(error,results){if(!error&&results){console.dir(results,{"colors":true,"depth":null});}});

import{lintaslintSync}from"markdownlint/sync";constresults=lintSync(options);console.dir(results,{"colors":true,"depth":null});

import{lintaslintPromise}from"markdownlint/promise";constresults=awaitlintPromise(options);console.dir(results,{"colors":true,"depth":null});

{"good.md": [],"bad.md": [    {"lineNumber":3,"ruleNames": ["MD010","no-hard-tabs" ],"ruleDescription":"Hard tabs","ruleInformation":"https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md010.md","errorDetail":"Column: 17","errorContext":null,"errorRange": [17,1 ],"fixInfo": {"editColumn":17,"deleteCount":1,"insertText":"" },"severity":"error" },    {"lineNumber":1,"ruleNames": ["MD018","no-missing-space-atx" ],"ruleDescription":"No space after hash on atx style heading","ruleInformation":"https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md018.md","errorDetail":null,"errorContext":"#bad.md","errorRange": [1,2 ],"fixInfo": {"editColumn":2,"insertText":"" },"severity":"error" },    {"lineNumber":3,"ruleNames": ["MD018","no-missing-space-atx" ],"ruleDescription":"No space after hash on atx style heading","ruleInformation":"https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md018.md","errorDetail":null,"errorContext":"#This file fails\tsome rules.","errorRange": [1,2 ],"fixInfo": {"editColumn":2,"insertText":"" },"severity":"error" },    {"lineNumber":1,"ruleNames": ["MD041","first-line-heading","first-line-h1" ],"ruleDescription":"First line in a file should be a top-level heading","ruleInformation":"https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md041.md","errorDetail":null,"errorContext":"#bad.md","errorRange":null,"fixInfo":null,"severity":"error" }  ]}

Browser

npm run build-demo

<scriptsrc="demo/markdownlint-browser.min.js"></script>

constoptions={"strings":{"content":"Some Markdown to lint."}};constresults=globalThis.markdownlint.lintSync(options);

Examples

Contributing

Releasing

History