markdownlint-cli2

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

Install

As a global CLI:

npm install markdownlint-cli2 --global

As a development dependency of the current package:

npm install markdownlint-cli2 --save-dev

Overview

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

Use

markdownlint-cli2 vX.Y.Z (markdownlint vX.Y.Z)
https://github.com/DavidAnson/markdownlint-cli2

Syntax: markdownlint-cli2 glob0 [glob1] [...] [globN]

Glob expressions (from the globby library):
- * matches any number of characters, but not /
- ? matches a single character, but not /
- ** matches any number of characters, including / (when it's the only thing in a path part)
- {} allows for a comma-separated list of "or" expressions
- ! or # at the beginning of a pattern negate the match

Dot-only glob:
- The command "markdownlint-cli2 ." would lint every file in the current directory tree which is probably not intended
- Instead, it is mapped to "markdownlint-cli2 *.{md,markdown}" which lints all Markdown files in the current directory
- To lint every file in the current directory tree, the command "markdownlint-cli2 **" can be used instead

Configuration via:
- .markdownlint-cli2.jsonc
- .markdownlint-cli2.yaml
- .markdownlint-cli2.js
- .markdownlint.jsonc or .markdownlint.json
- .markdownlint.yaml or .markdownlint.yml
- .markdownlint.js

Cross-platform compatibility:
- UNIX and Windows shells expand globs according to different rules, so quoting glob arguments is recommended
- Shells that expand globs do not support negated patterns (!node_modules), so quoting negated globs is required
- Some Windows shells do not handle single-quoted (') arguments correctly, so double-quotes (") are recommended
- Some UNIX shells handle exclamation (!) in double-quotes specially, so hashtag (#) is recommended for negated globs
- Some shells use backslash (\) to escape special characters, so forward slash (/) is the recommended path separator

Therefore, the most compatible glob syntax for cross-platform support:
$ markdownlint-cli2 "**/*.md" "#node_modules"

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

As shown above, the default command-line for markdownlint-cli2 looks something like:

markdownlint-cli2 "**/*.md" "#node_modules"

However, because sharing configuration between "normal" and "fix" modes is so common, the following command defaults the fix property (see below) to true:

markdownlint-cli2-fix "**/*.md" "#node_modules"

Other than the default behavior of the fix property (which can be overridden in both cases), these two commands behave identically.

Exit Codes

• 0: Linting was successful and there were no errors
• 1: Linting was successful and there were errors
• 2: Linting was not completed due to a runtime issue

Rule List

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

Glob expressions

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

Configuration

• 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 match files under the current directory and configuration for that (top-level) directory applies to the entire tree
  • When glob expressions match files not under the current directory, configuration for the current (top-level) directory is applied to the closest common parent directory

.markdownlint-cli2.jsonc

• 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,js} file (see below) is present in the same directory, it overrides the value of this property
  • customRules: Array of Strings of module names/paths of custom rules to load and use when linting
    • Each String is passed as the id parameter to Node's require function
    • 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|$)
  • 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 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
  • 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
  • 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
• 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.
• For example: .markdownlint-cli2.jsonc with all properties set

.markdownlint-cli2.yaml

• 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.
• If a .markdownlint-cli2.jsonc file is present in the same directory, it takes precedence.
• For example: .markdownlint-cli2.yaml with all properties set

.markdownlint-cli2.js

• The format of this file is a CommonJS module that exports the object described above for .markdownlint-cli2.jsonc.
• 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.
• If a .markdownlint-cli2.jsonc or .markdownlint-cli2.yaml file is present in the same directory, it takes precedence.
• For example: .markdownlint-cli2.js

.markdownlint.jsonc or .markdownlint.json

• 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.
• If jsonc and json files are present in the same directory, the jsonc version takes precedence.
• 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

.markdownlint.yaml or .markdownlint.yml

• 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.
• If yaml and yml files are present in the same directory, the yaml version takes precedence.
• If a jsonc or json file is present in the same directory, it takes precedence.
• For example: .markdownlint.yaml

.markdownlint.js

• The format of this file is a CommonJS module that exports the markdownlint config object.
• Other details are the same as for jsonc/json files described above.
• If a jsonc, json, yaml, or yml file is present in the same directory, it takes precedence.
• For example: .markdownlint.js

Compatibility

markdownlint-cli

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

vscode-markdownlint

• .markdownlintrc and .markdownlintignore are not supported.

pre-commit

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:

- repo: https://github.com/DavidAnson/markdownlint-cli2
  rev: v0.0.15
  hooks:
  - id: markdownlint-cli2

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

History

• 0.0.2 - Initial release
• 0.0.3 - Feature parity with markdownlint-cli
• 0.0.4 - Support output formatters and markdown-it plugins
• 0.0.5 - Improve support for ignoring files
• 0.0.6 - Improve handling of very large directory trees
• 0.0.7 - Support .markdownlint-cli2.js and .markdownlint.js
• 0.0.8 - Support .markdownlint-cli2.yaml, add progress
• 0.0.9 - Improve configuration file handling
• 0.0.10 - Improve performance and configuration
• 0.0.11 - Improve performance of fix, update banner
• 0.0.12 - Update dependencies (including markdownlint)
• 0.0.13 - Add markdownlint-cli2-fix command
• 0.0.14 - Update dependencies (including markdownlint)
• 0.0.15 - Improve extensibility