A fast, flexible, configuration-based command-line interface for linting Markdown/CommonMark files with the markdownlint library

As a global CLI:

As a development dependency of the current Node.js package:

As a Docker container image:

As a global CLI with Homebrew:

As a GitHub Action via markdownlint-cli2-action:

• markdownlint is a library for linting Markdown/ CommonMark files on Node.js using the markdown-it parser.
• markdownlint-cli is a traditional command-line interface for markdownlint.
• markdownlint-cli2 is a slightly unconventional command-line interface for markdownlint.
• markdownlint-cli2 is configuration-based and prioritizes speed and simplicity.
• markdownlint-cli2 supports all the features of markdownlint-cli (sometimes a little differently).
• vscode-markdownlint is a markdownlint extension for the Visual Studio Code editor.
• markdownlint-cli2 is designed to work well in conjunction with vscode-markdownlint.
• More about the motivation for markdownlint-cli2.

For scenarios where it is preferable to specify glob expressions in a configuration file, the globs property of .markdownlint-cli2.jsonc, .yaml, .cjs, or .mjs may be used instead of (or in addition to) passing glob0 ... globN on the command-line.

As shown above, a typical command-line for markdownlint-cli2 looks something like:

Because sharing the same configuration between "normal" and "fix" modes is common, the --fix argument can be used to default the fix property (see below) to true (though it can still be overridden by a configuration file):

In cases where it is not convenient to store a configuration file in the root of a project, the --config argument can be used to provide a path to any supported configuration file/format:

The configuration file name should be (or end with) one of the supported names above. For example, .markdownlint.json or example.markdownlint-cli2.jsonc. Alternatively, the configuration file name should have a supported extension like .jsonc, .yaml, .mjs, or .toml and its kind (see below) will be inferred. The configuration file will be loaded, parsed, and applied as a base configuration for the current directory - which will then be handled normally.

The --configPointer argument allows the use of JSON Pointer syntax to identify a sub-object within the configuration file specified by --config (see above). This argument can be used with any configuration file type and makes it possible to nest configuration data within another file like package.json or pyproject.toml (e.g., via /key or /key/subkey).

For example, a package.json file like this:

Could be used like this:

And a pyproject.toml file like this:

Could be used like this:

Note: The TOML format is supported by --config, --configPointer, and the extends configuration property, but not for per-directory overrides.

A container image davidanson/markdownlint-cli2 can also be used (e.g., as part of a CI pipeline):

Notes:

• As when using the command line, glob patterns are passed as arguments.
• This image is built on the official Node.js Docker image. Per security best practices, the default user node runs with restricted permissions. If it is necessary to run as root, pass the -u root option when invoking docker.
• By default, markdownlint-cli2 will execute within the /workdir directory inside the container. So, as shown above, bind mount the project's directory there.

  • A custom working directory can be specified with Docker's -w flag:

    docker run -w /myfolder -v $PWD:/myfolder davidanson/markdownlint-cli2:v0.22.1 "**/*.md" "#node_modules"

For convenience, the container image davidanson/markdownlint-cli2-rules includes the latest versions of custom rules published to npm with the tag markdownlint-rule. These rules are installed globally onto the base image davidanson/markdownlint-cli2.

Note: This container image exists for convenience and is not an endorsement of the rules within.

In addition to (or instead of) the default behavior of writing a list of all issues to the standard error (stderr) device, custom output formatters can be configured to produce a variety of outputs like:

• List of issues (default)
• List of issues with color and links
• GitLab Code Quality report file
• JSON file
• JUnit XML file
• Static Analysis Results Interchange Format/SARIF file
• Summary of issues found
• Flexible string template supporting:
  • Azure Pipelines Task command LogIssue format
  • GitHub Actions workflow commands format

For more information, refer to the documentation for the outputFormatters parameter below.

• 0: Linting was successful and there were no errors (there may be warnings)
• 1: Linting was successful and there were errors (and possibly warnings)
• 2: Linting was not successful due to a problem or failure

Some editors implement document formatting by invoking an external program, passing the text of the current document on standard input (stdin), and reading the formatted result from standard output (stdout). This scenario is supported by the --format command-line parameter. When --format is set:

• Globs and other input sources are ignored
• The --fix parameter is implicitly set
• The exit code 1 is not used

• See the Rules / Aliases and Tags sections of the markdownlint documentation.

• Globbing is performed by the globby library; refer to that documentation for more information and examples.

• See the Configuration section of the markdownlint documentation for information about the inline comment syntax for enabling and disabling rules with HTML comments.
• In general, glob expressions should match files under the current directory; the configuration for that directory will apply to the entire tree.
  • When glob expressions match files not under the current directory, configuration for the current directory is applied to the closest common parent directory.
• Paths beginning with ~ are resolved relative to the user's home directory (typically $HOME on UNIX and %USERPROFILE% on Windows)
• There are two kinds of configuration file (both detailed below):
  • Configuration files like .markdownlint-cli2.* allow complete control of markdownlint-cli2 behavior and are also used by vscode-markdownlint.
    • If multiple of these files are present in the same directory, only one is used according to the following precedence:
      1. .markdownlint-cli2.jsonc
      2. .markdownlint-cli2.yaml
      3. .markdownlint-cli2.cjs
      4. .markdownlint-cli2.mjs
  • Configuration files like .markdownlint.* allow control over only the markdownlint config object and tend to be supported more broadly (such as by markdownlint-cli).
    • If multiple of these files are present in the same directory, only one is used according to the following precedence:
      1. .markdownlint.jsonc
      2. .markdownlint.json
      3. .markdownlint.yaml
      4. .markdownlint.yml
      5. .markdownlint.cjs
      6. .markdownlint.mjs
  • Both configuration file types can appear in any directory and will override configuration defined in the project root or any directories in between.
• The VS Code extension includes a JSON Schema definition for the JSON(C) configuration files described below. This adds auto-complete and can make it easier to define proper structure.
• See markdownlint-cli2-config-schema.json for that schema and ValidatingConfiguration.md for ways to use it to validate configuration files.

• The format of this file is a JSONC object similar to the markdownlint options object.
• Valid properties are:
  • config: markdownlint config object to configure rules for this part of the directory tree
    • If a .markdownlint.{jsonc,json,yaml,yml,cjs,mjs} file (see below) is present in the same directory, it overrides the value of this property
    • If the config object contains an extends property, it will be resolved the same as .markdownlint.{jsonc,json,yaml,yml,cjs,mjs} (see below)
  • customRules: Array of Strings (or Arrays of Strings) of module names/paths of custom rules to load and use when linting
    • Relative paths are resolved based on the location of the JSONC file
    • Search markdownlint-rule on npm
  • fix: Boolean value to enable fixing of linting errors reported by rules that emit fix information
    • Fixes are made directly to the relevant file(s); no backup is created
  • frontMatter: String defining the RegExp used to match and ignore any front matter at the beginning of a document
    • The String is passed as the pattern parameter to the RegExp constructor
    • For example: (^---\s*$[^]*?^---\s*$)(\r\n|\r|\n|$)
  • gitignore: Boolean or String value to automatically ignore files referenced by .gitignore (or similar) when linting
    • When the value true is specified, all .gitignore files in the tree and up to the repository root are used (default git behavior)
    • When a String value is specified, that glob pattern is used to identify the set of ignore files to use
      • The value **/.gitignore corresponds to the Boolean value true but does not use .gitignore files up to the repository root
      • The value .gitignore uses only the file in the root of the tree; this is usually equivalent and can be much faster for large trees
    • This top-level setting is valid only in the directory from which markdownlint-cli2 is run
  • globs: Array of Strings defining glob expressions to append to the command-line arguments
    • This setting can be used instead of (or in addition to) passing globs on the command-line and offers identical performance
    • This setting is ignored when the --no-globs parameter is passed on the command-line
    • This top-level setting is valid only in the directory from which markdownlint-cli2 is run
  • ignores: Array of Strings defining glob expressions to ignore when linting
    • This setting has the best performance when applied to the directory from which markdownlint-cli2 is run
      • In this case, glob expressions are negated (by adding a leading !) and appended to the command-line arguments before file enumeration
      • The setting is not inherited by nested configuration files in this case
    • When this setting is applied in subdirectories, ignoring of files is done after file enumeration, so large directories can negatively impact performance
      • Nested configuration files inherit and reapply the setting to the contents of nested directories in this case
  • markdownItPlugins: Array of Arrays, each of which has a String naming a markdown-it plugin followed by parameters
    • Plugins can be used to add support for additional Markdown syntax
    • Relative paths are resolved based on the location of the JSONC file
    • For example: [ [ "plugin-name", param_0, param_1, ... ], ... ]
    • Search markdown-it-plugins on npm
  • modulePaths: Array of Strings providing additional paths to use when resolving module references (e.g., alternate locations for node_modules)
  • noBanner: Boolean value to disable the display of the banner message and version numbers on stdout
    • This top-level setting is valid only in the directory from which markdownlint-cli2 is run
    • Use with noProgress to suppress all output to stdout (i.e., --quiet)
  • noInlineConfig: Boolean value to disable the support of HTML comments within Markdown content
    • For example: <!-- markdownlint-disable some-rule -->
  • noProgress: Boolean value to disable the display of progress on stdout
    • This top-level setting is valid only in the directory from which markdownlint-cli2 is run
    • Use with noBanner to suppress all output to stdout (i.e., --quiet)
  • outputFormatters: Array of Arrays, each of which has a String naming an output formatter followed by parameters
    • Formatters can be used to customize the tool's output for different scenarios
    • Relative paths are resolved based on the location of the JSONC file
    • For example: [ [ "formatter-name", param_0, param_1, ... ], ... ]
    • This top-level setting is valid only in the directory from which markdownlint-cli2 is run
    • Search markdownlint-cli2-formatter on npm
  • showFound: Boolean value to display the list of found files on stdout
    • This top-level setting is valid only in the directory from which markdownlint-cli2 is run and only when noProgress has not been set
• When referencing a module via the customRules, markdownItPlugins, or outputFormatters properties, each String identifier is passed to Node's require function then (if that failed) its import expression
  • Importing a locally-installed module using a bare specifier (ex: package-name) or using a directory name (ex: ./package-dir) will not work until import.meta.resolve is available
• Settings in this file apply to the directory it is in and all subdirectories.
• Settings merge with those applied by any versions of this file in a parent directory (up to the current directory).
• For example: .markdownlint-cli2.jsonc with all properties set

• The format of this file is a YAML object with the structure described above for .markdownlint-cli2.jsonc.
• Other details are the same as for .markdownlint-cli2.jsonc described above.
• For example: .markdownlint-cli2.yaml with all properties set

• The format of this file is a CommonJS module (.cjs) or ECMAScript module (.mjs) that exports the object described above for .markdownlint-cli2.jsonc (directly or from a Promise).
• Instead of passing a String to identify the module name/path to load for customRules, markdownItPlugins, and outputFormatters, the corresponding Object or Function can be provided directly.
• Other details are the same as for .markdownlint-cli2.jsonc described above.
• For example: .markdownlint-cli2.cjs or .markdownlint-cli2.mjs

• The format of this file is a JSONC or JSON object matching the markdownlint config object.
• Settings in this file apply to the directory it is in and all subdirectories
• Settings override those applied by any versions of this file in a parent directory (up to the current directory).
• To merge the settings of these files or share configuration, use the extends property (documented in the link above).
• Both file types support comments in JSON.
• For example: .markdownlint.jsonc

• The format of this file is a YAML object representing the markdownlint config object.
• Other details are the same as for jsonc/json files described above.
• For example: .markdownlint.yaml

• The format of this file is a CommonJS module (.cjs) or ECMAScript module (.mjs) that exports the markdownlint config object (directly or from a Promise).
• Other details are the same as for jsonc/json files described above.
• For example: .markdownlint.cjs or .markdownlint.mjs

• The glob implementation and handling of pattern matching is slightly different.
• Configuration files are supported in every directory (vs. only one at the root).
• The INI config format, .markdownlintrc, and .markdownlintignore are not supported.

To run markdownlint-cli2 as part of a pre-commit workflow, add a reference to the repos list in that project's .pre-commit-config.yaml like:

Depending on the environment that workflow runs in, it may be necessary to override the version of Node.js used by pre-commit.

Setting the id above to markdownlint-cli2-docker uses the Docker container image instead. That image bundles Node.js and all dependencies and provides the most consistent experience because it is not affected by new releases of any dependencies.

See CHANGELOG.md.