Fixing Style Issues Automatically

Formatting issues like missing blank lines around headings, extra trailing spaces, or missing trailing newlines at the end of files can be tedious to fix manually. markdownlint-cli features automated, in-place corrections via the --fix parameter.

The Auto-Fix Engine Pipeline

When you run the tool with -f or --fix, the engine follows a specific sequence to update your files:

1. Read markdown file into memory.
2. Run synchronous lint checks across active rulesets.
3. Filter out identified violations that do not contain a 'fixInfo' metadata payload.
4. Call the 'applyFixes' helper to resolve fixable issues in memory.
5. Compare the updated text with your original document.
6. Save updates back to disk using UTF-8 encoding.

Core Rules that Support Auto-Fixing

Not all style violations can be solved automatically. For example, rules that inspect text quality or require semantic changes cannot be automated. Only rules that target structural whitespace or simple syntax updates support auto-fixing.

Examples of Fixable Violations:

  • MD022 (blanks-around-headings): Inserts missing empty lines directly before or after heading tags.
  • MD047 (single-trailing-newline): Automatically adds a trailing newline to the end of your Markdown file if it is missing.
  • Whitespace Anomalies: Strips trailing spaces at the ends of paragraphs or adjusts excessive empty line spans.

Violations requiring manual fixes:

  • MD014 (commands-show-output): Strips out manual console user prompts ($) preceding command outputs. These must be formatted using clean code blocks to prevent syntax errors.
  • MD041 (first-line-h1): Missing top-level title headers must be written by content authors.
  • Complex Layout Violations: Complex violations like broken reference link paths cannot be automated without risking layout issues.

Step-by-Step Scenario

Let's look at how the tool automatically corrects formatting issues.

1. Identify Broken Source (incorrect.md):

## header 2
# header

```fence
$ code

This document has several formatting issues:

- It begins with an `H2` heading instead of an `H1` top-level heading (`MD041`).
- There is no blank line between the first and second headings (`MD022`).
- It uses a leading terminal command prompt token (`$`) inside a raw output block (`MD014`).

### 2. Run the Auto-Fix Command:

```bash
markdownlint --fix incorrect.md

3. Review the Updated Output (incorrect.md):

## header 2

# header

```fence
$ code

Notice that the tool successfully inserted a blank line between the headings to resolve the `MD022` violation. 

Because the other issues require manual input, the linter outputs the remaining unresolved warnings to the terminal and exits with exit code `1`:

```text
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"]

Safe Practices for Auto-Fixing

Because the --fix engine writes modifications directly to your file system, keep these safety precautions in mind:

  • Check in your files: Always commit your active changes to a version control system (like Git) before running --fix. This ensures you can review or revert any automated edits.
  • Verify after run: Run git diff after executing --fix to check the changes made by the tool.
  • Restrict Build Pipeline Fixes: Avoid running --fix during deployment or build pipeline runs. Treat continuous integration pipelines as verification steps—fail the build if style errors exist, and require developers to run fixes locally before committing changes.