# MkDocs Flavor
For projects using [MkDocs](https://www.mkdocs.org/) or [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/).
## Supported Patterns
### Auto-References
MkDocs autorefs plugin allows shorthand links to documented objects:
```markdown
See [ClassName][] for details.
Use [module.function][] in your code.
```
**Affected rules**: MD042 (empty links), MD052 (reference links)
### Admonitions
MkDocs admonition syntax is recognized:
```markdown
!!! note "Title"
Content inside admonition.
!!! warning
Warning content.
??? tip "Collapsible"
Hidden content.
```
**Affected rules**: MD031 (blanks around fences), MD046 (code block style)
### Content Tabs
Material for MkDocs tab syntax:
```markdown
=== "Tab 1"
Content for tab 1.
=== "Tab 2"
Content for tab 2.
```
**Affected rules**: MD046 (code block style)
### Snippets
MkDocs snippets for including external files:
```markdown
--8<-- "path/to/file.md"
;--8<--
```
**Affected rules**: MD024 (duplicate headings), MD052 (reference links)
### HTML with Markdown Attribute
Allows `markdown`, `markdown="1"`, or `markdown="block"` to enable Markdown processing inside HTML elements. This includes Material for MkDocs grid cards pattern:
```markdown
<div class="grid cards" markdown>
- :zap:{ .lg .middle } **Built for speed**
---
Written in Rust for blazing fast performance.
</div>
```
Supported elements: `div`, `section`, `article`, `aside`, `details`, `figure`, `footer`, `header`, `main`, `nav`.
**Affected rules**: MD030 (list marker space), MD033 (inline HTML), MD035 (HR style)
### Code Block Title Attribute
MkDocs allows `title=` on fenced code blocks:
````markdown
```python title="example.py"
print("Hello")
```
````
**Affected rules**: MD040 (fenced code language)
### Table Extensions
MkDocs table handling with extensions like `md_in_html`:
**Affected rules**: MD056 (table column count)
### mkdocstrings Blocks
mkdocstrings autodoc syntax is recognized:
```markdown
::: module.path
options:
show_source: true
::: package.submodule.Class
```
**Affected rules**: MD031 (blanks around fences), MD038 (code spans)
### PyMdown Blocks
[PyMdown Blocks](https://facelessuser.github.io/pymdown-extensions/extensions/blocks/) syntax using `///` fences is recognized:
```markdown
Content inside the block.
///
/// caption
Figure 1: Example diagram
///
Custom HTML content with markdown.
///
```
Block types include: `admonition`, `details`, `caption`, `html`, `tab`, and custom blocks.
**Affected rules**: MD012, MD018, MD022, MD025, MD030, MD033, MD036, MD057, MD059, MD064 (all skip content inside blocks)
### Extended Markdown Syntax
MkDocs extensions for special formatting:
```markdown
++inserted text++ <!-- ins extension -->
==marked text== <!-- mark extension -->
^^superscript^^ <!-- caret extension -->
~subscript~ <!-- tilde extension -->
[[keyboard keys]] <!-- keys extension -->
```
**Affected rules**: MD038 (code spans), MD049 (emphasis style), MD050 (strong style)
## Rule Behavior Changes
| MD024 | Flag duplicate headings | Skip headings in snippet sections |
| MD030 | Check list marker spacing | Skip inside markdown-enabled HTML |
| MD031 | Require blanks around all fences | Respect admonition/tab/mkdocstrings |
| MD033 | Flag all inline HTML | Allow `markdown` attribute on elements |
| MD035 | Check horizontal rule style | Skip inside markdown-enabled HTML |
| MD038 | Flag spaces in code spans | Handle keys/caret/mark syntax |
| MD040 | Require language on code blocks | Allow `title=` without language |
| MD042 | Flag empty links `[]()` | Allow auto-references `[Class][]` |
| MD046 | Detect code block style globally | Account for admonition/tab context |
| MD049 | Check emphasis consistency | Handle mark/inserted syntax |
| MD050 | Check strong consistency | Handle mark/caret/tilde syntax |
| MD051 | Validate all fragment links | Skip footnote and option anchors |
| MD052 | Flag undefined references | Allow auto-references and snippets |
| MD056 | Strict column count | Handle MkDocs table extensions |
| MD077 | Content column W+N indent | Enforce min 4-space continuation indent |
## Configuration
```toml
[global]
flavor = "mkdocs"
```
Or for specific directories:
```toml
[per-file-flavor]
"docs/**/*.md" = "mkdocs"
```
## When to Use
Use the MkDocs flavor when:
- Building documentation with MkDocs
- Using Material for MkDocs theme
- Using mkdocstrings for API documentation
- Using PyMdown Extensions
## Extension Support Reference
The MkDocs flavor provides lint-aware support for the common Python-Markdown and PyMdown Extensions used in the MkDocs ecosystem.
### Support Levels
Each extension has one of these support levels:
| Lint-safe | rumdl won't flag valid extension syntax as violations |
| Fix-safe | `--fix` preserves extension constructs unchanged |
| Format-aware | Reflow/formatting respects extension structure (e.g., preserves indentation during MD013 reflow) |
### Python-Markdown Extensions
| [abbr](https://python-markdown.github.io/extensions/abbreviations/) | Lint-safe, Fix-safe | Abbreviation definitions `*[HTML]: Hypertext Markup Language` |
| [admonition](https://python-markdown.github.io/extensions/admonition/) | Format-aware | Admonition blocks `!!! note` with indentation-aware reflow |
| [attr_list](https://python-markdown.github.io/extensions/attr_list/) | Lint-safe, Fix-safe | Attribute lists `{#id .class}` |
| [def_list](https://python-markdown.github.io/extensions/definition_lists/) | Lint-safe, Fix-safe | Definition lists with `:` markers |
| [footnotes](https://python-markdown.github.io/extensions/footnotes/) | Lint-safe, Fix-safe | Footnotes `[^1]`, definitions, and anchor links `#fn:1` |
| [md_in_html](https://python-markdown.github.io/extensions/md_in_html/) | Lint-safe, Fix-safe | `markdown="1"` attribute on HTML elements |
| [toc](https://python-markdown.github.io/extensions/toc/) | Lint-safe, Fix-safe | `[TOC]` markers are preserved |
| [tables](https://python-markdown.github.io/extensions/tables/) | Lint-safe, Fix-safe | Standard table support |
| [meta](https://python-markdown.github.io/extensions/meta_data/) | Lint-safe, Fix-safe | YAML frontmatter detection |
| [fenced_code](https://python-markdown.github.io/extensions/fenced_code_blocks/) | Lint-safe, Fix-safe | Fenced code blocks with attributes |
| [codehilite](https://python-markdown.github.io/extensions/code_hilite/) | N/A | Rendering-only (no linting impact) |
### PyMdown Extensions
| [arithmatex](https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/) | Lint-safe, Fix-safe | Math blocks `$$ ... $$` and inline `$...$` |
| [betterem](https://facelessuser.github.io/pymdown-extensions/extensions/betterem/) | Lint-safe, Fix-safe | Standard emphasis handling applies |
| [blocks](https://facelessuser.github.io/pymdown-extensions/extensions/blocks/) | Lint-safe, Fix-safe | PyMdown Blocks `/// type` with `///` fence syntax |
| [caret](https://facelessuser.github.io/pymdown-extensions/extensions/caret/) | Lint-safe, Fix-safe | Superscript `^text^` and insert `^^text^^` |
| [critic](https://facelessuser.github.io/pymdown-extensions/extensions/critic/) | Lint-safe, Fix-safe | Critic markup `{++add++}`, `{--del--}` |
| [details](https://facelessuser.github.io/pymdown-extensions/extensions/details/) | Lint-safe, Fix-safe | Collapsible blocks `??? note` and `???+ note` |
| [emoji](https://facelessuser.github.io/pymdown-extensions/extensions/emoji/) | Lint-safe, Fix-safe | Emoji/icon shortcodes `:material-check:` |
| [highlight](https://facelessuser.github.io/pymdown-extensions/extensions/highlight/) | N/A | Rendering-only (no linting impact) |
| [inlinehilite](https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/) | Lint-safe, Fix-safe | Inline code highlighting `` `#!python code` `` |
| [keys](https://facelessuser.github.io/pymdown-extensions/extensions/keys/) | Lint-safe, Fix-safe | Keyboard keys `++ctrl+alt+del++` |
| [mark](https://facelessuser.github.io/pymdown-extensions/extensions/mark/) | Lint-safe, Fix-safe | Highlighted text `==text==` |
| [smartsymbols](https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/) | Lint-safe, Fix-safe | Smart symbols `(c)`, `(tm)`, `-->` |
| [snippets](https://facelessuser.github.io/pymdown-extensions/extensions/snippets/) | Lint-safe, Fix-safe | File inclusion `--8<-- "file.md"` |
| [superfences](https://facelessuser.github.io/pymdown-extensions/extensions/superfences/) | Lint-safe, Fix-safe | Custom fences with language + attributes |
| [tabbed](https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/) | Format-aware | Content tabs `=== "Tab"` with indentation-aware reflow |
| [tasklist](https://facelessuser.github.io/pymdown-extensions/extensions/tasklist/) | Lint-safe, Fix-safe | Task lists `- [x] Task` (standard GFM) |
| [tilde](https://facelessuser.github.io/pymdown-extensions/extensions/tilde/) | Lint-safe, Fix-safe | Subscript `~text~` and strikethrough `~~text~~` |
### mkdocstrings
| [Auto-doc blocks](https://mkdocstrings.github.io/) | Format-aware | `::: module.Class` with YAML options, indentation-aware reflow |
| [Cross-references](https://mkdocstrings.github.io/) | Lint-safe, Fix-safe | `[module.Class][]` reference links |
## See Also
- [Flavors Overview](../flavors.md) - Compare all flavors
- [MkDocs Documentation](https://www.mkdocs.org/)
- [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)
- [PyMdown Extensions](https://facelessuser.github.io/pymdown-extensions/)
- [mkdocstrings](https://mkdocstrings.github.io/)