markdownlint-cli2 custom rules for validating Material for MkDocs syntax including admonitions, content tabs, and code annotations
npm install mkdocs-material-linter

A markdownlint-cli2 plugin that provides custom rules for validating Material for MkDocs-specific markdown syntax.
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.
| 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 |
This is a plugin for markdownlint-cli2. You need to have markdownlint-cli2 installed and configured in your project first:
``bash`
npm install markdownlint-cli2 --save-dev
`bash`
npm install mkdocs-material-linter --save-devor
yarn add -D mkdocs-material-linteror
pnpm add -D mkdocs-material-linter
Add this plugin to your existing .markdownlint-cli2.jsonc configuration:
`json`
{
"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
}
}
`bashLint all markdown files
npx markdownlint-cli2
$3
Install the markdownlint extension, then add to
.vscode/settings.json:`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:
`json
{
"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
$3
`bash
npm test # Run all tests
npm run lint # Run ESLint
`$3
`bash
1. Update version
npm version patch # or minor/major2. Publish to npm
npm publish3. Create git tag
git push --tags
``