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.
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.
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):
Disable all rules: <!-- markdownlint-disable -->
Enable all rules: <!-- markdownlint-enable -->
Disable all rules for the current line: <!-- markdownlint-disable-line -->
Disable all rules for the next line: <!-- markdownlint-disable-next-line -->
Disable one or more rules by name: <!-- markdownlint-disable MD001 MD005 -->
Enable one or more rules by name: <!-- markdownlint-enable MD001 MD005 -->
Disable one or more rules by name for the current line:
<!-- markdownlint-disable-line MD001 MD005 -->
Disable one or more rules by name for the next line:
<!-- markdownlint-disable-next-line MD001 MD005 -->
Capture the current rule configuration: <!-- markdownlint-capture -->
Restore the captured rule configuration: <!-- markdownlint-restore -->
For example:
<!-- markdownlint-disable-next-line no-space-in-emphasis -->
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:
Disable all rules: <!-- markdownlint-disable-file -->
Enable all rules: <!-- markdownlint-enable-file -->
Disable one or more rules by name: <!-- markdownlint-disable-file MD001 -->
Enable one or more rules by name: <!-- markdownlint-enable-file MD001 -->
This can be used to "hide" markdownlint comments at the bottom of a file.
In cases where it is desirable to change the configuration of one or
more rules for a file, the following more advanced syntax is supported:
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.
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 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.
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:
Type: OptionalArray 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.
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.
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.
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.
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.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:
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 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.
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.
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.
请发表评论