What is eslint-mdx?
The eslint-mdx package is an ESLint plugin that provides linting support for MDX (Markdown with JSX) files. It helps ensure code quality and consistency in MDX files by leveraging ESLint's capabilities.
What are eslint-mdx's main functionalities?
Linting MDX Files
This configuration allows ESLint to lint MDX files by extending the recommended settings provided by the eslint-mdx plugin.
module.exports = {
"overrides": [
{
"files": ["*.mdx"],
"extends": ["plugin:mdx/recommended"]
}
]
};
Custom MDX Rules
This configuration demonstrates how to add custom rules for MDX files. In this example, the rule 'mdx/no-jsx-html-comments' is set to 'error' to disallow HTML comments within JSX.
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 Prettier with eslint-mdx to ensure consistent formatting in MDX files. The 'prettier/prettier' rule is configured to use the 'mdx' parser.
module.exports = {
"overrides": [
{
"files": ["*.mdx"],
"extends": ["plugin:mdx/recommended", "prettier"],
"rules": {
"prettier/prettier": ["error", { "parser": "mdx" }]
}
}
]
};
Other packages similar to eslint-mdx
eslint-plugin-markdown
eslint-plugin-markdown is an ESLint plugin that allows linting of JavaScript code blocks within Markdown files. Unlike eslint-mdx, which is specifically designed for MDX files, eslint-plugin-markdown focuses on JavaScript code within standard Markdown files.
remark-lint
remark-lint is a plugin for remark, a Markdown processor, that provides linting capabilities for Markdown files. While eslint-mdx leverages ESLint for linting MDX files, remark-lint is part of the remark ecosystem and focuses on Markdown linting with its own set of rules and plugins.
eslint-plugin-react
eslint-plugin-react is an ESLint plugin that provides linting rules for React applications. Although it is not specifically designed for MDX files, it can be used in conjunction with eslint-mdx to ensure React code within MDX files adheres to best practices.
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
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 add -D eslint-plugin-mdx
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
-
In your ESLint config file:
-
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": {}
}
}
-
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"
}
]
}
-
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'],
settings: {
'mdx/code-blocks': true,
'mdx/language-mapper': {},
},
overrides: [
{
files: ['*.md'],
rules: {
'prettier/prettier': [
2,
{
parser: 'markdown',
},
],
},
},
{
files: ['*.mdx'],
...configs.overrides,
},
{
files: '**/*.{md,mdx}/**',
...configs.codeBlocks,
},
],
}
-
Make sure ESLint knows to run on .md
or .mdx
files:
eslint . --ext js,md,mdx
Parser Options
-
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"
}
}
-
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.
-
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
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.
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