eslint-mdx

The mdx/remark rule integrates with remark-lint plugins. Because these rules are handled by the remark engine, you cannot disable or change their severity directly in your ESLint configuration. Instead, you must modify your remark configuration file.

To change severity, use the array syntax in your remark config (e.g., [rule-name, [severity]] where 2 is error and 0 is disabled).

{
  "plugins": [
    "@1stg/remark-config",
    // change to error severity, notice `[]` is required
    ["lint-no-duplicate-headings", [2]],
    // disable following plugin
    [
      "lint-no-multiple-toplevel-headings",
      [0], // or false
    ],
  ],
}

Install the MDX ESLint plugin as a development dependency using either npm or yarn.

# yarn
yarn add -D eslint-plugin-mdx

# npm
npm i -D eslint-plugin-mdx

The eslint-plugin-mdx package exports its core functionality through several modules. To use the plugin in an ESLint configuration, you will primarily interact with the exported rules, configurations, and processors.

• Rules: Individual linting rules for MDX files.
• Configs: Pre-defined sets of rules (e.g., recommended configurations) that can be easily integrated into your ESLint setup.
• Processors: Logic that allows ESLint to parse and lint content within MDX files, often used to lint code blocks or specific MDX elements.
• Helpers & Meta: Internal utilities and metadata used by the plugin.

The plugin provides two distinct sets of configurations based on the ESLint configuration system you are using:

Legacy Config (for .eslintrc files)

Use these for older ESLint setups. They are compatible with the Linter.LegacyConfig type:

• base
• codeBlocks (or 'code-blocks')
• overrides
• recommended

Flat Config (for eslint.config.js)

Use these for the modern ESLint Flat Config system. They are compatible with the Linter.FlatConfig type:

• flat
• flatCodeBlocks

When using remark-lint alongside Prettier, Prettier may insert blank lines that invalidate ESLint disable comments like {/* eslint-disable-line mdx/remark */}.

To avoid this, use block-style disable/enable comments instead:

{/* eslint-disable mdx/remark */}

# Heading

{/* eslint-enable mdx/remark */}

Alternatively, use remark-preset-prettier in your remark configuration to automatically disable rules that conflict with Prettier.

{
  "plugins": [
    "preset-lint-consistent",
    "preset-lint-recommended",
    "preset-lint-markdown-style-guide",
    "preset-prettier"
  ]
}

The eslint-mdx parser exports custom ESTree node types for MDX-specific structures:

• MDXCode: Represents code blocks within MDX.
• MDXHeading: Represents markdown headings within MDX.

These can be used when writing custom ESLint rules for MDX content.

import type { BaseNode } from 'estree'
import type { JSXElement } from 'estree-jsx'

export interface MDXCode extends BaseNode {
  type: 'MDXCode'
  value: string
  lang?: string | null
  meta?: string | null
}

export type HeadingDepth = 1 | 2 | 3 | 4 | 5 | 6

export interface MDXHeading extends BaseNode {
  type: 'MDXHeading'
  depth: HeadingDepth
  children: JSXElement['children']
}

The eslint-plugin-mdx processor uses the settings object in your ESLint configuration to pass options to the MDX processor. You can control how code blocks and remark configurations are handled by providing specific keys under the mdx/ namespace within your settings object.

Supported setting keys:

• mdx/code-blocks: Configures code block processing.
• mdx/language-mapper: Provides a mapping for languages used in code blocks.
• mdx/ignore-remark-config: A boolean flag to ignore remark configuration.
• mdx/remark-config-path: Specifies the path to a remark configuration file.

// Example ESLint configuration (e.g., .eslintrc.js or eslint.config.js)
module.exports = {
  settings: {
    'mdx/code-blocks': true,
    'mdx/language-mapper': {
      'js': 'javascript'
    },
    'mdx/ignore-remark-config': false,
    'mdx/remark-config-path': './.remarkrc'
  }
};

The mdx/flat configuration object is a pre-configured ESLint Flat Config preset designed for MDX files. It sets up the eslint-mdx parser, enables JSX support, configures the remark processor, and includes the mdx plugin with recommended rules. It targets all .md and .mdx files and sets React as a non-global variable.

import { flat } from 'eslint-plugin-mdx'

export default [
  {
    // ... your other configs
  },
  flat
]

The eslint-plugin-mdx package provides a recommended configuration object that can be used in your ESLint configuration to enable standard MDX linting rules. This preset includes base MDX rules and specific overrides for .md and .mdx files, including support for code blocks.

If eslint-plugin-prettier is detected in your environment (specifically versions compatible with the plugin's internal logic), the recommended config also automatically injects Prettier rules for Markdown and MDX files to ensure consistent formatting.

// Example usage in an ESLint configuration file
export default [
  {
    // ... other configs
  },
  recommended,
];