Lint MkDocs Markdown with rumdl¶

Use rumdl's mkdocs flavor to lint MkDocs and Material for MkDocs projects without treating valid admonitions, content tabs, snippets, mkdocstrings blocks, or common extension syntax as ordinary Markdown errors. The flavor changes how relevant rules interpret MkDocs constructs; it does not disable linting for the rest of the document.

[global]
flavor = "mkdocs"

Then run a read-only check:

rumdl check docs/

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