markdownlint-cli2

What is markdownlint-cli2?

markdownlint-cli2 is a command-line interface for the markdownlint library, which is used to lint Markdown files. It helps ensure that Markdown files adhere to a consistent style and are free of common errors.

What are markdownlint-cli2's main functionalities?

Linting Markdown Files

This command lints all Markdown files in the current directory and its subdirectories. It checks for common issues and style inconsistencies in Markdown files.

npx markdownlint-cli2 '**/*.md'

Using a Configuration File

This command uses a configuration file (.markdownlint.json) to specify custom linting rules. This allows for more granular control over the linting process.

npx markdownlint-cli2 '**/*.md' --config .markdownlint.json

Fixing Issues Automatically

This command not only lints the Markdown files but also attempts to fix any issues it finds automatically. This can save time by correcting common mistakes without manual intervention.

npx markdownlint-cli2-fix '**/*.md'

Ignoring Files

This command lints all Markdown files but ignores those in the node_modules directory. This is useful for excluding third-party files from the linting process.

npx markdownlint-cli2 '**/*.md' --ignore node_modules

Other packages similar to markdownlint-cli2

remark-cli

remark-cli is a command-line interface for the remark library, which is used to process Markdown files. It offers similar functionality to markdownlint-cli2, including linting and formatting, but is part of the larger unified ecosystem, which provides a wide range of plugins for additional processing tasks.

markdownlint

markdownlint is the core library that markdownlint-cli2 is based on. It provides the underlying linting functionality and can be used programmatically within Node.js applications. While it does not offer a command-line interface out of the box, it can be integrated into custom scripts and build processes.

mdlint

mdlint is another Markdown linter that focuses on simplicity and ease of use. It provides a basic set of linting rules and can be used as a command-line tool. While it may not be as feature-rich as markdownlint-cli2, it is a good option for users who need a straightforward linting solution.

README

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.

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

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"

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.

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

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