Quick Start Guide

This guide shows you how to run style checks on your Markdown documents, fix formatting violations automatically, and manage inline rule exceptions.

Step 1: Run Checks on a Single File

To evaluate a Markdown file, execute the tool with the relative path to your file as a positional argument:

markdownlint README.md

Understanding Standard Outputs

If violations exist, the CLI writes reports directly to standard error (STDERR). Each line in the output uses a standard structure:

[filename]:[line_number][::column_offset] [severity] [rule_names] [description] [details/context]

Real-World Output Example:

incorrect.md:1 error MD022/blanks-around-headings Headings should be surrounded by blank lines [Expected: 1; Actual: 0; Below] [Context: "## header 2"]
incorrect.md:1 error MD041/first-line-heading/first-line-h1 First line in a file should be a top-level heading [Context: "## header 2"]
incorrect.md:5:1 error MD014/commands-show-output Dollar signs used before commands without showing output [Context: "$ code"]

In this output:

  • incorrect.md:1: Points directly to line 1 of the document.
  • error MD022/blanks-around-headings: The type of violation, referencing both the alphanumeric identifier and the readable rule alias.
  • [Expected: 1; Actual: 0; Below]: Contextual details highlighting why the rule triggered.
  • [Context: "## header 2"]: Displays the offending line to make debugging easier.
  • incorrect.md:5:1: Displays an issue at line 5, column offset 1 (e.g., a CLI output issue).

If the document is structured correctly, the linter exits cleanly without printing any console output.

Step 2: Scan Folders recursively

You can lint whole directories to locate style deviations across several documents:

markdownlint docs/

markdownlint-cli recursively crawls the target directory, automatically parsing all files ending in .md or .markdown. Files using alternate extensions (such as .mdf or .txt) are ignored unless explicitly passed directly.

Step 3: Use Wildcards & Glob Patterns

You can target specific files or nested paths using wildcards.

Shell Globbing Differences (Crucial Details)

Your shell (e.g., Bash or Zsh) might try to expand glob patterns (like **/*.md) before launching the CLI. This can lead to issues because markdownlint-cli options like --ignore take a single argument, and shell expansion might only apply your option to the first matching file.

To avoid this, wrap all glob arguments in single quotes on Unix-like environments. This forces the shell to pass the raw glob string directly to markdownlint-cli's glob engine (tinyglobby), which then resolves all targets correctly.

Linux and macOS (Bash/Zsh):

# Correct: Quoted pattern passes through to internal resolver safely
markdownlint '**/*.md'

# Incorrect: Unquoted pattern may be expanded prematurely by your shell
markdownlint **/*.md

Windows Command Prompt (CMD):

Windows Command Prompt does not natively expand glob wildcards, so you can execute the command with or without quotes: 

markdownlint **/*.md

Step 4: Fix Basic Violations Automatically

markdownlint-cli features built-in formatting automation via the --fix parameter. This modifies your documents in-place to resolve easy-to-fix rules automatically:

markdownlint --fix README.md

Before and After Automated Fix Run

Let's look at how --fix handles typical formatting issues.

Original Markdown (incorrect.md):

## header 2
# header

```fence
$ code

#### Run the fix command:
```bash
markdownlint --fix incorrect.md

Generated Output (incorrect.md updated):

## header 2

# header

```fence
$ code

Notice that the linter added a missing blank line between the first and second headings to resolve the `MD022/blanks-around-headings` violation. 

However, the `MD041/first-line-h1` error (the document must begin with a top-level `#` heading) and `MD014` (dollar signs preceding terminal commands without showing output) still require manual resolution, and are printed to the console as remaining errors.

---

## Step 5: Inline File Overrides (JSONC & YAML)

To bypass rules for a particular document, write config parameters directly inside the file using HTML comments. These parameters take precedence over workspace configuration files.

### Disable Specific Rules inside a File
To disable rules like `MD013` (line-length) and `MD033` (inline HTML support) within a file, place this comment block at the top of your document:

```markdown
<!-- markdownlint-disable MD013 MD033 -->

# Document with Raw HTML

This is a long paragraph containing <span style="color:blue">raw HTML inline styling</span>, which now passes validations.

Provide Complex File Configurations via JSONC or YAML Comments

You can also configure specific rule settings inline using standard configuration formats:

Inline JSONC configuration:

# Project Standard Header

<!-- markdownlint-configure-file {
  // Temporarily increase line limit for inline data lists
  "line-length": {
    "line_length": 180
  }
} -->

Inline YAML configuration:

# Custom Section

<!-- markdownlint-configure-file
  no-multiple-blanks: false
-->

Next Steps