ESLint Parser/Plugin for MDX, helps you lint all ES syntaxes excluding
code
block of course. Work perfectly witheslint-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
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
-
In your ESLint config file:
-
If you're using
eslint >= 6.4.0
, just add:{ "extends": ["plugin:mdx/recommended"] }
-
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"] } ] }
-
If you're using
eslint@^5.0.0
, you need to enable this parser/plugin manually, becauseeslint@5
does not supportextends
foroverrides
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, ), ], }
-
-
Make sure ESLint knows to run on
.mdx
files:eslint . --ext js,mdx
Parser Options
-
parser
(string | ParserConfig | ParserFn
): Custom parser for ES syntax is supported, although@typescript-eslint/parser
orbabel-eslint
will be detected automatically what means you actually do not need to do this:{ "extends": ["plugin:mdx/recommended"], "parserOptions": { "parser": "babel-eslint" } }
-
extensions
(string | string[]
):eslint-mdx
will only resolve.mdx
files by default, files with other extensions will be resolved by theparser
option. 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.
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.