Have ideas to improve npm?Join in the discussion! »

    markdownlint-cli2

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

    Overview

    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

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

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

    Install

    npm i markdownlint-cli2

    DownloadsWeekly Downloads

    2,572

    Version

    0.1.2

    License

    MIT

    Unpacked Size

    42.3 kB

    Total Files

    8

    Last publish

    Collaborators

    • avatar