GitHub - DavidAnson/markdownlint: A Node.js style checker and lint tool for Markdown/CommonMark files. (original) (raw)

markdownlint

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

npm version License

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.

markdownlint is a static analysis tool forNode.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 theCommonMark 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 bymicromark extensions.

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

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 usekeyword markdownlint-rule on npm. To implement your own rules, refer to CustomRules.md.

Tags

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

Configuration

Text passed to markdownlint is parsed as Markdown, analyzed, and any issues reported. Two kinds of text are ignored by most rules:

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

For example:

space * in * emphasis

Or:

space * in * emphasis

Or:

space * in * emphasis

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

any violations you want

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

any violations you want

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

space * in * emphasis

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

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:

For example:

or

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, butoptions.configParsers can be used to support alternate formats.

API

Linting

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

/**

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

/**

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

/**

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 | 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, true enables its default configuration, and passing an object value customizes that rule. Setting the special defaultrule to true or false includes/excludes all rules by default. In the absence of a configuration object, all rules are enabled. 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 of referencing a built-in style from JavaScript:

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

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

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

See the style directory for more samples.

See markdownlint-config-schema.jsonfor the JSON Schema of the options.configobject.

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. ThereadConfig function can be used to read such aggregate styles from code.

For example, assuming a base.json configuration file:

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

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

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 matterfound 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\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, andJSON front matter such as:

---
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 settinghandleRuleFailures 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 anymarkdown-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:

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

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

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 themarkdown-it parser.

options.noInlineConfig

Type: Boolean

Disables the use of HTML comments like <!-- markdownlint-enable --> 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. 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. 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. 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 behavior.

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

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

/**

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

/**

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

/**

file

Type: String

Location of configuration file to read.

The file is resolved relative to the current working directory. If anextends key is present once read, its value will be resolved as a path relative to file and loaded recursively. Settings from a file referenced byextends 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 orextends 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:

[ 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, andaccessSync.

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 viaimport { applyFix, applyFixes } from "markdownlint":

/**

/**

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

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:

/**

Invoking getVersion is simple:

import { getVersion } from "markdownlint";

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

Usage

Invoke lint and use the result object's toString method:

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.log(results.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 as a synchronous call:

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

const results = lintSync(options); console.log(results.toString());

To examine the result object directly via a Promise-based call:

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

const results = await lintPromise(options); console.dir(results, { "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/md010.md", "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/md018.md", "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/md018.md", "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/md041.md", "errorDetail": null, "errorContext": "#bad.md", "errorRange": null } ] }

Integration with the gulp build system is straightforward: gulpfile.cjs.

Integration with the Grunt build system is similar:Gruntfile.cjs.

Browser

markdownlint also works in the browser.

Generate normal and minified scripts with:

Then reference the markdownlint-browser script:

And call it like so:

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

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

Examples

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

For more advanced integration scenarios:

Contributing

See CONTRIBUTING.md for more information.

Releasing

See ReleaseProcess.md for more information.

History

See CHANGELOG.md.