eslint-mdx

ESLint Parser/Plugin for MDX, helps you lint all ES syntaxes. Linting code blocks can be enabled with mdx/code-blocks setting too! Work perfectly with eslint-plugin-import, eslint-plugin-prettier or any other eslint plugins. And also can be integrated with remark-lint plugins to lint markdown syntaxes.

VSCode Extension

VSCode MDX: Integrates with VSCode ESLint, syntaxes highlighting and error reporting.

Packages

This repository is a monorepo managed by changesets what means we actually publish several packages to npm from same codebase, including:

Package	Description	Version
`eslint-mdx`	ESLint Parser for MDX
`eslint-plugin-mdx`	ESLint Plugin, Configuration and Rules for MDX

Install

# yarn
yarn add -D eslint-plugin-mdx

# npm
npm i -D eslint-plugin-mdx

Notice

If you're using multi languages, js/jsx/ts/tsx/vue, etc for example, you'd better to always use overrides (Classic Config) or files (Flag Config) feature of ESLint, because configs may be overridden by following configs.
See #251 for more details.
If you're using {/* eslint-disable-line mdx/remark */} with prettier, this won't work because prettier will add a blank line after the comment, which makes it invalid. You can use {/* eslint-disable mdx/remark */} paired with {/* eslint-enable mdx/remark */} instead:
```
{/* eslint-disable mdx/remark */}

# Heading

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

Usage

Classic Config

.eslintrc file:

{
  "extends": ["plugin:mdx/recommended"],
  // optional, if you want to lint code blocks at the same time
  "settings": {
    "mdx/code-blocks": true,
    // optional, if you want to disable language mapper, set it to `false`
    // if you want to override the default language mapper inside, you can provide your own
    "mdx/language-mapper": {},
    // optional, same as the `parserOptions.ignoreRemarkConfig`, you have to specify it twice unfortunately
    "mdx/ignore-remark-config": true,
    // optional, same as the `parserOptions.remarkConfigPath`, you have to specify it twice unfortunately
    "mdx/remark-config-path": "path/to/your/remarkrc",
  },
}

Flat Config

eslint.config.js file:

import * as mdx from 'eslint-plugin-mdx'

export default [
  {
    ...mdx.flat,
    // optional, if you want to lint code blocks at the same
    processor: mdx.createRemarkProcessor({
      lintCodeBlocks: true,
      // optional, if you want to disable language mapper, set it to `false`
      // if you want to override the default language mapper inside, you can provide your own
      languageMapper: {},
      // optional, same as the `parserOptions.ignoreRemarkConfig`, you have to specify it twice unfortunately
      ignoreRemarkConfig: true,
      // optional, same as the `parserOptions.remarkConfigPath`, you have to specify it twice unfortunately
      remarkConfigPath: 'path/to/your/remarkrc',
    }),
  },
  {
    ...mdx.flatCodeBlocks,
    rules: {
      ...mdx.flatCodeBlocks.rules,
      // if you want to override some rules for code blocks
      'no-var': 'error',
      'prefer-const': 'error',
    },
  },
]

Then, make sure ESLint knows to run on .md or .mdx files:

eslint . --ext js,md,mdx

Parser Options

extensions (string | string[]): eslint-mdx will only resolve .mdx files by default, if you want to resolve other extensions as like .mdx, you can use this option.
markdownExtensions (string | string[]): eslint-mdx will only treat .md files as plain markdown by default, and will lint them via remark plugins. If you want to resolve other extensions as like .md, you can use this option.
ignoreRemarkConfig (boolean): Ignore the remark configuration defined in the project.
remarkConfigPath (string): Specify the path to the remark configuration file, could be relative to CWD or absolute path.

Parser API

eslint-mdx returns an ESTree Program. In addition to standard ESTree and JSX nodes, it emits custom nodes for Markdown content and MDX expressions.

Markdown content nodes

Markdown content uses the MD prefix, while MDX-specific nodes use MDX. The prefix avoids collisions with ESTree/JSX nodes. All nodes are exposed in Program.body or as children of other nodes and are traversed through the parser visitor keys.

ESTree node	mdast node	Notes
`MDBlockquote`	`blockquote`
`MDBreak`	`break`
`MDCode`	`code`
`MDDefinition`	`definition`
`MDDelete`	`delete`	`remark-gfm`
`MDEmphasis`	`emphasis`
`MDFootnoteDefinition`	`footnoteDefinition`	`remark-gfm`
`MDFootnoteReference`	`footnoteReference`	`remark-gfm`
`MDHeading`	`heading`
`MDImage`	`image`
`MDImageReference`	`imageReference`
`MDInlineCode`	`inlineCode`
`MDInlineMath`	`inlineMath`	`remark-math`
`MDLink`	`link`
`MDLinkReference`	`linkReference`
`MDList`	`list`
`MDListItem`	`listItem`
`MDMath`	`math`	`remark-math`
`MDParagraph`	`paragraph`
`MDStrong`	`strong`
`MDTable`	`table`	`remark-gfm`
`MDTableCell`	`tableCell`	`remark-gfm`
`MDTableRow`	`tableRow`	`remark-gfm`
`MDText`	`text`
`MDThematicBreak`	`thematicBreak`
`MDToml`	`toml`	`remark-frontmatter`
`MDYaml`	`yaml`	`remark-frontmatter`

For example:

# Heading

Paragraph with **strong**, _emphasis_, `inlineCode`, [link](https://example.com), and ![image](https://example.com/image.png).

> Blockquote

- list item

```js
const value = 1
```

MDXCode and MDXHeading were renamed to MDCode and MDHeading; the old names are no longer emitted.

MDX expression nodes

MDX expressions use the MDX prefix and expose their ESTree expression:

ESTree node	mdast node
`MDXFlowExpression`	`mdxFlowExpression`
`MDXTextExpression`	`mdxTextExpression`

When these expressions are used as JSX children, they are wrapped in JSXExpressionContainer. Empty or comment-only expressions use JSXEmptyExpression.

For example:

{value}

> {value}

The value is {value}.

Typings

import type { BaseNode, Expression } from 'estree'
import type {
  JSXElement,
  JSXEmptyExpression,
  JSXExpressionContainer,
  JSXFragment,
  JSXSpreadChild,
  JSXText,
} from 'estree-jsx'

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

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

export interface MDHeading extends BaseNode {
  type: 'MDHeading'
  depth: HeadingDepth
  children: MDContentNode[]
}

export interface MDXFlowExpression extends BaseNode {
  type: 'MDXFlowExpression'
  expression: Expression | JSXEmptyExpression
}

export interface MDXTextExpression extends BaseNode {
  type: 'MDXTextExpression'
  expression: Expression | JSXEmptyExpression
}

export interface MDText extends BaseNode {
  type: 'MDText'
  value: string
}

export interface MDParagraph extends BaseNode {
  type: 'MDParagraph'
  children: MDContentNode[]
}

export interface MDBlockquote extends BaseNode {
  type: 'MDBlockquote'
  children: MDContentNode[]
}

export interface MDList extends BaseNode {
  type: 'MDList'
  ordered?: boolean | null
  start?: number | null
  spread?: boolean | null
  children: MDListItem[]
}

export interface MDListItem extends BaseNode {
  type: 'MDListItem'
  checked?: boolean | null
  spread?: boolean | null
  children: MDContentNode[]
}

export interface MDEmphasis extends BaseNode {
  type: 'MDEmphasis'
  children: MDContentNode[]
}

export interface MDStrong extends BaseNode {
  type: 'MDStrong'
  children: MDContentNode[]
}

export interface MDInlineCode extends BaseNode {
  type: 'MDInlineCode'
  value: string
}

export interface MDLink extends BaseNode {
  type: 'MDLink'
  url: string
  title?: string | null
  children: MDContentNode[]
}

export interface MDImage extends BaseNode {
  type: 'MDImage'
  url: string
  title?: string | null
  alt?: string | null
}

export interface MDBreak extends BaseNode {
  type: 'MDBreak'
}

export interface MDThematicBreak extends BaseNode {
  type: 'MDThematicBreak'
}

export interface MDDefinition extends BaseNode {
  type: 'MDDefinition'
  identifier: string
  label?: string | null
  url: string
  title?: string | null
}

export interface MDDelete extends BaseNode {
  type: 'MDDelete'
  children: MDContentNode[]
}

export interface MDFootnoteDefinition extends BaseNode {
  type: 'MDFootnoteDefinition'
  identifier: string
  label?: string | null
  children: MDContentNode[]
}

export interface MDFootnoteReference extends BaseNode {
  type: 'MDFootnoteReference'
  identifier: string
  label?: string | null
}

export interface MDImageReference extends BaseNode {
  type: 'MDImageReference'
  identifier: string
  label?: string | null
  referenceType: 'collapsed' | 'full' | 'shortcut'
  alt?: string | null
}

export interface MDInlineMath extends BaseNode {
  type: 'MDInlineMath'
  value: string
}

export interface MDLinkReference extends BaseNode {
  type: 'MDLinkReference'
  identifier: string
  label?: string | null
  referenceType: 'collapsed' | 'full' | 'shortcut'
  children: MDContentNode[]
}

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

export interface MDTable extends BaseNode {
  type: 'MDTable'
  align?: Array<'center' | 'left' | 'right' | null> | null
  children: MDTableRow[]
}

export interface MDTableCell extends BaseNode {
  type: 'MDTableCell'
  children: MDContentNode[]
}

export interface MDTableRow extends BaseNode {
  type: 'MDTableRow'
  children: MDTableCell[]
}

export interface MDToml extends BaseNode {
  type: 'MDToml'
  value: string
}

export interface MDYaml extends BaseNode {
  type: 'MDYaml'
  value: string
}

export type MDContentNode =
  | JSXElement
  | JSXExpressionContainer
  | JSXFragment
  | JSXSpreadChild
  | JSXText
  | MDBlockquote
  | MDBreak
  | MDCode
  | MDDefinition
  | MDDelete
  | MDEmphasis
  | MDFootnoteDefinition
  | MDFootnoteReference
  | MDHeading
  | MDImage
  | MDImageReference
  | MDInlineCode
  | MDInlineMath
  | MDLink
  | MDLinkReference
  | MDList
  | MDListItem
  | MDMath
  | MDParagraph
  | MDStrong
  | MDTable
  | MDTableCell
  | MDTableRow
  | MDText
  | MDThematicBreak
  | MDToml
  | MDXFlowExpression
  | MDXTextExpression
  | MDYaml

Rules

mdx/remark

possible fixable depends on your remark plugins:

Integration with remark-lint plugins, it will read remark's configuration automatically via unified-engine. But .remarkignore will not be respected, you should use .eslintignore instead.

If you want to disable or change severity of some related rules, it won't work by setting rules in eslint config like 'remark-lint-no-duplicate-headings': 0, you should change your remark config instead like following:

{
  "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
    ],
  ],
}

Prettier Integration

If you're using remark-lint feature with Prettier both together, you can try remark-preset-prettier which helps you to turn off all rules that are unnecessary or might conflict with Prettier.

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

Sponsors and Backers

Backers

1stG	RxTS	UnRS	UnTS

Changelog

Detailed changes for each release are documented in CHANGELOG.md.

unified

Project: mdx-js/eslint-mdx

Package: eslint-mdx@2.0.5

TOC