mdx-js/eslint-mdx: ESLint Parser/Plugin for 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 | npm</a> | | 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

`MDXCode`

A new MDXCode estree node type is exported from eslint-mdx which represents code blocks in mdx like the following:

<div>

js
  export function foo() {
    return 'bar'
  }
  </div>

`MDXHeading`

A new MDXHeading estree node type is exported from eslint-mdx which represents markdown heading in mdx like the following:

<div>
Here's a text gradient short code!
</div>

Typings

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']
}

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

Changelog

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

License

[1stg.me]: https://www.1stG.me [changesets]: https://github.com/changesets/changesets [eslint]: https://eslint.org [jounqin]: https://github.com/JounQin [mdx]: https://github.com/mdx-js/mdx [mit]: http://opensource.org/licenses/MIT [prettier]: https://prettier.io [remark-lint]: https://github.com/remarkjs/remark-lint [remark-preset-prettier]: https://github.com/un-ts/remark-preset-prettier [unified-engine]: https://github.com/unifiedjs/unified-engine [vscode eslint]: https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint [vscode mdx]: https://github.com/mdx-js/mdx-analyzer/tree/main/packages/vscode-mdx