1 | <p align="center">
|
2 | <a href="https://eslint.org">
|
3 | <img src="https://eslint.org/assets/img/logo.svg" height="50">
|
4 | </a>
|
5 | <a href="#readme">
|
6 | <img src="https://rx-ts.github.io/assets/heart.svg" height="50">
|
7 | </a>
|
8 | <a href="https://github.com/mdx-js/mdx">
|
9 | <img src="https://mdx-logo.now.sh" height="50">
|
10 | </a>
|
11 | </p>
|
12 |
|
13 | [![GitHub Actions](https://github.com/mdx-js/eslint-mdx/workflows/CI/badge.svg)](https://github.com/mdx-js/eslint-mdx/actions/workflows/ci.yml)
|
14 | [![Codecov](https://img.shields.io/codecov/c/gh/mdx-js/eslint-mdx)](https://codecov.io/gh/mdx-js/eslint-mdx)
|
15 | [![type-coverage](https://img.shields.io/badge/dynamic/json.svg?label=type-coverage&prefix=%E2%89%A5&suffix=%&query=$.typeCoverage.atLeast&uri=https%3A%2F%2Fraw.githubusercontent.com%2Fmdx-js%2Feslint-mdx%2Fmaster%2Fpackage.json)](https://github.com/plantain-00/type-coverage)
|
16 | [![GitHub release](https://img.shields.io/github/release/mdx-js/eslint-mdx)](https://github.com/mdx-js/eslint-mdx/releases)
|
17 | [![David Dev](https://img.shields.io/david/dev/mdx-js/eslint-mdx.svg)](https://david-dm.org/mdx-js/eslint-mdx?type=dev)
|
18 |
|
19 | [![Conventional Commits](https://img.shields.io/badge/conventional%20commits-1.0.0-yellow.svg)](https://conventionalcommits.org)
|
20 | [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)
|
21 | [![lerna](https://img.shields.io/badge/maintained%20with-lerna-cc00ff.svg)](https://lerna.js.org)
|
22 |
|
23 | > [ESLint][] Parser/Plugin for [MDX][], helps you lint all ES syntaxes.
|
24 | > Linting `code` blocks can be enabled with `mdx/code-blocks` setting too!
|
25 | > Work perfectly with `eslint-plugin-import`, `eslint-plugin-prettier` or any other eslint plugins.
|
26 | > And also can be integrated with [remark-lint][] plugins to lint markdown syntaxes.
|
27 |
|
28 | ## TOC <!-- omit in toc -->
|
29 |
|
30 | - [VSCode Extension](#vscode-extension)
|
31 | - [Packages](#packages)
|
32 | - [Install](#install)
|
33 | - [Notice](#notice)
|
34 | - [Usage](#usage)
|
35 | - [Parser Options](#parser-options)
|
36 | - [Rules](#rules)
|
37 | - [mdx/no-jsx-html-comments](#mdxno-jsx-html-comments)
|
38 | - [mdx/no-unused-expressions](#mdxno-unused-expressions)
|
39 | - [mdx/remark](#mdxremark)
|
40 | - [Prettier Integration](#prettier-integration)
|
41 | - [Changelog](#changelog)
|
42 | - [License](#license)
|
43 |
|
44 | ## VSCode Extension
|
45 |
|
46 | [![Visual Studio Marketplace Version](https://img.shields.io/visual-studio-marketplace/v/JounQin.vscode-mdx)](https://marketplace.visualstudio.com/items?itemName=JounQin.vscode-mdx)
|
47 |
|
48 | [VSCode MDX][]\: Integrates with [VSCode ESLint][], syntaxes highlighting and error reporting.
|
49 |
|
50 | ## Packages
|
51 |
|
52 | This repository is a monorepo managed by [Lerna][] what means we actually publish several packages to npm from same codebase, including:
|
53 |
|
54 | | Package | Description | Version | Peer Dependencies | Dependencies |
|
55 | | -------------------------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
56 | | [`eslint-mdx`](/packages/eslint-mdx) | ESLint Parser for MDX | [![npm](https://img.shields.io/npm/v/eslint-mdx.svg)](https://www.npmjs.com/package/eslint-mdx) | [![David Peer](https://img.shields.io/david/peer/mdx-js/eslint-mdx.svg?path=packages/eslint-mdx)](https://david-dm.org/mdx-js/eslint-mdx?path=packages/eslint-mdx&type=peer) | [![David](https://img.shields.io/david/mdx-js/eslint-mdx.svg?path=packages/eslint-mdx)](https://david-dm.org/mdx-js/eslint-mdx?path=packages/eslint-mdx) |
|
57 | | [`eslint-plugin-mdx`](/packages/eslint-plugin-mdx) | ESLint Plugin, Configuration and Rules for MDX | [![npm](https://img.shields.io/npm/v/eslint-plugin-mdx.svg)](https://www.npmjs.com/package/eslint-plugin-mdx) | [![David Peer](https://img.shields.io/david/peer/mdx-js/eslint-mdx.svg?path=packages/eslint-plugin-mdx)](https://david-dm.org/mdx-js/eslint-mdx?path=packages/eslint-plugin-mdx&type=peer) | [![David](https://img.shields.io/david/mdx-js/eslint-mdx.svg?path=packages/eslint-plugin-mdx)](https://david-dm.org/mdx-js/eslint-mdx?path=packages/eslint-plugin-mdx) |
|
58 |
|
59 | ## Install
|
60 |
|
61 | ```sh
|
62 | # yarn
|
63 | yarn add -D eslint-plugin-mdx
|
64 |
|
65 | # npm
|
66 | npm i -D eslint-plugin-mdx
|
67 | ```
|
68 |
|
69 | ## Notice
|
70 |
|
71 | If you're using multi languages, `js/jsx/ts/tsx/vue`, etc for example, you'd better to always use [`overrides`](https://eslint.org/docs/user-guide/configuring/configuration-files#how-do-overrides-work) feature of ESLint, because configs may be overridden by following configs.
|
72 |
|
73 | See [#251](https://github.com/mdx-js/eslint-mdx/issues/251#issuecomment-736139224) for more details.
|
74 |
|
75 | ## Usage
|
76 |
|
77 | 1. In your ESLint config file:
|
78 |
|
79 | 1. If you're using `eslint >= 6.4.0`, just add:
|
80 |
|
81 | ```jsonc
|
82 | {
|
83 | "extends": ["plugin:mdx/recommended"],
|
84 | // optional, if you want to lint code blocks at the same time
|
85 | "settings": {
|
86 | "mdx/code-blocks": true,
|
87 | // optional, if you want to disable language mapper, set it to `false`
|
88 | // if you want to override the default language mapper inside, you can provide your own
|
89 | "mdx/language-mapper": {}
|
90 | }
|
91 | }
|
92 | ```
|
93 |
|
94 | 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:
|
95 |
|
96 | ```jsonc
|
97 | {
|
98 | "extends": ["plugin:mdx/recommended"],
|
99 | // optional, if you want to lint code blocks at the same time
|
100 | "settings": {
|
101 | "mdx/code-blocks": true,
|
102 | // optional, if you want to disable language mapper, set it to `false`
|
103 | // if you want to override the default language mapper inside, you can provide your own
|
104 | "mdx/language-mapper": {}
|
105 | },
|
106 | "overrides": [
|
107 | {
|
108 | "files": ["*.md"],
|
109 | "rules": {
|
110 | "prettier/prettier": [
|
111 | 2,
|
112 | {
|
113 | // unnecessary if you're not using `eslint-plugin-prettier`, but required if you are
|
114 | "parser": "markdown"
|
115 | }
|
116 | ]
|
117 | }
|
118 | },
|
119 | {
|
120 | "files": ["*.mdx"],
|
121 | "extends": ["plugin:mdx/overrides"]
|
122 | },
|
123 | {
|
124 | "files": "**/*.{md,mdx}/**",
|
125 | "extends": "plugin:mdx/code-blocks"
|
126 | }
|
127 | ]
|
128 | }
|
129 | ```
|
130 |
|
131 | 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:
|
132 |
|
133 | ```js
|
134 | const configs = require('eslint-plugin-mdx/lib/configs')
|
135 |
|
136 | module.exports = {
|
137 | extends: ['plugin:mdx/recommended'],
|
138 | // optional, if you want to lint code blocks at the same time
|
139 | settings: {
|
140 | 'mdx/code-blocks': true,
|
141 | // optional, if you want to disable language mapper, set it to `false`
|
142 | // if you want to override the default language mapper inside, you can provide your own
|
143 | 'mdx/language-mapper': {},
|
144 | },
|
145 | overrides: [
|
146 | {
|
147 | files: ['*.md'],
|
148 | rules: {
|
149 | 'prettier/prettier': [
|
150 | 2,
|
151 | {
|
152 | // unnecessary if you're not using `eslint-plugin-prettier`, but required if you are
|
153 | parser: 'markdown',
|
154 | },
|
155 | ],
|
156 | },
|
157 | },
|
158 | {
|
159 | files: ['*.mdx'],
|
160 | ...configs.overrides,
|
161 | },
|
162 | {
|
163 | files: '**/*.{md,mdx}/**',
|
164 | ...configs.codeBlocks,
|
165 | },
|
166 | ],
|
167 | }
|
168 | ```
|
169 |
|
170 | 2. Make sure ESLint knows to run on `.md` or `.mdx` files:
|
171 |
|
172 | ```sh
|
173 | eslint . --ext js,md,mdx
|
174 | ```
|
175 |
|
176 | ## Parser Options
|
177 |
|
178 | 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:
|
179 |
|
180 | ```json
|
181 | {
|
182 | "extends": ["plugin:mdx/recommended"],
|
183 | "parserOptions": {
|
184 | "parser": "babel-eslint"
|
185 | }
|
186 | }
|
187 | ```
|
188 |
|
189 | 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.
|
190 |
|
191 | 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.
|
192 |
|
193 | ## Rules
|
194 |
|
195 | ### mdx/no-jsx-html-comments
|
196 |
|
197 | _Fixable_: HTML style comments in jsx block is invalid, this rule will help you to fix it by transforming it to JSX style comments.
|
198 |
|
199 | ### mdx/no-unused-expressions
|
200 |
|
201 | [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.
|
202 |
|
203 | ### mdx/remark
|
204 |
|
205 | _possible fixable depends on your remark plugins_:
|
206 |
|
207 | Integration with [remark-lint][] plugins, it will read [remark's configuration](https://github.com/remarkjs/remark/tree/master/packages/remark-cli#remark-cli) automatically via [cosmiconfig][]. But `.remarkignore` will not be respected, you should use `.eslintignore` instead.
|
208 |
|
209 | 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:
|
210 |
|
211 | ```jsonc
|
212 | {
|
213 | "plugins": [
|
214 | "@1stg/remark-config",
|
215 | // change to error severity, notice `[]` is required
|
216 | ["lint-no-duplicate-headings", [2]],
|
217 | // disable following plugin
|
218 | [
|
219 | "lint-no-multiple-toplevel-headings",
|
220 | [0] // or false
|
221 | ]
|
222 | ]
|
223 | }
|
224 | ```
|
225 |
|
226 | ## Prettier Integration
|
227 |
|
228 | 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][]_.
|
229 |
|
230 | ```json
|
231 | {
|
232 | "plugins": [
|
233 | "preset-lint-consistent",
|
234 | "preset-lint-recommended",
|
235 | "preset-lint-markdown-style-guide",
|
236 | "preset-prettier"
|
237 | ]
|
238 | }
|
239 | ```
|
240 |
|
241 | ## Changelog
|
242 |
|
243 | Detailed changes for each release are documented in [CHANGELOG.md](./CHANGELOG.md).
|
244 |
|
245 | ## License
|
246 |
|
247 | [MIT][] © [JounQin][]@[1stG.me][]
|
248 |
|
249 | [1stg.me]: https://www.1stg.me
|
250 | [cosmiconfig]: https://github.com/davidtheclark/cosmiconfig
|
251 | [eslint]: https://eslint.org
|
252 | [jounqin]: https://GitHub.com/JounQin
|
253 | [lerna]: https://github.com/lerna/lerna
|
254 | [mdx]: https://github.com/mdx-js/mdx
|
255 | [mit]: http://opensource.org/licenses/MIT
|
256 | [prettier]: https://prettier.io
|
257 | [remark-lint]: https://github.com/remarkjs/remark-lint
|
258 | [remark-preset-prettier]: https://github.com/JounQin/remark-preset-prettier
|
259 | [vscode eslint]: https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint
|
260 | [vscode mdx]: https://github.com/mdx-js/vscode-mdx
|