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 | [![Travis](https://img.shields.io/travis/com/mdx-js/eslint-mdx.svg)](https://travis-ci.com/mdx-js/eslint-mdx)
|
14 | [![Codacy Grade](https://img.shields.io/codacy/grade/4ea8225261c04837995a858676caae4b)](https://www.codacy.com/app/JounQin/eslint-mdx)
|
15 | [![Codecov](https://img.shields.io/codecov/c/gh/mdx-js/eslint-mdx)](https://codecov.io/gh/mdx-js/eslint-mdx)
|
16 | [![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)
|
17 | [![GitHub release](https://img.shields.io/github/release/mdx-js/eslint-mdx)](https://github.com/mdx-js/eslint-mdx/releases)
|
18 | [![David Dev](https://img.shields.io/david/dev/mdx-js/eslint-mdx.svg)](https://david-dm.org/mdx-js/eslint-mdx?type=dev)
|
19 |
|
20 | [![Conventional Commits](https://img.shields.io/badge/conventional%20commits-1.0.0-yellow.svg)](https://conventionalcommits.org)
|
21 | [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)
|
22 | [![lerna](https://img.shields.io/badge/maintained%20with-lerna-cc00ff.svg)](https://lerna.js.org)
|
23 | [![codechecks.io](https://raw.githubusercontent.com/codechecks/docs/master/images/badges/badge-default.svg?sanitize=true)](https://codechecks.io)
|
24 |
|
25 | > [ESLint][] Parser/Plugin for [MDX][], helps you lint all ES syntaxes excluding `code` block of course.
|
26 | > Work perfectly with `eslint-plugin-import`, `eslint-plugin-prettier` or any other eslint plugins.
|
27 | > And also can be integrated with [remark-lint][] plugins to lint markdown syntaxes.
|
28 |
|
29 | ## TOC <!-- omit in toc -->
|
30 |
|
31 | - [VSCode Extension](#vscode-extension)
|
32 | - [Packages](#packages)
|
33 | - [Install](#install)
|
34 | - [Usage](#usage)
|
35 | - [Parser Options](#parser-options)
|
36 | - [Rules](#rules)
|
37 | - [mdx/no-jsx-html-comments](#mdxno-jsx-html-comments)
|
38 | - [mdx/no-unescaped-entities](#mdxno-unescaped-entities)
|
39 | - [mdx/no-unused-expressions](#mdxno-unused-expressions)
|
40 | - [mdx/remark](#mdxremark)
|
41 | - [Prettier Integration](#prettier-integration)
|
42 | - [Changelog](#changelog)
|
43 | - [License](#license)
|
44 |
|
45 | ## VSCode Extension
|
46 |
|
47 | [![Visual Studio Marketplace Version](https://img.shields.io/visual-studio-marketplace/v/JounQin.vscode-mdx)](https://marketplace.visualstudio.com/items?itemName=JounQin.vscode-mdx)
|
48 |
|
49 | [VSCode MDX][]\: Integrates with [VSCode ESLint][], syntaxes highlighting and error reporting.
|
50 |
|
51 | ## Packages
|
52 |
|
53 | This repository is a monorepo managed by [Lerna][] what means we actually publish several packages to npm from same codebase, including:
|
54 |
|
55 | | Package | Description | Version | Peer Dependencies | Dependencies |
|
56 | | -------------------------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
57 | | [`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) |
|
58 | | [`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) |
|
59 |
|
60 | ## Install
|
61 |
|
62 | ```sh
|
63 | # yarn
|
64 | yarn add -D eslint-plugin-mdx
|
65 |
|
66 | # npm
|
67 | npm i -D eslint-plugin-mdx
|
68 | ```
|
69 |
|
70 | ## Usage
|
71 |
|
72 | 1. In your ESLint config file:
|
73 |
|
74 | 1. If you're using `eslint >= 6.4.0`, just add:
|
75 |
|
76 | ```json
|
77 | {
|
78 | "extends": ["plugin:mdx/recommended"]
|
79 | }
|
80 | ```
|
81 |
|
82 | 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:
|
83 |
|
84 | ```jsonc
|
85 | {
|
86 | "extends": ["plugin:mdx/recommended"],
|
87 | "overrides": [
|
88 | {
|
89 | "files": ["*.md"],
|
90 | "rules": {
|
91 | "prettier/prettier": [
|
92 | 2,
|
93 | {
|
94 | // unnecessary if you're not using `eslint-plugin-prettier`, but required if you are
|
95 | "parser": "markdown"
|
96 | }
|
97 | ]
|
98 | }
|
99 | },
|
100 | {
|
101 | "files": ["*.mdx"],
|
102 | "extends": ["plugin:mdx/overrides"]
|
103 | }
|
104 | ]
|
105 | }
|
106 | ```
|
107 |
|
108 | 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:
|
109 |
|
110 | ```js
|
111 | const { configs } = require('eslint-plugin-mdx')
|
112 |
|
113 | module.exports = {
|
114 | extends: ['plugin:mdx/recommended'],
|
115 | overrides: [
|
116 | {
|
117 | files: ['*.md'],
|
118 | rules: {
|
119 | 'prettier/prettier': [
|
120 | 2,
|
121 | {
|
122 | // unnecessary if you're not using `eslint-plugin-prettier`, but required if you are
|
123 | parser: 'markdown',
|
124 | },
|
125 | ],
|
126 | },
|
127 | },
|
128 | Object.assign(
|
129 | {
|
130 | files: ['*.mdx'],
|
131 | },
|
132 | configs.overrides,
|
133 | ),
|
134 | ],
|
135 | }
|
136 | ```
|
137 |
|
138 | 2. Make sure ESLint knows to run on `.mdx` files:
|
139 |
|
140 | ```sh
|
141 | eslint . --ext js,mdx
|
142 | ```
|
143 |
|
144 | ## Parser Options
|
145 |
|
146 | 1. `parser` (`string | ParserConfig | ParserFn`): Custom parser for ES syntax is supported, although `@typescript-eslint/parser` or `babel-eslint` will be detected automatically what means you actually do not need to do this:
|
147 |
|
148 | ```json
|
149 | {
|
150 | "extends": ["plugin:mdx/recommended"],
|
151 | "parserOptions": {
|
152 | "parser": "babel-eslint"
|
153 | }
|
154 | }
|
155 | ```
|
156 |
|
157 | 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.
|
158 |
|
159 | 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.
|
160 |
|
161 | ## Rules
|
162 |
|
163 | ### mdx/no-jsx-html-comments
|
164 |
|
165 | _Fixable_: HTML style comments in jsx block is invalid, this rule will help you to fix it by transforming it to JSX style comments.
|
166 |
|
167 | ### mdx/no-unescaped-entities
|
168 |
|
169 | 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.
|
170 |
|
171 | ### mdx/no-unused-expressions
|
172 |
|
173 | [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.
|
174 |
|
175 | ### mdx/remark
|
176 |
|
177 | _possible fixable depends on your remark plugins_:
|
178 |
|
179 | 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.
|
180 |
|
181 | ## Prettier Integration
|
182 |
|
183 | 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][]_.
|
184 |
|
185 | ```json
|
186 | {
|
187 | "plugins": [
|
188 | "preset-lint-consistent",
|
189 | "preset-lint-recommended",
|
190 | "preset-lint-markdown-style-guide",
|
191 | "preset-prettier"
|
192 | ]
|
193 | }
|
194 | ```
|
195 |
|
196 | ## Changelog
|
197 |
|
198 | Detailed changes for each release are documented in [CHANGELOG.md](./CHANGELOG.md).
|
199 |
|
200 | ## License
|
201 |
|
202 | [MIT][] © [JounQin][]@[1stG.me][]
|
203 |
|
204 | [1stg.me]: https://www.1stg.me
|
205 | [cosmiconfig]: https://github.com/davidtheclark/cosmiconfig
|
206 | [eslint]: https://eslint.org
|
207 | [eslint-plugin-react]: https://github.com/yannickcr/eslint-plugin-react
|
208 | [jounqin]: https://GitHub.com/JounQin
|
209 | [lerna]: https://github.com/lerna/lerna
|
210 | [mdx]: https://github.com/mdx-js/mdx
|
211 | [mit]: http://opensource.org/licenses/MIT
|
212 | [prettier]: https://prettier.io
|
213 | [remark-lint]: https://github.com/remarkjs/remark-lint
|
214 | [remark-preset-prettier]: https://github.com/JounQin/remark-preset-prettier
|
215 | [vscode eslint]: https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint
|
216 | [vscode mdx]: https://github.com/mdx-js/vscode-mdx
|