gem-hunter
Language: JavaScript
A fast, flexible, configuration-based command-line interface for linting Markdown/CommonMark files with the markdownlint library
A fast, flexible, configuration-based command-line interface for linting Markdown/CommonMark files with the
markdownlintlibrary
As a global CLI:
npm install markdownlint-cli2 --global
As a development dependency of the current Node.js package:
npm install markdownlint-cli2 --save-dev
As a Docker container image:
docker pull davidanson/markdownlint-cli2
As a global CLI with Homebrew:
brew install markdownlint-cli2
As a GitHub Action via
markdownlint-cli2-action:
- name: markdownlint-cli2-action uses: DavidAnson/markdownlint-cli2-action@main
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.markdownlint-cli2.markdownlint-cli2 vX.Y.Z (markdownlint vX.Y.Z)
https://github.com/DavidAnson/markdownlint-cli2
Syntax: markdownlint-cli2 glob0 [glob1] [...] [globN] [--config file] [--configPointer pointer] [--fix] [--format] [--help] [--no-globs]
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 /
- {} allows for a comma-separated list of "or" expressions
- ! or # at the beginning of a pattern negate the match
- : at the beginning identifies a literal file path
- - as a glob represents standard input (stdin)
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
Optional parameters:
- --config specifies the path to a configuration file to define the base configuration
- --configPointer specifies a JSON Pointer to a configuration object within the --config file
- --fix updates files to resolve fixable issues (can be overridden in configuration)
- --format reads standard input (stdin), applies fixes, writes standard output (stdout)
- --help writes this message to the console and exits without doing anything else
- --no-globs ignores the "globs" property if present in the top-level options object
Configuration via:
- .markdownlint-cli2.jsonc
- .markdownlint-cli2.yaml
- .markdownlint-cli2.cjs or .markdownlint-cli2.mjs
- .markdownlint.jsonc or .markdownlint.json
- .markdownlint.yaml or .markdownlint.yml
- .markdownlint.cjs or .markdownlint.mjs
Cross-platform compatibility:
- UNIX and Windows shells expand globs according to different rules; quoting arguments is recommended
- Some Windows shells don't handle single-quoted (') arguments well; double-quote (") is recommended
- Shells that expand globs do not support negated patterns (!node_modules); quoting is required here
- Some UNIX shells parse exclamation (!) in double-quotes; hashtag (#) is recommended in these cases
- The path separator is forward slash (/) on all platforms; backslash (\) is automatically converted
- On any platform, passing the parameter "--" causes all remaining parameters to be treated literally
The most compatible 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, .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:
markdownlint-cli2 "**/*.md" "#node_modules"
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):
markdownlint-cli2 --fix "**/*.md" "#node_modules"
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:
markdownlint-cli2 --config "config/.markdownlint-cli2.jsonc" "**/*.md" "#node_modules"
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:
{
"...": "...",
"markdownlint-cli2": {
"config": {
"no-multiple-blanks": false
},
"noProgress": true
}
}Could be used like this:
markdownlint-cli2 --config package.json --configPointer /markdownlint-cli2 "*.md"And a pyproject.toml file like this:
[project] # ... [tool.markdownlint-cli2] noProgress = true [tool.markdownlint-cli2.config] no-multiple-blanks = false
Could be used like this:
markdownlint-cli2 --config pyproject.toml --configPointer /tool/markdownlint-cli2 "*.md"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):
docker run -v $PWD:/workdir davidanson/markdownlint-cli2:v0.24.0 "**/*.md" "#node_modules"
Notes:
node
runs with restricted permissions. If it is necessary to run as root, pass
the -u root option when invoking docker.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.24.0 "**/*.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:
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 failureSome 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:
--fix parameter is implicitly set1 is not usedmarkdownlint documentation.markdownlint documentation for information about the inline comment syntax
for enabling and disabling rules with HTML comments.~ are resolved relative to the user's home directory
(typically $HOME on UNIX and %USERPROFILE% on Windows).markdownlint-cli2.* allow complete control of
markdownlint-cli2 behavior and are also used by vscode-markdownlint.
.markdownlint-cli2.jsonc.markdownlint-cli2.yaml.markdownlint-cli2.cjs.markdownlint-cli2.mjs.markdownlint.* allow control over only the
markdownlint config object and tend to be supported more broadly (such
as by markdownlint-cli).
.markdownlint.jsonc.markdownlint.json.markdownlint.yaml.markdownlint.yml.markdownlint.cjs.markdownlint.mjsJSON(C) configuration files described below. This adds auto-complete and can
make it easier to define proper structure.markdownlint options objectconfig: markdownlint config object to configure
rules for this part of the directory tree
.markdownlint.{jsonc,json,yaml,yml,cjs,mjs} file (see below) is
present in the same directory, it overrides the value of this propertyconfig 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
JSONC filemarkdownlint-rule on npmfix: Boolean value to enable fixing of linting issues reported by rules
that emit fix information
frontMatter: String defining the RegExp used to match and
ignore any front matter at the beginning of a document
String is passed as the pattern parameter to the
RegExp constructor(^---\s*$[\s\S]*?^---\s*$)(\r\n|\r|\n|$)gitignore: Boolean or String value to automatically ignore files
referenced by .gitignore (or similar) when linting
true is specified, all .gitignore files in the tree
and up to the repository root are used (default git behavior)String value is specified, that glob pattern is used to identify
the set of ignore files to use
**/.gitignore corresponds to the Boolean value true but
does not use .gitignore files up to the repository root.gitignore uses only the file in the root of the tree;
this is usually equivalent and can be much faster for large treesmarkdownlint-cli2 is runglobs: Array of Strings defining glob expressions to append to the
command-line arguments
--no-globs parameter is passed on the
command-linemarkdownlint-cli2 is runignores: Array of Strings defining glob expressions to ignore when
linting
markdownlint-cli2 is run
!) and
appended to the command-line arguments before file enumerationmarkdownItPlugins: Array of Arrays, each of which has a String
naming a markdown-it plugin followed by
parameters
JSONC file[ [ "plugin-name", param_0, param_1, ... ], ... ]markdown-it-plugins on npmmodulePaths: 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
markdownlint-cli2 is runnoProgress to suppress all output to stdout (i.e., --quiet)noInlineConfig: Boolean value to disable the support of
HTML comments within Markdown content
<!-- markdownlint-disable some-rule -->noProgress: Boolean value to disable the display of progress on stdout
markdownlint-cli2 is runnoBanner 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
JSONC file[ [ "formatter-name", param_0, param_1, ... ], ... ]markdownlint-cli2 is runmarkdownlint-cli2-formatter on npmoverrides: Array of Override objects defining configuration overrides
Override object properties (all required):
filter: Array of Strings defining glob expressions of files to
include or exclude (analogous to globs above)
filter will not bring in additional filesOverride object filters match a file, only the first
matching Override is usedconfig: markdownlint config object (as defined for parent object
above)combine: String value merge or replace:
merge: Merges override config values with parent configreplace: Replaces parent config values with override configshowFound: Boolean value to display the list of found files on stdout
markdownlint-cli2 is run and only when noProgress has not been setcustomRules, markdownItPlugins, or
outputFormatters properties, each String identifier is passed to Node's
require function then (if that failed) its
import expression
package-name) or using a directory name (ex: ./package-dir) will not
work until import.meta.resolve is available.markdownlint-cli2.jsonc with all
properties set.markdownlint-cli2.jsonc.markdownlint-cli2.jsonc described above.markdownlint-cli2.yaml with all
properties set.cjs) or
ECMAScript module (.mjs) that exports the object
described above for .markdownlint-cli2.jsonc (directly or from a Promise)String to identify the module name/path to load for
customRules, markdownItPlugins, and outputFormatters, the corresponding
Object or Function can be provided directly.markdownlint-cli2.jsonc described above.markdownlint-cli2.cjs or
.markdownlint-cli2.mjsmarkdownlint config objectextends
property (documented in the link above).markdownlint.jsoncmarkdownlint config objectjsonc/json files described above.markdownlint.yaml.cjs) or
ECMAScript module (.mjs) that exports the
markdownlint config object (directly or from a
Promise)jsonc/json files described above.markdownlint.cjs or
.markdownlint.mjsINI config format, .markdownlintrc, and .markdownlintignore are not
supportedTo 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.24.0 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.
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.