Lint MDX with rumdl¶

rumdl automatically selects its mdx flavor for .mdx files. The flavor keeps Markdown rules active while recognizing JSX components, JSX expressions, React-style attributes, comments, and ESM imports that would otherwise resemble invalid HTML or Markdown.

rumdl check '**/*.mdx'

Use an explicit per-file mapping only when MDX content has a different file extension.

Markdown inside JSX¶

Markdown links and images are recognized inside both custom components and lowercase JSX elements, including generated HTML-style reference tables:

<table>
  <tbody>
    <tr><td>[Documentation](/docs)</td></tr>
  </tbody>
</table>

Blank lines inside the table do not change whether the link is parsed. MD091 therefore does not flag it, while link rules such as MD042 (empty links) and MD059 (descriptive link text) still check it. Inline code and fenced code inside JSX remain code.

JSX attributes and JavaScript expressions are separate from Markdown. For example, {'[example](url)'} is a JavaScript string, so Markdown link rules do not check it. Strings, comments, regular expressions, and nested JSX are taken into account when locating the end of an expression.

Supported Patterns¶

JSX Components¶

Capitalized tags are treated as JSX components, not HTML:

<Button onClick={handleClick}>Click me</Button>

<Card title="Example">
  Content inside component.
</Card>

<MyCustomComponent prop={value} />

Affected rules: MD033 (inline HTML)

JSX Attributes¶

Elements with JSX-specific attributes are recognized as JSX, not HTML:

<!-- These use JSX attributes and are not flagged -->
<div className="container">...</div>
<label htmlFor="input-id">Label</label>
<button onClick={handler}>Click</button>
<input onChange={handleChange} />

JSX-specific attributes include: className, htmlFor, onClick, onChange, onSubmit, dangerouslySetInnerHTML, and other camelCase event handlers.

Affected rules: MD033 (inline HTML)

JSX Expressions¶

JSX expressions and comments are recognized:

The value is {computedValue}.

{/* This is a JSX comment */}

<Component prop={expression} />

Affected rules: MD037 (no space in emphasis), MD039 (no space in links), MD044 (proper names), MD049 (emphasis style)

ESM Imports/Exports¶

MDX 2.0+ supports ESM anywhere in the document:

import { Component } from './component'
export const metadata = { title: 'Page' }

# Heading

<Component />

Affected rules: MD013 (line length - ESM lines can be longer)

Rule Behavior Changes¶

Rule	Standard Behavior	MDX Behavior
MD013	Check all line lengths	Allow longer ESM import/export lines
MD033	Flag all inline HTML	Allow JSX components and JSX attributes
MD037	Check emphasis spacing	Skip JSX expressions
MD039	Check link spacing	Skip JSX expressions
MD044	Check proper names	Skip inside JSX expressions
MD049	Check emphasis style	Skip JSX expressions

Limitations¶

Complex nested JSX expressions may not be fully parsed
MDX compile-time expressions are treated as runtime expressions

Configuration¶

[global]
flavor = "mdx"

Or auto-detect by file extension:

[per-file-flavor]
"**/*.mdx" = "mdx"

Note: .mdx files are auto-detected as MDX flavor by default.

When to Use¶

Use the MDX flavor when:

Building sites with Docusaurus
Using Next.js with MDX
Writing interactive documentation with React components
Using any MDX-based framework