Ignoring Files

As projects expand, excluding third-party dependency directories, compiled code output folders, and auto-generated data files from style checks is essential to maintain clean, fast static analysis builds.

markdownlint-cli evaluates files and ignore patterns using multiple sequential layers, giving you fine-grained control over exclusions.

How Ignore Exclusions Are Resolved

When identifying targets, markdownlint-cli filters file listings using a standard sequence:

1. Target inputs are collected from command line arguments.
2. In-directory filters are resolved via the target file extensions (.md and .markdown by default).
3. Any files matching patterns in your ignore file (.markdownlintignore or --ignore-path) are removed.
4. Any remaining files matching --ignore parameters are removed.

Setting Up .markdownlintignore

The default way to configure exclusions is by creating a .markdownlintignore file in your project root directory. This file uses standard Git match patterns, supported internally by the ignore package.

Guidelines for Writing Exclusions:

  • Lines starting with # are treated as comments and ignored.
  • Exclude whole directories recursively by appending a slash (e.g., dist/).
  • Match files using glob wildcards (e.g., **/*.tmp.md).
  • Negate patterns using a leading exclamation mark (!). This is helpful to enforce checks on a specific file within an ignored directory.

In-Depth .markdownlintignore Example:

# Exclude local dependency directories
node_modules/
bower_components/

# Exclude build output and compiler artifact folders
build/
dist/
out/

# Exclude specific auto-generated report documents
docs/api/auto-generated.md

# Exclude all markdown files ending with .draft.md
**/*.tmp.md

# Exclude temp folders, except for a specific checklist
temp/*
!temp/release-checks.md

Custom Exclusions with --ignore-path

If you want to share a single ignore file across multiple projects, or use an existing pattern configuration (like a .gitignore file), pass the file path directly using the -p or --ignore-path parameter:

markdownlint --ignore-path .gitignore .

!!! troubleshooting "Missing Custom Ignore Files" If you define a custom ignore path via --ignore-path and the target file does not exist, markdownlint-cli exits with code 1 and prints an ENOENT error. Ensure the path is correct before running your command.

Exclusions via --ignore

You can also configure exclusions directly in your command line execution using the -i or --ignore flag. Specify the flag multiple times to ignore multiple patterns:

markdownlint . --ignore "node_modules/**" --ignore "vendor/cache" --ignore "docs/archive/*.md"

Quote Arguments to Avoid Shell Expansion Issues

Always wrap your glob patterns in quotes. If you run an unquoted glob pattern like --ignore **/*.md in Linux or macOS, the shell expands the pattern into a list of file paths before launching markdownlint-cli.

Because --ignore accepts a single pattern parameter, only the first expanded file path is ignored, and the remaining paths are evaluated as targets to check.

# Correct: Passes the glob pattern string directly to the internal matcher
markdownlint . --ignore 'legacy/**/*.md'

# Incorrect: Expanded by the shell, ignoring only the first matching file
markdownlint . --ignore legacy/**/*.md