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
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 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
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
- emphasis - MD036, MD037
- 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
- indentation - MD005, MD006, MD007, MD027
- language - MD040
- line_length - MD013
- links - MD011, MD034, MD039, MD042
- 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 within a file, add one of these markers to the appropriate place (HTML
comments don't appear in the final markup):
- Disable all rules unconditionally:
<!-- markdownlint-disable -->
- Enable all rules unconditionally:
<!-- markdownlint-enable -->
- Disable one or more rules by name:
<!-- markdownlint-disable MD001 MD005 -->
- Enable one or more rules by name:
<!-- markdownlint-enable MD001 MD005 -->
- Capture the current rule configuration:
<!-- markdownlint-capture -->
- Restore the captured rule configuration:
<!-- markdownlint-restore -->
For example:
<!-- markdownlint-disable no-space-in-emphasis -->
deliberate 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 document began
with <!-- markdownlint-capture -->
), so the pattern above can be expressed
more simply:
<!-- markdownlint-disable -->
any violations you want
<!-- markdownlint-restore -->
Changes take effect starting with the line a comment is on, so the following
has no effect:
space * in * emphasis <!-- markdownlint-disable --> <!-- markdownlint-enable -->
API
Linting
Standard asynchronous interface:
function markdownlint(options, callback) { ... }
Synchronous interface (for build scripts, etc.):
function markdownlint.sync(options) { ... }
options
Type: Object
Configures the function.
options.customRules
Type: Array
of Object
List of custom rules to include with the default rule set for linting.
Each array element should define a rule. Rules are typically exported by another
package, but can be defined inline.
Example:
const extraRules = require("extraRules");
const options = {
"customRules": [ extraRules.one, extraRules.two ]
};
See CustomRules.md for details about authoring custom rules.
options.files
Type: Array
of String
List of files to lint.
Each array element should be a single file (via relative or absolute path);
globbing is the caller's
responsibility.
Example: [ "one.md", "dir/two.md" ]
options.strings
Type: Object
mapping String
to String
Map of identifiers to strings for linting.
When Markdown content is not available as files, it can be passed as strings.
The keys of the strings
object are used to identify each input value in the
result
summary.
Example:
{
"readme": "# README\n...",
"changelog": "# CHANGELOG\n..."
}
options.config
Type: Object
mapping String
to Boolean | Object
Configures the rules to use.
Object keys are rule names or aliases and values are the rule's configuration.
The value false
disables a rule, true
enables its default configuration,
and passing an object customizes its settings. Setting the special default
rule to true
or false
includes/excludes all rules by default. Enabling or
disabling a tag name (ex: whitespace
) affects all rules having that tag.
The default
rule is applied first, then keys are processed in order from top
to bottom with later values overriding earlier ones. Keys (including rule names,
aliases, tags, and default
) are not case-sensitive.
Example:
{
"default": true,
"MD003": { "style": "atx_closed" },
"MD007": { "indent": 4 },
"no-hard-tabs": false,
"whitespace": false
}
Sets of rules (known as a "style") can be stored separately and loaded as
JSON.
Example:
const options = {
"files": [ "..." ],
"config": require("style/relaxed.json")
};
See the style directory for more samples.
See markdownlint-config-schema.json
for the JSON Schema of the options.config
object.
For more advanced scenarios, styles can reference and extend other styles. The
readConfig
and readConfigSync
functions can be used to read such styles.
For example, assuming a base.json
configuration file:
{
"default": true
}
And a custom.json
configuration file:
{
"extends": "base.json",
"line-length": false
}
Then code like the following:
const options = {
"config": markdownlint.readConfigSync("./custom.json")
};
Merges custom.json
and base.json
and is equivalent to:
const options = {
"config": {
"default": true,
"line-length": false
}
};
options.frontMatter
Type: RegExp
Matches any front matter found at the
beginning of a file.
Some Markdown content begins with metadata; the default RegExp
for this option
ignores common forms of "front matter". To match differently, specify a custom
RegExp
or use the value null
to disable the feature.
The default value:
/((^---\s*$[^]*?^---\s*$)|(^\+\+\+\s*$[^]*?^(\+\+\+|\.\.\.)\s*$))(\r\n|\r|\n|$)/m
Ignores YAML and
TOML such as:
---
layout: post
title: Title
---
Note: Matches must occur at the start of the file.
options.handleRuleFailures
Type: Boolean
Catches exceptions thrown during rule processing and reports the problem as a
rule violation.
By default, exceptions thrown by rules (or the library itself) are unhandled
and bubble up the stack to the caller in the conventional manner. By setting
handleRuleFailures
to true
, exceptions thrown by failing rules will be
handled by the library and the exception message logged as a rule violation.
This setting can be useful in the presence of (custom) rules that encounter
unexpected syntax and fail. By enabling this option, the linting process is
allowed to continue and report any violations that were found.
options.noInlineConfig
Type: Boolean
Disables the use of HTML comments like <!-- markdownlint-disable -->
to toggle
rules within the body of Markdown content.
By default, properly-formatted inline comments can be used to create exceptions
for parts of a document. Setting noInlineConfig
to true
ignores all such
comments.
options.resultVersion
Type: Number
Specifies which version of the result
object to return (see the "Usage" section
below for examples).
Passing a resultVersion
of 0
corresponds to the original, simple format where
each error is identified by rule name and line number. This is deprecated.
Passing a resultVersion
of 1
corresponds to a detailed format where each error
includes information about the line number, rule name, alias, description, as well
as any additional detail or context that is available. This is deprecated.
Passing a resultVersion
of 2
corresponds to a detailed format where each error
includes information about the line number, rule names, description, as well as any
additional detail or context that is available. This is the default.
Passing a resultVersion
of 3
corresponds to the detailed version 2
format
with additional information about how to fix automatically-fixable errors. In this
mode, all errors that occur on each line are reported (other versions report only
the first error for each rule).
options.markdownItPlugins
Type: Array
of Array
of Function
and plugin parameters
Specifies additional markdown-it plugins
to use when parsing input. Plugins can be used to support additional syntax and
features for advanced scenarios.
Each item in the top-level Array
should be of the form:
[ require("markdown-it-plugin"), plugin_param_0, plugin_param_1, ... ]
callback
Type: Function
taking (Error
, Object
)
Standard completion callback.
result
Type: Object
Call result.toString()
for convenience or see below for an example of the
structure of the result
object. Passing the value true
to toString()
uses rule aliases (ex: no-hard-tabs
) instead of names (ex: MD010
).
Config
The options.config
configuration object is simple and can be stored in a file
for readability and easy reuse. The readConfig
and readConfigSync
functions
load configuration settings and support the extends
keyword for referencing
other files (see above).
By default, configuration files are parsed as JSON (and named .markdownlint.json
).
Custom parsers can be provided to handle other formats like JSONC, YAML, and TOML.
Asynchronous interface:
function readConfig(file, parsers, callback) { ... }
Synchronous interface:
function readConfigSync(file, parsers) { ... }
file
Type: String
Location of configuration file to read.
The file
is resolved relative to the current working directory. If an extends
key is present once read, its value will be resolved as a path relative to file
and loaded recursively. Settings from a file referenced by extends
are applied
first, then those of file
are applied on top (overriding any of the same keys
appearing in the referenced file).
parsers
Type: Optional Array
of Function
taking (String
) and returning Object
Array of functions to parse configuration files.
The contents of a configuration file are passed to each parser function until one
of them returns a value (vs. throwing an exception). Consequently, strict parsers
should come before flexible parsers.
For example:
[ JSON.parse, require("toml").parse, require("js-yaml").safeLoad ]
callback
Type: Function
taking (Error
, Object
)
Standard completion callback.
result
Type: Object
Configuration object.
Usage
Invoke markdownlint
and use the result
object's toString
method:
const markdownlint = require("markdownlint");
const options = {
"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."
}
};
markdownlint(options, function callback(err, result) {
if (!err) {
console.log(result.toString());
}
});
Output:
bad.string: 3: MD010/no-hard-tabs Hard tabs [Column: 19]
bad.string: 1: MD018/no-missing-space-atx No space after hash on atx style heading [Context: "#bad.string"]
bad.string: 3: MD018/no-missing-space-atx No space after hash on atx style heading [Context: "#This string fails some rules."]
bad.string: 1: MD041/first-line-heading/first-line-h1 First line in file should be a top level heading [Context: "#bad.string"]
bad.md: 3: MD010/no-hard-tabs Hard tabs [Column: 17]
bad.md: 1: MD018/no-missing-space-atx No space after hash on atx style heading [Context: "#bad.md"]
bad.md: 3: MD018/no-missing-space-atx No space after hash on atx style heading [Context: "#This file fails some rules."]
bad.md: 1: MD041/first-line-heading/first-line-h1 First line in file should be a top level heading [Context: "#bad.md"]
Or invoke markdownlint.sync
for a synchronous call:
const result = markdownlint.sync(options);
console.log(result.toString());
To examine the result
object directly:
markdownlint(options, function callback(err, result) {
if (!err) {
console.dir(result, { "colors": true, "depth": null });
}
});
Output:
{
"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/Rules.md#md010",
"errorDetail": "Column: 17",
"errorContext": null,
"errorRange": [ 17, 1 ] },
{ "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/Rules.md#md018",
"errorDetail": null,
"errorContext": "#bad.md",
"errorRange": [ 1, 2 ] },
{ "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/Rules.md#md018",
"errorDetail": null,
"errorContext": "#This file fails\tsome rules.",
"errorRange": [ 1, 2 ] },
{ "lineNumber": 1,
"ruleNames": [ "MD041", "first-line-heading", "first-line-h1" ],
"ruleDescription": "First line in file should be a top level heading",
"ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/Rules.md#md041",
"errorDetail": null,
"errorContext": "#bad.md",
"errorRange": null }
]
}
Integration with the gulp build system is straightforward:
const gulp = require("gulp");
const through2 = require("through2");
const markdownlint = require("markdownlint");
gulp.task("markdownlint", function task() {
return gulp.src("*.md", { "read": false })
.pipe(through2.obj(function obj(file, enc, next) {
markdownlint(
{ "files": [ file.relative ] },
function callback(err, result) {
const resultString = (result || "").toString();
if (resultString) {
console.log(resultString);
}
next(err, file);
});
}));
});
Output:
[00:00:00] Starting 'markdownlint'...
bad.md: 3: MD010/no-hard-tabs Hard tabs [Column: 17]
bad.md: 1: MD018/no-missing-space-atx No space after hash on atx style heading [Context: "#bad.md"]
bad.md: 3: MD018/no-missing-space-atx No space after hash on atx style heading [Context: "#This file fails some rules."]
bad.md: 1: MD041/first-line-heading/first-line-h1 First line in file should be a top level heading [Context: "#bad.md"]
[00:00:00] Finished 'markdownlint' after 10 ms
Integration with the Grunt build system is similar:
const markdownlint = require("markdownlint");
module.exports = function wrapper(grunt) {
grunt.initConfig({
"markdownlint": {
"example": {
"src": [ "*.md" ]
}
}
});
grunt.registerMultiTask("markdownlint", function task() {
const done = this.async();
markdownlint(
{ "files": this.filesSrc },
function callback(err, result) {
const resultString = err || ((result || "").toString());
if (resultString) {
grunt.fail.warn("\n" + resultString + "\n");
}
done(!err || !resultString);
});
});
};
Output:
Running "markdownlint:example" (markdownlint) task
Warning:
bad.md: 3: MD010/no-hard-tabs Hard tabs [Column: 17]
bad.md: 1: MD018/no-missing-space-atx No space after hash on atx style heading [Context: "#bad.md"]
bad.md: 3: MD018/no-missing-space-atx No space after hash on atx style heading [Context: "#This file fails some rules."]
bad.md: 1: MD041/first-line-heading/first-line-h1 First line in file should be a top level heading [Context: "#bad.md"]
Use --force to continue.
Browser
markdownlint
also works in the browser.
Generate normal and minified scripts with:
npm run build-demo
Then reference markdown-it
and markdownlint
:
<script src="demo/markdown-it.min.js"></script>
<script src="demo/markdownlint-browser.min.js"></script>
And call it like so:
const options = {
"strings": {
"content": "Some Markdown to lint."
}
};
const results = window.markdownlint.sync(options).toString();
Examples
For ideas how to integrate markdownlint
into your workflow, refer to the following projects:
Contributing
See CONTRIBUTING.md for more information.
History
- 0.0.1 - Initial release, includes tests MD001-MD032.
- 0.0.2 - Improve documentation, tests, and code.
- 0.0.3 - Add synchronous API, improve documentation and code.
- 0.0.4 - Add tests MD033-MD040, update dependencies.
- 0.0.5 - Add
strings
option to enable file-less scenarios, add in-browser demo. - 0.0.6 - Improve performance, simplify in-browser, update dependencies.
- 0.0.7 - Add MD041, improve MD003, ignore front matter, update dependencies.
- 0.0.8 - Support disabling/enabling rules inline, improve code fence, dependencies.
- 0.1.0 - Add aliases, exceptions for MD033, exclusions for MD013, dependencies.
- 0.1.1 - Fix bug handling HTML in tables, reference markdownlint-cli.
- 0.2.0 - Add MD042/MD043, enhance MD002/MD003/MD004/MD007/MD011/MD025/MD041, dependencies.
- 0.3.0 - More detailed error reporting with
resultVersion
, enhance MD010/MD012/MD036,
fixes for MD027/MD029/MD030, include JSON schema, dependencies.
- 0.3.1 - Fix regressions in MD032/MD038, update dependencies.
- 0.4.0 - Add MD044, enhance MD013/MD032/MD041/MD042/MD043, fix for MD038, dependencies.
- 0.4.1 - Fixes for MD038/front matter, improvements to MD044, update dependencies.
- 0.5.0 - Add shareable configuration,
noInlineConfig
option, README links, fix MD030,
improve MD009/MD041, update dependencies. - 0.6.0 -
resultVersion
defaults to 1 (breaking change), ignore HTML comments, TOML
front matter, fixes for MD044, update dependencies.
- 0.6.1 - Update
markdown-it
versioning, exclude demo/test from publishing. - 0.6.2 - Improve MD013/MD027/MD034/MD037/MD038/MD041/MD044, update dependencies.
- 0.6.3 - Improve highlighting for MD020.
- 0.6.4 - Improve MD029/MD042, update dependencies.
- 0.7.0 -
resultVersion
defaults to 2 (breaking change), add MD045, improve MD029,
remove trimLeft/trimRight, split rules, refactor, update dependencies. - 0.8.0 - Add support for using and authoring custom rules, improve MD004/MD007/MD013,
add
engines
to package.json
, refactor, update dependencies.
- 0.8.1 - Update item loop to be iterative, improve MD014, update dependencies.
- 0.9.0 - Remove support for end-of-life Node versions 0.10/0.12/4, change "header" to
"heading" per spec (non-breaking), improve MD003/MD009/MD041, handle uncommon
line-break characters, refactor for ES6, update dependencies.
- 0.10.0 - Add support for non-JSON configuration files, pass file/string name to custom
rules, update dependencies.
- 0.11.0 - Improve MD005/MD024/MD029/MD038, improve custom rule example, add CONTRIBUTING.md,
update dependencies.
- 0.12.0 - Add
information
link for custom rules, markdownItPlugins
for extensibility,
improve MD023/MD032/MD038, update dependencies. - 0.13.0 - Improve MD013/MD022/MD025/MD029/MD031/MD032/MD037/MD041/, deprecate MD002,
improve pandoc YAML support, update dependencies.
- 0.14.0 - Remove support for end-of-life Node version 6, introduce
markdownlint-rule-helpers
,
add MD046/MD047, improve MD033/MD034/MD039, improve custom rule validation and
in-browser demo, update dependencies.
- 0.14.1 - Improve MD033.
- 0.14.2 - Improve MD047, add
handleRuleFailures
option.
- 0.15.0 - Add
markdownlint-capture
/markdownlint-restore
inline comments, improve
MD009/MD013/MD026/MD033/MD036, update dependencies. - 0.16.0 - Add custom rule sample for linting code, improve MD026/MD031/MD033/MD038,
update dependencies.
- 0.17.0 - Add
resultVersion
3 to support fix information for default and custom rules,
add fix information for 24 rules, update newline handling to match latest
CommonMark specification, improve MD014/MD037/MD039, update dependencies.
- 0.17.1 - Fix handling of front matter by fix information.
- 0.17.2 - Improve MD020/MD033/MD044.