Repository files navigation

ESLint Parser/Plugin forMDX, helps you lint all ES syntaxes.Lintingcode blocks can be enabled withmdx/code-blocks setting too!Work perfectly witheslint-plugin-import,eslint-plugin-prettier or any other eslint plugins.And also can be integrated withremark-lint plugins to lint markdown syntaxes.

• VSCode Extension
• Packages
• Install
• Notice
• Usage
  • Classic Config
  • Flat Config
• Parser Options
• Parser API
  • MDXCode
  • MDXHeading
  • Typings
• Rules
  • mdx/remark
• Prettier Integration
• Sponsors and Backers
  • Sponsors
  • Backers
• Changelog
• License

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

This repository is a monorepo managed bychangesets 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

# yarnyarn add -D eslint-plugin-mdx# npmnpm i -D eslint-plugin-mdx

1. If you're using multi languages,js/jsx/ts/tsx/vue, etc for example, you'd better to always useoverrides (Classic Config) orfiles (Flag Config) feature of ESLint, because configs may be overridden by following configs.

   See#251 for more details.

2. If you're using{/* eslint-disable-line mdx/remark */} withprettier, this won't work becauseprettier 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*/}

.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",  },}

eslint.config.js file:

import*asmdxfrom'eslint-plugin-mdx'exportdefault[{    ...mdx.flat,// optional, if you want to lint code blocks at the sameprocessor: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 ownlanguageMapper:{},// optional, same as the `parserOptions.ignoreRemarkConfig`, you have to specify it twice unfortunatelyignoreRemarkConfig:true,// optional, same as the `parserOptions.remarkConfigPath`, you have to specify it twice unfortunatelyremarkConfigPath:'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

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

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

3. ignoreRemarkConfig (boolean): Ignore theremark configuration defined in the project.

4. remarkConfigPath (string): Specify the path to theremark configuration file, could be relative toCWD or absolute path.

A newMDXCode estree node type is exported fromeslint-mdx which represents code blocks inmdx like the following:

<div>```jsexportfunctionfoo() {return'bar'  }```</div>

See alsohttps://github.com/syntax-tree/mdast#code

A newMDXHeading estree node type is exported fromeslint-mdx which represents markdown heading inmdx like the following:

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

See alsohttps://github.com/syntax-tree/mdast#heading

importtype{BaseNode}from'estree'importtype{JSXElement}from'estree-jsx'exportinterfaceMDXCodeextendsBaseNode{type:'MDXCode'value:stringlang?:string|nullmeta?:string|null}exporttypeHeadingDepth=1|2|3|4|5|6exportinterfaceMDXHeadingextendsBaseNode{type:'MDXHeading'depth:HeadingDepthchildren:JSXElement['children']}

possible fixable depends on your remark plugins:

Integration withremark-lint plugins, it will readremark's configuration automatically viaunified-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    ],  ],}

If you're usingremark-lint feature withPrettier both together, you can tryremark-preset-prettier which helps you toturn off all rules that are unnecessary or might conflict withPrettier.

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

1stG	RxTS	UnRS	UnTS

1stG	RxTS	UnRS	UnTS

Detailed changes for each release are documented inCHANGELOG.md.

MIT ©JounQin@1stG.me