Configuration Guide

This guide details how markdownlint-cli resolves configuration files, supports multiple formats, handles JS evaluation rules, and targets sub-objects via JSON Pointers.

The Configuration Resolution Hierarchy

When you execute markdownlint-cli, the configuration engine determines active rulesets by merging multiple configuration sources in a specific order of precedence:

[High Precedence]
  1. Command Line Parameters (--enable, --disable)
  2. Inline File Overrides (<!-- markdownlint-configure-file -->)
  3. Manually Specified Config File (-c / --config <file>)
  4. Directory-Level Configs in CWD (.markdownlint.jsonc, .json, .yaml, .yml)
  5. Parent Directory Lookup Hierarchy (.markdownlintrc via rc)
[Low Precedence]

Automated File Lookups

If you do not specify a configuration file using the -c or --config parameters, markdownlint-cli automatically searches for a configuration file in your directory structure.

Step 1: Upward Hierarchy Lookup via rc

The CLI first uses the run-con library to search for a file named .markdownlintrc in the current working directory, and recursively checks parent directories up to your system root if not found.

Step 2: CWD Config File Scanning

If no .markdownlintrc is discovered, the engine searches the current working directory for the following default configuration filenames (evaluated in order of precedence):

1. .markdownlint.jsonc
2. .markdownlint.json
3. .markdownlint.yaml
4. .markdownlint.yml

Once a match is found, scanning stops and any remaining lower-priority files are ignored.

Supported Configuration File Formats

When providing a configuration file explicitly via --config <file>, you can choose from several formats depending on your workflow.

1. JSON and JSONC (With Comments)

JSON configurations are widely used in Node.js-centric repositories. Using standard JSONC parser libraries, comments are stripped out during processing, allowing you to explain configurations inline.

{
  // Enable default configurations
  "default": true,

  // Force closing tags on ATX style headings
  "MD003": {
    "style": "atx_closed"
  },

  // Restrict list indentation to 4 spaces
  "MD007": {
    "indent": 4
  },

  // Disable inline HTML and trailing punctuation checks
  "no-inline-html": false,
  "no-trailing-punctuation": false
}

2. YAML

YAML is ideal for pipelines, matching configuration styles in MkDocs or Ansible environments.

default: true
MD003:
  style: "atx"
MD007:
  indent: 2
MD013:
  line_length: 120
no-hard-tabs: false

3. TOML

TOML configurations use clear section boundaries and key-value declarations. markdownlint-cli parses TOML using the smol-toml package.

default = true
no-hard-tabs = false

[MD013]
line_length = 120

[MD003]
style = "atx"

4. JavaScript (CommonJS)

JavaScript-based configurations let you generate configuration rules dynamically or load shared packages from your workspace dependencies.

'use strict';

const sharedBrandGuidelines = require('@company/brand-configs/markdownlint');

module.exports = {
  default: true,
  ...sharedBrandGuidelines,
  // Override a specific rule locally
  MD013: {
    line_length: 160
  }
};

markdownlint --config .markdownlint.cjs .

JSON Pointer (--configPointer)

In monorepos or multi-tool configuration environments, you may want to centralize tool configurations in a single file—such as storing lint parameters under a root package.json or custom JSON manifest.

You can use the --configPointer option to target a specific nested sub-object in your configuration file using RFC 6901 JSON Pointer syntax.

Package.json Configuration Example

Consider this package.json file:

{
  "name": "my-project-package",
  "version": "1.0.0",
  "devDependencies": {
    "markdownlint-cli": "^0.47.0"
  },
  "tooling": {
    "linters": {
      "markdownlint": {
        "default": true,
        "line-length": {
          "line_length": 140
        }
      }
    }
  }
}

To run linting using this nested configuration, reference the package.json file path and define the path to your settings block with --configPointer:

markdownlint --config package.json --configPointer /tooling/linters/markdownlint '**/*.md'

Configuration Best Practices

• Prefer Local Project Configs: Always check a .markdownlint.json or .markdownlint.yaml configuration file into the root of your source repository. This keeps styling requirements aligned across all developer platforms and automated tasks.
• Use Comments: Leverage .markdownlint.jsonc or YAML configuration formats so you can document why certain rules are customized or disabled inline.
• Keep Rule Identifiers Consistent: Stick to either alphanumeric identifiers (e.g. MD013) or their readable aliases (e.g. line-length) throughout your project settings to make configurations easier to read.
• Disable Explicitly: Rather than removing rules from your configuration files, disable them explicitly (e.g., "MD033": false). This clearly indicates to other developers that the rule was intentionally disabled, rather than overlooked.