MkDocs Flavor¶

For projects using MkDocs or Material for MkDocs.

Supported Patterns¶

Auto-References¶

MkDocs autorefs plugin allows shorthand links to documented objects:

See [ClassName][] for details.
Use [module.function][] in your code.

Affected rules: MD042 (empty links), MD052 (reference links)

Admonitions¶

MkDocs admonition syntax is recognized:

!!! 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:

=== "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:

--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:

<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:

```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:

::: module.path
    options:
        show_source: true

::: package.submodule.Class

Affected rules: MD031 (blanks around fences), MD038 (code spans)

PyMdown Blocks¶

PyMdown Blocks syntax using /// fences is recognized:

/// details | Summary
    type: warning

Content inside the block.

///

/// caption
Figure 1: Example diagram
///

/// html | div.custom-class

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:

++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¶

Configuration¶

[global]
flavor = "mkdocs"

Or for specific directories:

[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:

Python-Markdown Extensions¶

PyMdown Extensions¶

mkdocstrings¶

See Also¶

• Flavors Overview - Compare all flavors
• MkDocs Documentation
• Material for MkDocs
• PyMdown Extensions
• mkdocstrings