DOCSEARCHbyAlgolia
Submit Docs

markdownlint-cli2

repository·main·Indexed 21 days ago

https://github.com/davidanson/markdownlint-cli2

A fast, flexible, configuration-based command-line interface for linting Markdown and CommonMark files using the markdownlint library. Version 0.23.2. It supports various output formatters including default, JSON, JUnit XML, SARIF, pretty, and GitLab Code Quality reports.

Tokens
15K
Snippets
58
Records
71
Agent score
72%

What's inside markdownlint-cli2

  1. Understand differences between markdownlint-cli and markdownlint-cli2

    main

    If you are migrating from markdownlint-cli to markdownlint-cli2, be aware of the following behavioral differences:

    • Glob Implementation: The glob implementation and pattern matching handling differ slightly.
    • Configuration Scoping: In markdownlint-cli2, configuration files are supported in every directory. In markdownlint-cli, configuration is only supported at the root.
    • Unsupported Formats: markdownlint-cli2 does not support the INI config format, .markdownlintrc, or .markdownlintignore files.

  2. Configure the template formatter with custom tokens

    main

    The markdownlint-cli2-formatter-template allows you to custom-format linting violations by setting a template string in your .markdownlint-cli2.jsonc configuration. The template is applied once for each violation.

    Available Tokens

    Always defined:

    • fileName: File name
    • lineNumber: Line number (1-based)
    • ruleName: Full rule name
    • ruleDescription: Rule description
    • ruleInformation: Informational URL

    Sometimes defined (rule-dependent):

    • columnNumber: Column number (1-based)
    • errorContext: Context information
    • errorDetail: Additional detail
    • errorSeverity: Severity (error or warning)

    Token Syntax

    • Simple: ${token}
    • If present: ${token:text if present} (e.g., ${columnNumber:Column=${columnNumber}})
    • If not present: ${token!text if not present} (e.g., ${columnNumber!No column number})

    Note: Only one level of token nesting is supported.

    Token Behavior Examples

    TemplateOutput if definedOutput if not defined
    Column=${columnNumber}Column=10Column=
    ${columnNumber:Column=${columnNumber}}Column=10(empty)
    ${columnNumber!No column number}(empty)No column number
    ${columnNumber:Column=${columnNumber}}${columnNumber!No column number}Column=10No column number
    {
  "outputFormatters": [
    [
      "markdownlint-cli2-formatter-template",
      {
        "template": "Column=${columnNumber}"
      }
    ]
  ]
}

  3. Understand the two types of configuration files

    main

    markdownlint-cli2 supports two distinct categories of configuration files. Choosing the right one depends on whether you want to control the CLI tool's behavior or just the linting rules.

    1. Full CLI Configuration (.markdownlint-cli2.*): These files provide complete control over markdownlint-cli2 behavior (e.g., custom rules, plugins, formatters, and file ignoring). These are also used by the vscode-markdownlint extension.
    2. Rule-only Configuration (.markdownlint.*): These files only control the markdownlint config object (the rules themselves). They are more broadly supported by other tools like markdownlint-cli.

    Configuration files in subdirectories override those in parent directories. If multiple files of the same type exist in one directory, they follow a specific precedence order.

  4. Use markdownlint-cli2 via Command Line

    main

    The CLI accepts glob expressions to identify files to lint.

    Syntax: markdownlint-cli2 glob0 [glob1] [...] [globN] [--config file] [--configPointer pointer] [--fix] [--format] [--help] [--no-globs]

    Common Usage Patterns:

    • Standard linting: markdownlint-cli2 "**/*.md" "#node_modules"
    • Linting with auto-fix: markdownlint-cli2 --fix "**/*.md" "#node_modules"
    • Using a specific config file: markdownlint-cli2 --config "config/.markdownlint-cli2.jsonc" "**/*.md"
    • Using a JSON Pointer to a config object in another file (e.g., package.json): markdownlint-cli2 --config package.json --configPointer /markdownlint-cli2 "*.md"

    Important Notes:

    • Cross-platform compatibility: It is highly recommended to quote glob arguments (e.g., "**/*.md") to ensure compatibility across different shells (UNIX/Windows).
    • Dot-only glob: Running markdownlint-cli2 . is automatically mapped to markdownlint-cli2 *.{md,markdown}. To lint the entire tree, use markdownlint-cli2 **.
    • Stdin/Formatting mode: Using the --format flag tells the CLI to read from stdin, apply fixes, and write to stdout. This is useful for editor integrations.
    markdownlint-cli2 "**/*.md" "#node_modules"

  7. Enable editor autocomplete for markdownlint-cli2 configuration

    main

    You can enable automatic validation and autocomplete in supported editors by adding a $schema property to your configuration file (e.g., .markdownlint-cli2.jsonc). This references the official JSON Schema provided by the project.

    Use the following URL in your configuration file: https://raw.githubusercontent.com/DavidAnson/markdownlint-cli2/main/schema/markdownlint-cli2-config-schema.json

    {
  "$schema": "https://raw.githubusercontent.com/DavidAnson/markdownlint-cli2/main/schema/markdownlint-cli2-config-schema.json"
}

  11. Integrate markdownlint-cli2 with pre-commit

    main

    To run markdownlint-cli2 automatically during a pre-commit workflow, add the repository to your .pre-commit-config.yaml file.

    You can choose between two hook IDs:

    1. markdownlint-cli2: Runs using the local Node.js environment.
    2. markdownlint-cli2-docker: Runs using a Docker container image that bundles Node.js and all dependencies. This provides a more consistent experience as it is isolated from local dependency changes.
    - repo: https://github.com/DavidAnson/markdownlint-cli2
  rev: v0.23.2
  hooks:
  - id: markdownlint-cli2

  12. Validate markdownlint-cli2 configuration using AJV CLI

    main

    To manually validate your markdownlint-cli2 configuration files (such as .markdownlint-cli2.jsonc or .markdownlint-cli2.yaml) against the official schema, you can use the ajv-cli tool.

    This command validates your configuration files against both the markdownlint-cli2-config-schema.json and the underlying markdownlint-config-schema.json.

    npx ajv-cli validate -s ./markdownlint-cli2/schema/markdownlint-cli2-config-schema.json -r ./markdownlint-cli2/schema/markdownlint-config-schema.json -d "**/.markdownlint-cli2.{jsonc,yaml}" --strict=false