Usage¶
Linting files¶
Lint the current directory (recursively finds all Markdown files):
mdlint check
Lint specific files:
mdlint check README.md docs/guide.md
Lint a directory recursively:
mdlint check docs/
Directories are searched for files ending in .md, .markdown, .mdown, .mkd or .mkdn. Files named on the
command line are linted whatever their extension, unless they match an exclude pattern.
Lint from stdin:
cat README.md | mdlint check -
Output formats¶
Human-readable terminal output (default):
$ mdlint check docs/
docs/usage.md (2)
6:1 MD041 First heading should be h1, found h2
52:1 MD040 Fenced code block without language specified
✘ Found 2 violations in 1 file (5 files checked)
JSON output for programmatic use:
$ mdlint check --format json docs/
{
"files": [
{
"path": "docs/usage.md",
"violations": [
{
"line": 6,
"column": 1,
"rule_id": "MD041",
"rule_name": "first-line-heading",
"message": "First heading should be h1, found h2",
"context": "## Usage"
},
{
"line": 56,
"column": 1,
"rule_id": "MD040",
"rule_name": "fenced-code-language",
"message": "Fenced code block without language specified",
"context": "```"
}
],
"error": null
}
],
"summary": {
"files_checked": 5,
"files_with_violations": 1,
"files_with_errors": 0,
"total_violations": 2,
"exit_code": 1
}
}
Show the in-file context of the found error:
$ mdlint check --show-context docs/
docs/usage.md (2)
6:1 MD041 First heading should be h1, found h2
4: ---
5:
6: ## Usage
^
7:
8: ## Linting files
88:1 MD040 Fenced code block without language specified
86: Show the in-file context of the found error:
87:
88: ```
^
89: $ mdlint check --show-context docs/
90: docs/usage.md (2)
✘ Found 2 violations in 1 file (5 files checked)
Additional options¶
# Disable .gitignore and .ignore patterns
mdlint check --no-ignore
# Show files being processed
mdlint check --verbose
# List files that would be linted without linting them
mdlint check --show-files
Auto-fixing violations¶
Use --fix to automatically correct fixable violations:
# Fix violations in files in-place
mdlint check --fix docs/
# Fix a single file
mdlint check --fix README.md
# Fix stdin and output the result to stdout
cat README.md | mdlint check --fix -
Not all rules support auto-fixing. When --fix is used:
- Fixable rules are applied sequentially to each file, in repeated passes because one rule's fix can leave work for another; passes continue while they reduce the number of fixable violations, up to 10
- A rule with a violation suppressed by an inline directive is not applied to that file, so the suppressed lines are left untouched and the rule's other violations there are still reported
- Fixes that only change formatting, such as list indentation or heading style, are discarded for a file if they would change how the document renders; those violations are still reported for you to fix by hand
- Files are modified in-place with the corrected content, keeping their line endings (LF or CRLF) and any byte order mark
- Any remaining unfixable violations are still reported in the output
- The rules index shows which rules are fixable with a checkmark in the "Fixable" column
When used with stdin (-), the fixed content is written to stdout. This is useful for editor integrations that pipe
content through external formatters.
The exit code behavior is unchanged: exit code 1 if any violations remain after fixing, 0 if all violations were
fixed or there were none.
Viewing rule documentation¶
List all available rules:
mdlint rule
View details for a specific rule, by ID or name:
mdlint rule MD001
mdlint rule line-length
Include valid/invalid examples:
mdlint rule MD003 --show-examples
Inline suppression¶
You can suppress specific rule violations inline using HTML comment directives (ignored inside code blocks). This is useful when a violation is intentional, and you don't want to disable the rule globally.
Suppress one or more rules from a specific point until re-enabled:
<!-- mdlint: disable MD013 -->
This long line (if it were long enough) will not trigger MD013.
<!-- mdlint: enable MD013 -->
<!-- mdlint: disable MD001 MD013 -->
...
<!-- mdlint: enable -->
Rules can be referenced by ID or by name, in any case, and separated by spaces, commas, or both. For example, MD013,
md013 and line-length all refer to the same rule:
<!-- mdlint: disable no-inline-html, MD013 -->
Unknown rule IDs and names are silently ignored; the remaining rules in the directive still apply. A directive that names only unknown rules has no effect.
You can selectively re-enable specific rules after a disable comment:
<!-- mdlint: disable -->
<!-- mdlint: enable MD001 -->
### MD001 still applies here, but other rules are suppressed.
<!-- mdlint: enable -->
Suppress one or more rules for just the line immediately following the comment:
<!-- mdlint: disable-next-line MD001 -->
### This heading won't trigger MD001
Suppression comments are automatically exempt from triggering MD033 (no-inline-html) violations
Exit codes¶
| Code | Meaning |
|---|---|
| 0 | No violations and no errors |
| 1 | Violations found, even if some files could not be read |
| 2 | Invalid configuration, unknown rule or missing path; or files could not be read and no violations were found |