markdownlint
Advanced tools
markdownlint is a Node.js package that provides a linter for Markdown files. It helps ensure that Markdown files adhere to a consistent style and are free from common errors. The package can be used programmatically or via the command line, and it supports custom rules and configurations.
Linting Markdown Files
This feature allows you to lint Markdown files to ensure they follow specified rules. The code sample demonstrates how to lint a file named 'README.md' with a custom configuration that disables the 'MD013' rule.
const markdownlint = require('markdownlint');
const options = {
files: [ 'README.md' ],
config: {
'default': true,
'MD013': false
}
};
markdownlint(options, function callback(err, result) {
if (!err) {
console.log(result.toString());
}
});Custom Rules
This feature allows you to define and use custom rules for linting. The code sample shows how to include custom rules from a file named 'custom-rules.js' and apply them to 'README.md'.
const markdownlint = require('markdownlint');
const customRules = require('./custom-rules');
const options = {
files: [ 'README.md' ],
customRules: customRules
};
markdownlint(options, function callback(err, result) {
if (!err) {
console.log(result.toString());
}
});Command Line Interface
markdownlint can be used via the command line to lint files. The code sample demonstrates how to lint 'README.md' using a configuration file named '.markdownlint.json'.
markdownlint README.md --config .markdownlint.jsonremark-lint is a Markdown code style linter built on the remark processor. It is highly customizable and can be extended with plugins. Compared to markdownlint, remark-lint offers a more modular approach and integrates well with the unified ecosystem.
markdown-it is a Markdown parser that can be extended with plugins to add linting capabilities. While it is primarily a parser, its extensibility allows for custom linting rules. It is more flexible but requires additional setup compared to markdownlint.
markdownlint-cli is a command-line interface for markdownlint. It provides similar functionality to markdownlint but is specifically designed for use in the command line. It is a good choice if you prefer a CLI tool over a programmatic API.
A Node.js style checker and lint tool for Markdown/CommonMark files.
npm install markdownlint --save-dev
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.
markdownlint demo, an interactive, in-browser
playground for learning and exploring.
See Rules.md for more details.
Struck through rules are deprecated, and provided for backward-compatibility.
All rules with
headingas part of their name are also available asheaderaliases (e.g.heading-incrementis also available asheader-increment). The use ofheaderis deprecated and provided for backward-compatibility.
Tags group related rules and can be used to enable/disable multiple rules at once.
Text passed to markdownlint is parsed as Markdown, analyzed, and any
issues reported. Two kinds of text are ignored:
options.frontMatter below)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):
<!-- markdownlint-disable --><!-- markdownlint-enable --><!-- markdownlint-disable-line --><!-- markdownlint-disable-next-line --><!-- markdownlint-disable MD001 MD005 --><!-- markdownlint-enable MD001 MD005 --><!-- markdownlint-disable-line MD001 MD005 --><!-- markdownlint-disable-next-line MD001 MD005 --><!-- markdownlint-capture --><!-- markdownlint-restore -->For example:
<!-- markdownlint-disable-next-line no-space-in-emphasis -->
deliberate space * in * emphasis
Or:
deliberate space * in * emphasis <!-- markdownlint-disable-line no-space-in-emphasis -->
Or:
<!-- 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 -->
To apply changes to an entire file regardless of where the comment is located, the following syntax is supported:
<!-- markdownlint-disable-file --><!-- markdownlint-enable-file --><!-- markdownlint-disable-file MD001 --><!-- 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 or more rules for a file, the following more advanced syntax is supported:
<!-- markdownlint-configure-file { options.config JSON } -->For example:
<!-- markdownlint-configure-file { "MD013": { "code_blocks": false } } -->
or
<!-- markdownlint-configure-file
{
"hr-style": {
"style": "---"
},
"no-trailing-spaces": false
}
-->
These changes apply to the entire file regardless of where the comment is
located. Multiple such comments (if present) are applied top-to-bottom. By
default, content of markdownlint-configure-file is assumed to be JSON, but
options.configParsers can be used to support
alternate formats.
Standard asynchronous API:
/**
* Lint specified Markdown files.
*
* @param {Options} options Configuration options.
* @param {LintCallback} callback Callback (err, result) function.
* @returns {void}
*/
function markdownlint(options, callback) { ... }
Synchronous API (for build scripts, etc.):
/**
* Lint specified Markdown files synchronously.
*
* @param {Options} options Configuration options.
* @returns {LintResults} Results object.
*/
function markdownlint.sync(options) { ... }
Promise API (in the promises namespace like Node.js's
fs Promises API):
/**
* Lint specified Markdown files.
*
* @param {Options} options Configuration options.
* @returns {Promise<LintResults>} Results object.
*/
function markdownlint(options) { ... }
Type: Object
Configures the function. All properties are optional, but at least one
of files or strings should be set to provide input.
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
}
See .markdownlint.jsonc and/or .markdownlint.yaml for an example configuration object with all properties set to the default value.
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
}
};
Type: Optional Array of Function taking (String) and returning Object
Array of functions to parse the content of markdownlint-configure-file blocks.
As shown in the Configuration section, inline comments can be
used to customize the configuration object for a document. By
default, the JSON.parse built-in is used, but custom parsers can be specified.
Content is passed to each parser function until one returns a value (vs. throwing
an exception). As such, strict parsers should come before flexible ones.
For example:
[ JSON.parse, require("toml").parse, require("js-yaml").load ]
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 locally. Custom rules are
identified by the
keyword markdownlint-rule on npm.
Example:
const extraRules = require("extraRules");
const options = {
"customRules": [ extraRules.one, extraRules.two ]
};
See CustomRules.md for details about authoring custom rules.
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" ]
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*$)|(^\{\s*$[^]*?^\}\s*$))(\r\n|\r|\n|$)/m
Ignores YAML, TOML, and JSON front matter such as:
---
layout: post
title: Title
---
Note: Matches must occur at the start of the file.
Type: Object implementing the file system API
In advanced scenarios, it may be desirable to bypass the default file system API.
If a custom file system implementation is provided, markdownlint will use that
instead of invoking require("fs").
Note: The only methods called are readFile and readFileSync.
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.
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, ... ]
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.
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 deprecated.
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). This is the default.
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..."
}
Type: Function taking (Error, Object)
Standard completion callback.
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).
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 API:
/**
* 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}
*/
function readConfig(file, parsers, fs, callback) { ... }
Synchronous API:
/**
* Read specified configuration file synchronously.
*
* @param {string} file Configuration file name.
* @param {ConfigurationParser[]} [parsers] Parsing function(s).
* @param {Object} [fs] File system implementation.
* @returns {Configuration} Configuration object.
*/
function readConfigSync(file, parsers, fs) { ... }
Promise API (in the promises namespace like Node.js's
fs Promises API):
/**
* 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.
*/
function readConfig(file, parsers, fs) { ... }
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). If either the file or extends path begins
with the ~ directory, it will act as a placeholder for the home directory.
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").load ]
Type: Optional Object implementing the file system API
In advanced scenarios, it may be desirable to bypass the default file system API.
If a custom file system implementation is provided, markdownlint will use that
instead of invoking require("fs").
Note: The only methods called are readFile, readFileSync, access, and accessSync.
Type: Function taking (Error, Object)
Standard completion callback.
Type: Object
Configuration object.
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 a 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 a 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 a 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 a 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 a file should be a top-level heading [Context: "#bad.md"]
Use --force to continue.
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();
For ideas how to integrate markdownlint into your workflow, refer to the
following projects or one of the tools in the Related section:
See CONTRIBUTING.md for more information.
strings option to enable file-less scenarios, add in-browser demo.resultVersion, enhance MD010/MD012/MD036,
fixes for MD027/MD029/MD030, include JSON schema, dependencies.
noInlineConfig option, README links, fix MD030,
improve MD009/MD041, update dependencies.resultVersion defaults to 1 (breaking change), ignore HTML comments, TOML
front matter, fixes for MD044, update dependencies.
markdown-it versioning, exclude demo/test from publishing.resultVersion defaults to 2 (breaking change), add MD045, improve MD029,
remove trimLeft/trimRight, split rules, refactor, update dependencies.engines to package.json, refactor, update dependencies.
information link for custom rules, markdownItPlugins for extensibility,
improve MD023/MD032/MD038, update dependencies.markdownlint-rule-helpers,
add MD046/MD047, improve MD033/MD034/MD039, improve custom rule validation and
in-browser demo, update dependencies.
handleRuleFailures option.markdownlint-capture/markdownlint-restore inline comments, improve
MD009/MD013/MD026/MD033/MD036, update dependencies.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.
markdownlint-disable-file/markdownlint-enable-file inline comments, add
type declaration file (.d.ts) for TypeScript dependents, update schema, improve
MD006/MD007/MD009/MD013/MD030, update dependencies.markdownlint-configure-file inline comment, reimplement MD037,
improve MD005/MD007/MD013/MD018/MD029/MD031/MD034/MD038/MD039, improve HTML
comment handling, update dependencies.
toString on LintResults, add ability
to fix in browser demo, allow custom rules in .markdownlint.json schema, improve
MD042/MD044, improve documentation, update dependencies.
getVersion API.extends in config to reference installed packages by name, add
markdownlint-disable-next-line inline comment, support JSON front matter, improve
MD009/MD026/MD028/MD043, update dependencies (including markdown-it to v12)..markdownlint.jsonc/.markdownlint.yaml files, add fix
information for MD004/ul-style, improve MD018/MD019/MD020/MD021/MD037/MD041, improve
HTML comment handling, update test runner and test suite, update dependencies.
require (.resolve).markdownlint-disable-line
inline comment, support ~ paths in readConfig/Sync, add configParsers option,
remove support for end-of-life Node version 12, default resultVersion to 3, update
browser script to use ES2015, simplify JSON schema, address remaining CodeQL issues,
improve performance, update dependencies.
FAQs
A Node.js style checker and lint tool for Markdown/CommonMark files.
The npm package markdownlint receives a total of 487,239 weekly downloads. As such, markdownlint popularity was classified as popular.
We found that markdownlint demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.
Security News
Research
Socket's threat research team has detected five malicious npm packages targeting Roblox developers, deploying malware to steal credentials and personal data.
Security News
vlt introduced its new package manager and a serverless registry this week, innovating in a space where npm has stagnated.