mkdocs-material-linter

A markdownlint-cli2 plugin that provides custom rules for validating Material for MkDocs-specific markdown syntax.

Why This Exists

Material for MkDocs extends standard Markdown with powerful features like admonitions (!!!), content tabs (===), and collapsible blocks (???). However, standard markdown linters don't understand this syntax and can't validate it. This leads to:

• Silent failures - Invalid admonition types that don't render
• Inconsistent formatting - Mixed indentation breaking content blocks
• Broken features - Malformed content tabs or annotations that don't work
• Poor navigation - Heading structures that create confusing documentation sites

This plugin ensures your Material for MkDocs documentation is valid, consistent, and follows best practices before you build your site.

Provided Rules

| Rule Name | Severity | Description | |-----------|----------|-------------| | material-admonition-types | Error | Validates only supported admonition types (note, warning, tip, etc.) | | material-admonition-indentation | Error | Enforces 4-space indentation for admonition content | | material-admonition-empty | Error | Detects admonitions with no content (forgot to indent) | | material-admonition-empty-title | Warning | Prevents empty title quotes in admonitions | | material-content-tabs | Error | Validates === delimiter syntax and tab structure | | material-code-annotations | Warning | Ensures annotation comment style matches code language | | material-navigation-structure | Warning | Checks heading hierarchy and navigation best practices | | material-shell-language-standardization | Warning | Enforces using "shell" instead of "bash" or "sh" for shell code blocks | | material-bundle-exec-shell-type | Warning | Ensures code blocks starting with "bundle exec" use shell language type | | material-blank-lines-spacing | Warning | Ensures blank lines before and after headers and after code blocks | | material-code-block-syntax | Error | Code blocks must have proper syntax - no type on closing tag and all blocks must be closed |

Installation & Usage

Prerequisites

This is a plugin for markdownlint-cli2. You need to have markdownlint-cli2 installed and configured in your project first:

npm install markdownlint-cli2 --save-dev

Installation

npm install mkdocs-material-linter --save-dev
# or
yarn add -D mkdocs-material-linter
# or
pnpm add -D mkdocs-material-linter

Configuration

Add this plugin to your existing .markdownlint-cli2.jsonc configuration:

{
  "customRules": ["mkdocs-material-linter"],
  "config": {
    "material-admonition-types": true,
    "material-admonition-indentation": true,
    "material-admonition-empty": true,
    "material-admonition-empty-title": true,
    "material-code-annotations": true,
    "material-content-tabs": true,
    "material-navigation-structure": true,
    "material-shell-language-standardization": true,
    "material-bundle-exec-shell-type": true,
    "material-blank-lines-spacing": true,
    "material-code-block-syntax": true
  }
}

Running the Linter

# Lint all markdown files
npx markdownlint-cli2

# Lint specific files
npx markdownlint-cli2 "docs/**/*.md"

# Auto-fix issues where possible
npx markdownlint-cli2 --fix

# Add to package.json scripts
"scripts": {
  "lint:docs": "markdownlint-cli2",
  "lint:docs:fix": "markdownlint-cli2 --fix"
}

VS Code Integration

Install the markdownlint extension, then add to .vscode/settings.json:

{
  "markdownlint.customRules": ["mkdocs-material-linter"],
  "markdownlint.config": {
    "material-admonition-types": true,
    "material-admonition-indentation": true,
    "material-admonition-empty": true,
    "material-admonition-empty-title": true,
    "material-code-annotations": true,
    "material-content-tabs": true,
    "material-navigation-structure": true,
    "material-shell-language-standardization": true,
    "material-bundle-exec-shell-type": true,
    "material-blank-lines-spacing": true,
    "material-code-block-syntax": true
  }
}

Advanced Configuration

Each rule can be individually enabled/disabled or configured:

{
  "config": {
    "material-admonition-types": false,
    "material-admonition-indentation": true,
    "material-code-annotations": "warning",
    "material-content-tabs": true,
    "material-navigation-structure": true
  }
}

FAQ

Q: Why do I get errors about missing dependencies? A: Make sure you have markdownlint >= 0.30.0 installed as a peer dependency.

Q: Can I disable specific rules? A: Yes! Set any rule to false in your config or use "off".

Q: Does this work with regular markdownlint (not CLI2)? A: Yes, but markdownlint-cli2 is recommended for better performance and features.

Q: Can I use this with other Material themes? A: This is specifically designed for Material for MkDocs. Other themes may have different syntax.

Development

Testing

npm test        # Run all tests
npm run lint    # Run ESLint

Releasing

# 1. Update version
npm version patch  # or minor/major

# 2. Publish to npm
npm publish

# 3. Create git tag
git push --tags