markdownlint Documentation

File: README.md

markdownlint

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

Install

bash

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.)

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
Editor
Tooling
Ruby
- markdownlint/mdl gem for Ruby

References

The following specifications are considered authoritative in cases of ambiguity:

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.

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:

markdown

space * in * emphasis

Or:

markdown

space * in * emphasis

Or:

markdown

space * in * emphasis

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

markdown

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:

markdown

any violations you want

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

markdown

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:

markdown

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.

API

Linting

Asynchronous API via import { lint } from "markdownlint/async":

javascript

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

Synchronous API via import { lint } from "markdownlint/sync":

javascript

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

Promise API via import { lint } from "markdownlint/promise":

javascript

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

options

Type: Object

Configures the function. All properties are optional, but at least one
of files or strings should be set to provide input.

options.config

Type: Object mapping String to Boolean | "error" | "warning" | Object

Configures the rules to use.

Object keys are rule names/aliases; object values are the rule's configuration.
The value false disables a rule. The values true or "error" enable a rule
in its default configuration and report violations as errors. The value
"warning" enables a rule in its default configuration and reports violations
as warnings. Passing an object enables and customizes the rule; the properties
severity ("error" | "warning") and enabled (false | true) can be used in
this context. The special default rule assigns the default for all rules.
Using a tag name (e.g., whitespace) and a setting of false, true,
"error", or "warning" applies that setting to all rules with that tag. When
no configuration object is passed or the optional default setting is not
present, all rules are enabled.

The following syntax disables the specified rule, tag, or default:

javascript

{
  "rule_tag_or_default": false
}

The following syntax enables the specified rule, tag, or default to report
violations as errors:

javascript

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

The following syntax enables the specified rule, tag, or default to report
violations as warnings:

javascript

{
  "rule_tag_or_default": "warning"
}

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

javascript

{
  "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 report
violations as warnings:

javascript

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

Note that values "error" and "warning" and the property severity are not
supported by library versions earlier than 0.39.0. However, the examples
above behave the same there, with warnings being reported as errors.

The following syntax disables and configures the specified rule:

javascript

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

Note that this example behaves differently with library versions earlier
than 0.39.0 because the property enabled is not supported: it enables
the rule instead of disabling it. As such, this syntax is discouraged when
interoperability is important.

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

Example using default, rule names, and tag names together:

json

{
  "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 of referencing a built-in style from JavaScript:

javascript

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

Example doing so from .markdownlint.json via extends (more on this below):

json

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

See the style directory for more samples.

See markdownlint-config-schema.json
for the JSON Schema of the options.config
object.

See ValidatingConfiguration.md for ways to
use the JSON Schema to validate configuration.

For more advanced scenarios, styles can reference and build upon other styles
via the extends keyword and a file path or (installed) package name. The
readConfig function can be used to read such aggregate styles from code.

For example, assuming a base.json configuration file:

json

{
  "default": true
}

And a custom.json configuration file:

json

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

Then code like the following:

javascript

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

Merges custom.json and base.json and is equivalent to:

javascript

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

options.configParsers

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:

javascript

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

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 locally.

Example:

javascript

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

javascript

/((^---[^\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

Ignores YAML,
TOML, and
JSON front matter such as:

text

---
layout: post
title: Title
---

Note: Matches must occur at the start of the file.

options.fs

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 using node:fs.

Note: The only methods called are readFile and readFileSync.

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.markdownItFactory

Type: Function returning an instance of a markdown-it parser

Provides a factory function for creating instances of the markdown-it parser.

Previous versions of the markdownlint library declared markdown-it as a
direct dependency. This function makes it possible to avoid that dependency
entirely. In cases where markdown-it is needed, the caller is responsible for
declaring the dependency and returning an instance from this factory. If any
markdown-it plugins are needed, they should be used by
the caller before returning the markdown-it instance.

For compatibility with previous versions of markdownlint, this function should
be similar to:

javascript

import markdownIt from "markdown-it";
const markdownItFactory = () => markdownIt({ "html": true });

When an asynchronous implementation of lint is being invoked (e.g., via
markdownlint/async or markdownlint/promise), this function can return a
Promise in order to defer the import of markdown-it:

javascript

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

Note that this function is only invoked when a markdown-it parser is
needed. None of the built-in rules use the markdown-it parser, so it is only
invoked when one or more custom rules are present that use the
markdown-it parser.

options.noInlineConfig

Type: Boolean

Disables the use of HTML comments like `` 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.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:

json

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

callback

Type: Function taking (Error, Object)

Standard completion callback.

result

Type: Object

Map of input file names and string identifiers to issues within.

See the Usage section for an example of the structure of this object.

Config

The options.config configuration object is simple and can be stored in a file
for readability and easy reuse. The readConfig function loads configuration
settings and supports the extends keyword for referencing files or packages
(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 via import { readConfig } from "markdownlint/async":

javascript

/**
 * 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 via import { readConfig } from "markdownlint/sync":

javascript

/**
 * 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.
 */
function readConfig(file, parsers, fs) { ... }

Promise API via import { readConfig } from "markdownlint/promise":

javascript

/**
 * 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) { ... }

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). If either the file or
extends path begins with the ~ directory, it will act as a placeholder for
the home directory.

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:

javascript

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

fs

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 node:fs.

Note: The only methods called are readFile, readFileSync, access, and
accessSync.

callback

Type: Function taking (Error, Object)

Standard completion callback.

result

Type: Object

Configuration object.

Fixing

Rules that can be fixed automatically include a fixInfo property which is
outlined in the documentation for custom rules.
To apply fixes consistently, the applyFix/applyFixes methods may be used via
import { applyFix, applyFixes } from "markdownlint":

javascript

/**
 * 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.
 */
function applyFix(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.
 */
function applyFixes(input, errors) { ... }

Invoking applyFixes with the results of a call to lint can be done like so:

javascript

import { applyFixes } from "markdownlint";
import { lint as lintSync } from "markdownlint/sync";

const results = lintSync({ "strings": { "content": original } });
const fixed = applyFixes(original, results.content);

Miscellaneous

To get the semantic version of the library, the getVersion method
can be used:

javascript

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

Invoking getVersion is simple:

javascript

import { getVersion } from "markdownlint";

// Displays the library version
console.log(getVersion());

Usage

Invoke lint as an asynchronous call:

javascript

import { lint as lintAsync } from "markdownlint/async";

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."
  }
};

lintAsync(options, function callback(error, results) {
  if (!error && results) {
    console.dir(results, { "colors": true, "depth": null });
  }
});

Or as a synchronous call:

javascript

import { lint as lintSync } from "markdownlint/sync";

const results = lintSync(options);
console.dir(results, { "colors": true, "depth": null });

Or as a Promise-based call:

javascript

import { lint as lintPromise } from "markdownlint/promise";

const results = await lintPromise(options);
console.dir(results, { "colors": true, "depth": null });

All of which return an object like:

json

{
  "good.md": [],
  "bad.md": [
    { "lineNumber": 3,
      "ruleNames": [ "MD010", "no-hard-tabs" ],
      "ruleDescription": "Hard tabs",
      "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.41.1/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.41.1/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.41.1/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.41.1/doc/md041.md",
      "errorDetail": null,
      "errorContext": "#bad.md",
      "errorRange": null,
      "fixInfo": null,
      "severity": "error" }
  ]
}

Browser

markdownlint also works in the browser.

Generate normal and minified scripts with:

bash

npm run build-demo

Then reference the markdownlint-browser script:

html

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

And call it like so:

javascript

const options = {
  "strings": {
    "content": "Some Markdown to lint."
  }
};

const results = globalThis.markdownlint.lintSync(options);

Examples

For ideas how to integrate markdownlint into your workflow, refer to the
following projects or one of the tools in the Related section:

.NET Documentation (Search repository)
ally.js (Search repository)
Apache Airflow (Search repository)
CodiMD (Search repository)
Electron (Search repository)
ESLint (Search repository)
Garden React Components (Search repository)
MDN Web Docs (Search repository)
MkDocs (Search repository)
Pi-hole documentation (Search repository)
Reactable (Search repository)
V8 (Search repository)
webhint (Search repository)
webpack (Search repository)
WordPress (Search repository)

For more advanced integration scenarios:

Contributing

See CONTRIBUTING.md for more information.

Releasing

See ReleaseProcess.md for more information.

History

See CHANGELOG.md.

File: doc/CustomRules.md

Custom Rules

In addition to its built-in rules, markdownlint lets you enhance the linting
experience by passing an array of custom rules using the options.customRules
property. Custom rules can do everything the built-in
rules can and are defined inline or imported from another package (keyword
markdownlint-rule on npm). When defined by a file or
package, the export can be a single rule object (see below) or an array of them.
Custom rules can be disabled, enabled, and customized using the same syntax as
built-in rules.

Implementing Simple Rules

For simple requirements like disallowing certain characters or patterns,
the community-developed
markdownlint-rule-search-replace
plug-in can be used. This plug-in allows anyone to create a set of simple
text-replacement rules without needing to write code.

Authoring

Rules are defined by a name (or multiple names), a description, an optional link
to more information, one or more tags, and a function that implements the rule's
behavior. That function is called once for each file/string input and is passed
the parsed input and a function to log any violations.

Custom rules can (should) operate on a structured set of tokens based on the
micromark parser (this is preferred). Alternatively, custom
rules can operate on a structured set of tokens based on the
markdown-it parser (legacy support). Finally, custom rules
can operate directly on text with the none parser.

A simple rule implementation using the micromark parser to report a violation
for any use of blockquotes might look like:

javascript

/** @type {import("markdownlint").Rule} */
module.exports = {
  "names": [ "any-blockquote-micromark" ],
  "description": "Rule that reports an error for any blockquote",
  "information": new URL("https://example.com/rules/any-blockquote"),
  "tags": [ "test" ],
  "parser": "micromark",
  "function": (params, onError) => {
    const blockquotes = params.parsers.micromark.tokens
      .filter((token) => token.type === "blockQuote");
    for (const blockquote of blockquotes) {
      const lines = blockquote.endLine - blockquote.startLine + 1;
      onError({
        "lineNumber": blockquote.startLine,
        "detail": "Blockquote spans " + lines + " line(s).",
        "context": params.lines[blockquote.startLine - 1]
      });
    }
  }
}

That same rule implemented using the markdown-it parser might look like:

javascript

/** @type {import("markdownlint").Rule} */
module.exports = {
  "names": [ "any-blockquote-markdown-it" ],
  "description": "Rule that reports an error for any blockquote",
  "information": new URL("https://example.com/rules/any-blockquote"),
  "tags": [ "test" ],
  "parser": "markdownit",
  "function": (params, onError) => {
    const blockquotes = params.parsers.markdownit.tokens
      .filter((token) => token.type === "blockquote_open");
    for (const blockquote of blockquotes) {
      const [ startIndex, endIndex ] = blockquote.map;
      const lines = endIndex - startIndex;
      onError({
        "lineNumber": blockquote.lineNumber,
        "detail": "Blockquote spans " + lines + " line(s).",
        "context": blockquote.line
      });
    }
  }
}

A rule is implemented as an Object:

names is a required Array of String values that identify the rule in
output messages and config.
description is a required String value that describes the rule in output
messages.
information is an optional (absolute) URL of a link to more information
about the rule.
tags is a required Array of String values that groups related rules for
easier customization.
parser is a required String value "markdownit" | "micromark" | "none"
that specifies the parser data used via params.parsers (see below).
asynchronous is an optional Boolean value that indicates whether the rule
returns a Promise and runs asynchronously.
function is a required Function that implements the rule and is passed two
parameters:
- params is an Object with properties that describe the content being
  analyzed:
  - name is a String that identifies the input file/string.
  - parsers is an Object with properties corresponding to the value of
    parser in the rule definition (see above).
    - markdownit is an Object that provides access to output from the
      markdown-it parser.
      - tokens is an Array of markdown-it Tokens
        with added line and lineNumber properties. (This property was
        previously on the params object.)
    - micromark is an Object that provides access to output from the
      micromark parser.
      - tokens is an Array of MicromarkToken objects.
    - Samples for both tokens are available via test snapshots.
  - lines is an Array of String values corresponding to the lines of the
    input file/string.
  - frontMatterLines is an Array of String values corresponding to any
    front matter (not present in lines).
  - config is an Object corresponding to the rule's entry in
    options.config (if present).
  - version is a String that corresponds to the version of markdownlint
- onError is a function that takes a single Object parameter with one
  required and four optional properties:
  - lineNumber is a required Number specifying the 1-based line number of
    the error.
  - detail is an optional String with information about what caused the
    error.
  - context is an optional String with relevant text surrounding the error
    location.
  - information is an optional (absolute) URL of a link to override the
    same-named value provided by the rule definition. (Uncommon)
  - range is an optional Array with two Number values identifying the
    1-based column and length of the error.
  - fixInfo is an optional Object with information about how to fix the
    error (all properties are optional, but at least one of deleteCount and
    insertText should be present; when applying a fix, the delete should be
    performed before the insert):
    - lineNumber is an optional Number specifying the 1-based line number
      of the edit.
    - editColumn is an optional Number specifying the 1-based column
      number of the edit.
    - deleteCount is an optional Number specifying the number of
      characters to delete (the value -1 is used to delete the line).
    - insertText is an optional String specifying the text to insert. \n
      is the platform-independent way to add a line break; line breaks should
      be added at the beginning of a line instead of at the end.

The collection of helper functions shared by the built-in rules is available for
use by custom rules in the markdownlint-rule-helpers package.

Asynchronous Rules

If a rule needs to perform asynchronous operations (such as fetching a network
resource), it can specify the value true for its asynchronous property.
Asynchronous rules should return a Promise from their function
implementation that is resolved when the rule completes. (The value passed to
resolve(...) is ignored.) Linting violations from asynchronous rules are
reported via the onError function just like for synchronous rules.

Note: Asynchronous rules cannot be referenced in a synchronous calling
context (i.e., import { lint } from "markdownlint/sync"). Attempting to do so
throws an exception.

Examples

References

File: doc/md001.md

`MD001` - Heading levels should only increment by one level at a time

Tags: headings

Aliases: heading-increment

Parameters:

front_matter_title: RegExp for matching title in front matter (string,
default ^\s*title\s*[:=])

This rule is triggered when you skip heading levels in a Markdown document, for
example:

markdown

# Heading 1

### Heading 3

We skipped out a 2nd level heading in this document

When using multiple heading levels, nested headings should increase by only one
level at a time:

markdown

# Heading 1

## Heading 2

### Heading 3

#### Heading 4

## Another Heading 2

### Another Heading 3

If YAML front matter is present and
contains a title property (commonly used with blog posts), this rule treats
that as a top level heading and will report a violation if the actual first
heading is not a level 2 heading. To use a different property name in the
front matter, specify the text of a regular expression via the
front_matter_title parameter. To disable the use of front matter by this
rule, specify "" for front_matter_title. When front matter is not present,
the first heading can be any level.

Rationale: Headings represent the structure of a document and can be confusing
when skipped - especially for accessibility scenarios. More information:
https://www.w3.org/WAI/tutorials/page-structure/headings/.

File: doc/md003.md

`MD003` - Heading style

Tags: headings

Aliases: heading-style

Parameters:

style: Heading style (string, default consistent, values atx /
atx_closed / consistent / setext / setext_with_atx /
setext_with_atx_closed)

This rule is triggered when different heading styles are used in the same
document:

markdown

# ATX style H1

## Closed ATX style H2 ##

Setext style H1
===============

To fix the issue, use consistent heading styles throughout the document:

markdown

# ATX style H1

## ATX style H2

The setext_with_atx and setext_with_atx_closed settings allow ATX-style
headings of level 3 or more in documents with setext-style headings (which only
support level 1 and 2 headings):

markdown

Setext style H1
===============

Setext style H2
---------------

### ATX style H3

Note: The configured heading style can be a specific style to require (atx,
atx_closed, setext, setext_with_atx, setext_with_atx_closed), or can
require that all heading styles match the first heading style via consistent.

Note: The placement of a horizontal rule directly below a line of text can
trigger this rule by turning that text into a level 2 setext-style heading:

markdown

A line of text followed by a horizontal rule becomes a heading
---

Rationale: Consistent formatting makes it easier to understand a document.

File: doc/md004.md

`MD004` - Unordered list style

Tags: bullet, ul

Aliases: ul-style

Parameters:

style: List style (string, default consistent, values asterisk /
consistent / dash / plus / sublist)

Fixable: Some violations can be fixed by tooling

This rule is triggered when the symbols used in the document for unordered
list items do not match the configured unordered list style:

markdown

* Item 1
+ Item 2
- Item 3

To fix this issue, use the configured style for list items throughout the
document:

markdown

* Item 1
* Item 2
* Item 3

The configured list style can ensure all list styling is a specific symbol
(asterisk, plus, dash), ensure each sublist has a consistent symbol that
differs from its parent list (sublist), or ensure all list styles match the
first list style (consistent).

For example, the following is valid for the sublist style because the
outer-most indent uses asterisk, the middle indent uses plus, and the inner-most
indent uses dash:

markdown

* Item 1
  + Item 2
    - Item 3
  + Item 4
* Item 4
  + Item 5

Rationale: Consistent formatting makes it easier to understand a document.

File: doc/md005.md

`MD005` - Inconsistent indentation for list items at the same level

Tags: bullet, indentation, ul

Aliases: list-indent

Fixable: Some violations can be fixed by tooling

This rule is triggered when list items are parsed as being at the same level,
but don't have the same indentation:

markdown

* Item 1
  * Nested Item 1
  * Nested Item 2
   * A misaligned item

Usually, this rule will be triggered because of a typo. Correct the indentation
for the list to fix it:

markdown

* Item 1
  * Nested Item 1
  * Nested Item 2
  * Nested Item 3

Sequentially-ordered list markers are usually left-aligned such that all items
have the same starting column:

markdown

...
8. Item
9. Item
10. Item
11. Item
...

This rule also supports right-alignment of list markers such that all items have
the same ending column:

markdown

...
 8. Item
 9. Item
10. Item
11. Item
...

Rationale: Violations of this rule can lead to improperly rendered content.

File: doc/md007.md

`MD007` - Unordered list indentation

Tags: bullet, indentation, ul

Aliases: ul-indent

Parameters:

indent: Spaces for indent (integer, default 2)
start_indent: Spaces for first level indent (when start_indented is set)
(integer, default 2)
start_indented: Whether to indent the first level of the list (boolean,
default false)

Fixable: Some violations can be fixed by tooling

This rule is triggered when list items are not indented by the configured
number of spaces (default: 2).

Example:

markdown

* List item
   * Nested list item indented by 3 spaces

Corrected Example:

markdown

* List item
  * Nested list item indented by 2 spaces

Note: This rule applies to a sublist only if its parent lists are all also
unordered (otherwise, extra indentation of ordered lists interferes with the
rule).

The start_indented parameter allows the first level of lists to be indented by
the configured number of spaces rather than starting at zero. The start_indent
parameter allows the first level of lists to be indented by a different number
of spaces than the rest (ignored when start_indented is not set).

Rationale: Indenting by 2 spaces allows the content of a nested list to be in
line with the start of the content of the parent list when a single space is
used after the list marker. Indenting by 4 spaces is consistent with code blocks
and simpler for editors to implement. Additionally, this can be a compatibility
issue for other Markdown parsers, which require 4-space indents. More
information: Markdown Style Guide.

Note: See Prettier.md for compatibility information.

File: doc/md009.md

`MD009` - Trailing spaces

Tags: whitespace

Aliases: no-trailing-spaces

Parameters:

br_spaces: Spaces for line break (integer, default 2)
code_blocks: Include code blocks (boolean, default false)
list_item_empty_lines: Allow spaces for empty lines in list items
(boolean, default false)
strict: Include unnecessary breaks (boolean, default false)

Fixable: Some violations can be fixed by tooling

This rule is triggered on any lines that end with unexpected whitespace. To fix
this, remove the trailing space from the end of the line.

The br_spaces parameter allows an exception to this rule for a specific number
of trailing spaces, typically used to insert an explicit line break. The default
value allows 2 spaces to indicate a hard break (\ element). (You must set
br_spaces to a value >= 2 for this parameter to take effect. Setting
br_spaces to 1 behaves the same as 0, disallowing any trailing spaces.)

By default, trailing space is allowed in indented and fenced code blocks because
some programming languages require that. To report such instances, set the
code_blocks parameter to true.

By default, this rule will not trigger when the allowed number of spaces is
used, even when it doesn't create a hard break (for example, at the end of a
paragraph). To report such instances, set the strict parameter to true.

markdown

Text text text
text[2 spaces]

Using spaces to indent blank lines inside a list item is usually not necessary,
but some parsers require it. Set the list_item_empty_lines parameter to true
to allow this (even when strict is true):

markdown

- list item text
  [2 spaces]
  list item text

Rationale: Except when being used to create a line break, trailing whitespace
has no purpose and does not affect the rendering of content.

File: doc/md010.md

`MD010` - Hard tabs

Tags: hard_tab, whitespace

Aliases: no-hard-tabs

Parameters:

code_blocks: Include code blocks (boolean, default true)
ignore_code_languages: Fenced code languages to ignore (string[], default
[])
spaces_per_tab: Number of spaces for each hard tab (integer, default 1)

Fixable: Some violations can be fixed by tooling

This rule is triggered by any lines that contain hard tab characters instead
of using spaces for indentation. To fix this, replace any hard tab characters
with spaces instead.

Example:

markdown

Some text

	* hard tab character used to indent the list item

Corrected example:

markdown

Some text

    * Spaces used to indent the list item instead

You have the option to exclude this rule for code blocks and spans. To do so,
set the code_blocks parameter to false. Code blocks and spans are included
by default since handling of tabs by Markdown tools can be inconsistent (e.g.,
using 4 vs. 8 spaces).

When code blocks are scanned (e.g., by default or if code_blocks is true),
the ignore_code_languages parameter can be set to a list of languages that
should be ignored (i.e., hard tabs will be allowed, though not required). This
makes it easier for documents to include code for languages that require hard
tabs.

By default, violations of this rule are fixed by replacing the tab with 1 space
character. To use a different number of spaces, set the spaces_per_tab
parameter to the desired value.

Rationale: Hard tabs are often rendered inconsistently by different editors and
can be harder to work with than spaces.

More information:

File: doc/md011.md

`MD011` - Reversed link syntax

Tags: links

Aliases: no-reversed-links

Fixable: Some violations can be fixed by tooling

This rule is triggered when text that appears to be a link is encountered, but
where the syntax appears to have been reversed (the [] and () are
reversed):

markdown

(Incorrect link syntax)[https://www.example.com/]

To fix this, swap the [] and () around:

markdown

[Correct link syntax](https://www.example.com/)

Note: Markdown Extra-style
footnotes do not trigger this rule:

markdown

For (example)[^1]

Rationale: Reversed links are not rendered as usable links.

File: README.md Copy Chapter

markdownlint

Install Copy Chapter

Overview Copy Chapter

Related Copy Section

References Copy Section

Demonstration Copy Chapter

Rules / Aliases Copy Chapter

Custom Rules Copy Section

Tags Copy Chapter

Configuration Copy Chapter

API Copy Chapter

Linting Copy Section

options

options.config

options.configParsers

options.customRules

options.files

options.frontMatter

options.fs

options.handleRuleFailures

options.markdownItFactory

options.noInlineConfig

options.strings

callback

result

Config Copy Section

file

parsers

fs

callback

result

Fixing Copy Section

Miscellaneous Copy Section

Usage Copy Chapter

Browser Copy Chapter

Examples Copy Chapter

Contributing Copy Chapter

Releasing Copy Chapter

History Copy Chapter

File: doc/CustomRules.md Copy Chapter

Custom Rules

Implementing Simple Rules Copy Chapter

Authoring Copy Chapter

Asynchronous Rules Copy Section

Examples Copy Chapter

References Copy Chapter

File: doc/md001.md Copy Chapter

`MD001` - Heading levels should only increment by one level at a time

File: doc/md003.md Copy Chapter

`MD003` - Heading style

File: doc/md004.md Copy Chapter

`MD004` - Unordered list style

File: doc/md005.md Copy Chapter

`MD005` - Inconsistent indentation for list items at the same level

File: doc/md007.md Copy Chapter

`MD007` - Unordered list indentation

File: doc/md009.md Copy Chapter

`MD009` - Trailing spaces

File: doc/md010.md Copy Chapter

`MD010` - Hard tabs

File: doc/md011.md Copy Chapter

`MD011` - Reversed link syntax

Explore Related Technologies & Topics

File: README.md

Install

Overview

Related

References

Demonstration

Rules / Aliases

Custom Rules

Tags

Configuration

API

Linting

Config

Fixing

Miscellaneous

Usage

Browser

Examples

Contributing

Releasing

History

File: doc/CustomRules.md

Implementing Simple Rules

Authoring

Asynchronous Rules

Examples

References

File: doc/md001.md

File: doc/md003.md

File: doc/md004.md

File: doc/md005.md

File: doc/md007.md

File: doc/md009.md

File: doc/md010.md

File: doc/md011.md