eslint-plugin-mdx

What is eslint-plugin-mdx?

eslint-plugin-mdx is an ESLint plugin that provides linting and formatting capabilities for MDX (Markdown with JSX) files. It helps ensure code quality and consistency in MDX files by applying ESLint rules.

What are eslint-plugin-mdx's main functionalities?

Linting MDX Files

This configuration enables linting for MDX files by extending the recommended settings provided by eslint-plugin-mdx.

module.exports = {
  "extends": [
    "plugin:mdx/recommended"
  ],
  "overrides": [
    {
      "files": ["*.mdx"],
      "extends": ["plugin:mdx/recommended"]
    }
  ]
};

Custom MDX Rules

This configuration demonstrates how to apply custom rules specifically for MDX files. In this example, the rule 'mdx/no-jsx-html-comments' is set to 'error'.

module.exports = {
  "overrides": [
    {
      "files": ["*.mdx"],
      "extends": ["plugin:mdx/recommended"],
      "rules": {
        "mdx/no-jsx-html-comments": "error"
      }
    }
  ]
};

Integrating with Prettier

This configuration shows how to integrate eslint-plugin-mdx with Prettier for consistent code formatting in MDX files.

module.exports = {
  "extends": [
    "plugin:mdx/recommended",
    "prettier"
  ],
  "overrides": [
    {
      "files": ["*.mdx"],
      "extends": ["plugin:mdx/recommended", "prettier/mdx"]
    }
  ]
};

Other packages similar to eslint-plugin-mdx

eslint-plugin-markdown

eslint-plugin-markdown is an ESLint plugin that allows linting of JavaScript code blocks within Markdown files. While it focuses on JavaScript within Markdown, eslint-plugin-mdx is specifically designed for MDX files, which combine Markdown and JSX.

remark-lint

remark-lint is a Markdown linter built on the remark ecosystem. It provides a wide range of rules for linting Markdown files. Unlike eslint-plugin-mdx, which is tailored for MDX files, remark-lint is focused solely on Markdown.

eslint-plugin-react

eslint-plugin-react is an ESLint plugin for React-specific linting rules. While it is not designed for MDX files, it can be used in conjunction with eslint-plugin-mdx to ensure React code within MDX files adheres to best practices.

README

ESLint Parser/Plugin for MDX, helps you lint all ES syntaxes excluding code block of course. 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.

TOC

• VSCode Extension
• Packages
• Install
• Usage
• Parser Options
• Rules
  • mdx/no-jsx-html-comments
  • mdx/no-unescaped-entities
  • mdx/no-unused-expressions
  • mdx/remark
• Prettier Integration
• Changelog
• License

VSCode Extension

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

Packages

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

Package	Description	Version	Peer Dependencies	Dependencies
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

Usage

1. In your ESLint config file:

   1. If you're using eslint >= 6.4.0, just add:

      {
        "extends": ["plugin:mdx/recommended"]
      }
      

   2. If you're using eslint >=6.0.0 and <6.4.0, add as following because it does not support overrides from npm pkg:

      {
        "extends": ["plugin:mdx/recommended"],
        "overrides": [
          {
            "files": ["*.md"],
            "rules": {
              "prettier/prettier": [
                2,
                {
                  // unnecessary if you're not using `eslint-plugin-prettier`, but required if you are
                  "parser": "markdown"
                }
              ]
            }
          },
          {
            "files": ["*.mdx"],
            "extends": ["plugin:mdx/overrides"]
          }
        ]
      }
      

   3. If you're using eslint@^5.0.0, you need to enable this parser/plugin manually, because eslint@5 does not support extends for overrides property in its configuration:

      const { configs } = require('eslint-plugin-mdx')
      
      module.exports = {
        extends: ['plugin:mdx/recommended'],
        overrides: [
          {
            files: ['*.md'],
            rules: {
              'prettier/prettier': [
                2,
                {
                  // unnecessary if you're not using `eslint-plugin-prettier`, but required if you are
                  parser: 'markdown',
                },
              ],
            },
          },
          Object.assign(
            {
              files: ['*.mdx'],
            },
            configs.overrides,
          ),
        ],
      }
      

2. Make sure ESLint knows to run on .mdx files:

   eslint . --ext js,mdx
   

Parser Options

1. parser (string | ParserConfig | ParserFn): Custom parser for ES syntax is supported, although @typescript-eslint/parser or babel-eslint will be detected automatically what means you actually do not need to do this:

   {
     "extends": ["plugin:mdx/recommended"],
     "parserOptions": {
       "parser": "babel-eslint"
     }
   }
   

2. extensions (string | string[]): eslint-mdx will only resolve .mdx files by default, files with other extensions will be resolved by the parser option. If you want to resolve other extensions as like .mdx, you can use this option.

3. 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.

Rules

mdx/no-jsx-html-comments

Fixable: HTML style comments in jsx block is invalid, this rule will help you to fix it by transforming it to JSX style comments.

mdx/no-unescaped-entities

Inline JSX like Inline <Component /> is supported by MDX, but rule react/no-unescaped-entities from eslint-plugin-react is incompatible with it, mdx/no-unescaped-entities is the replacement.

mdx/no-unused-expressions

MDX can render jsx block automatically without exporting them, but ESLint will report no-unused-expressions issue which could be unexpected, this rule is a replacement of it, so make sure that you've turned off the original no-unused-expressions rule.

mdx/remark

possible fixable depends on your remark plugins:

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

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

Changelog

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

License

MIT © [e-mail]