No Packages Misplaced

    markdownlint-cli2

    0.5.0 • Public • Published

    markdownlint-cli2

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

    npm version License

    Install

    As a global CLI:

    npm install markdownlint-cli2 --global

    As a development dependency of the current package:

    npm install markdownlint-cli2 --save-dev

    Or as a Docker container image:

    docker pull davidanson/markdownlint-cli2

    Overview

    Use

    Command Line

    markdownlint-cli2 vX.Y.Z (markdownlint vX.Y.Z)
    https://github.com/DavidAnson/markdownlint-cli2
    
    Syntax: markdownlint-cli2 glob0 [glob1] [...] [globN]
            markdownlint-cli2-fix glob0 [glob1] [...] [globN]
            markdownlint-cli2-config config-file 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 /
    - {} 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
    
    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.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
    
    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 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), these two commands behave identically.

    In cases where it is not convenient to store a configuration file in the root of a project, the markdownlint-cli2-config command can be used. This command accepts a path to any supported configuration file as its first argument:

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

    The configuration file name must be (or end with) one of the supported types above. For example, .markdownlint.json or example.markdownlint-cli2.jsonc. The specified configuration file will be loaded, parsed, and applied as a base configuration for the current directory - which will then be handled normally. Otherwise, this command behaves identically to markdownlint-cli2.

    Container Image

    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:0.5.0 "**/*.md" "#node_modules"

    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:0.5.0 "**/*.md" "#node_modules"

    To invoke the markdownlint-cli2-config or markdownlint-cli2-fix commands instead, use Docker's --entrypoint flag:

    docker run -v $PWD:/workdir --entrypoint="markdownlint-cli2-fix" davidanson/markdownlint-cli2:0.5.0 "**/*.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

    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 the configuration for that directory applies 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.

    .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 (or Arrays of Strings) of module names/paths of custom rules to load and use when linting
      • 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
    • 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

    .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.cjs or .markdownlint-cli2.mjs

    • The format of this file is a CommonJS module (.cjs) or ECMAScript module (.mjs) 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; .markdownlint-cli2.cjs takes precedence over .markdownlint-cli2.mjs.
    • For example: .markdownlint-cli2.cjs or .markdownlint-cli2.mjs

    .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 (up to the current 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.cjs or .markdownlint.mjs

    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

    • .markdownlintignore is 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.5.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.

    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
    • 0.1.0 - Simplify use of require, increment minor version
      • 0.1.1 - Restore previous use of require
      • 0.1.2 - Update use of require to be more flexible
      • 0.1.3 - Support rule collections
    • 0.2.0 - Improve handling of Windows paths using backslash
    • 0.3.0 - Add Docker container, update dependencies
      • 0.3.1 - Extensibility tweaks
      • 0.3.2 - Extensibility/Windows/consistency improvements
    • 0.4.0 - New rules, async custom rules, explicit config, CJS (breaking)
    • 0.5.0 - New rules, support modules (MJS) everywhere, include dotfiles

    Install

    npm i markdownlint-cli2

    DownloadsWeekly Downloads

    18,316

    Version

    0.5.0

    License

    MIT

    Unpacked Size

    56.8 kB

    Total Files

    9

    Last publish

    Collaborators

    • davidanson