markdownlint-cli2

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

Install

npm install markdownlint-cli2 --save-dev

Overview

Note: markdownlint-cli2 is under development and is not yet as capable as markdownlint-cli.

• markdownlint is a library for linting Markdown/ CommonMark files on Node.js.
• 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 both speed and simplicity.
• markdownlint-cli2 is mostly compatible with the features of markdownlint-cli.
• vscode-markdownlint is a markdownlint extension for the Visual Studio Code editor.
• markdownlint-cli2 is meant to work well in conjunction with vscode-markdownlint.

Use

markdownlint-cli2 version X.Y.Z by David Anson (https://dlaa.me/)
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

Configuration:
- Via .markdownlint-cli2.jsonc, .markdownlint.jsonc, .markdownlint.json, .markdownlint.yaml, or .markdownlint.yml

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 syntax for cross-platform support:
markdownlint-cli2 "**/*.md" "#node_modules"

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][markdownlint-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.

.markdownlintignore

• The format of this file is similar to .npmignore and consists of one glob pattern per line.
• These glob patterns are negated (by adding a leading !) and appended to the end of the command-line arguments.
• Blank lines and lines that begin with the # character are ignored.

.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 jsonc/json/yaml/yml 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
  • 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 Markdown content
    • The String is passed as the pattern parameter to the RegExp constructor
    • For example: (^---\s*$[^]*?^---\s*$)(\r\n|\r|\n|$)
  • noInlineConfig: Boolean value to disable the support of HTML comments within Markdown content
    • For example: <!-- markdownlint-disable some-rule -->
• 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.

.markdownlint.jsonc / .markdownlint.json

• The format of this file is a JSON or JSONC 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 both 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 above).
• Both extensions support comments in JSON.

.markdownlint.yaml / .markdownlint.yml

• The format of this file is a YAML object representing markdownlint's config object.
• Other details are the same as for jsonc/json files described above.
• If both files are present in the same directory, the yaml version takes precedence.
• If a jsonc or json file is present, it takes precedence according the rules above.

Compatibility

markdownlint-cli

• The glob implementation and handling of patterns is different.
• The treatment of .markdownlintignore patterns is different.
• Configuration files are supported in each directory (vs. one globally).
• The INI config format and .markdownlintrc are not supported.

vscode-markdownlint

• The treatment of .markdownlintignore patterns is different.
• .markdownlintrc is not supported as a configuration file.

History

• 0.0.2 - Initial release