Wondering what’s next for npm?Check out our public roadmap! »

    eslint-plugin-mdx
    TypeScript icon, indicating that this package has built-in type declarations

    1.12.0 • Public • Published

    Travis Codacy Grade Codecov type-coverage GitHub release David Dev

    Conventional Commits code style: prettier lerna codechecks.io

    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.

    TOC

    VSCode Extension

    Visual Studio Marketplace Version

    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 npm David Peer David
    eslint-plugin-mdx ESLint Plugin, Configuration and Rules for MDX npm David Peer David

    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 feature of ESLint, because configs may be overridden by following configs.

    See #251 for more details.

    Usage

    1. In your ESLint config file:

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

        {
          "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": {}
          }
        }
      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"],
          // 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": {}
          },
          "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"]
            },
            {
              "files": "**/*.{md,mdx}/**",
              "extends": "plugin:mdx/code-blocks"
            }
          ]
        }
      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/lib/configs')
        
        module.exports = {
          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': {},
          },
          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'],
              ...configs.overrides,
            },
            {
              files: '**/*.{md,mdx}/**',
              ...configs.codeBlocks,
            },
          ],
        }
    2. Make sure ESLint knows to run on .md or .mdx files:

      eslint . --ext js,md,mdx

    Parser Options

    1. parser (string | ParserConfig | ParserFn): Custom parser for ES syntax is supported, although @typescript-eslint/parser or @babel/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-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 the replacement, 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.

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

    Changelog

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

    License

    MIT © JounQin@1stG.me

    Install

    npm i eslint-plugin-mdx

    DownloadsWeekly Downloads

    68,301

    Version

    1.12.0

    License

    MIT

    Unpacked Size

    208 kB

    Total Files

    68

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar
    • avatar