diff --git a/.eslintrc.js b/.eslintrc.js
index c4997b8..ca3260b 100644
--- a/.eslintrc.js
+++ b/.eslintrc.js
@@ -22,16 +22,27 @@ module.exports = {
PACKAGE_NAME
],
- "overrides": [
- {
- "files": ["*.md"],
- "processor": "markdown/markdown"
- }
- ],
-
"env": {
"node": true
},
- "extends": "eslint"
+ "extends": "eslint",
+
+ "overrides": [
+ {
+ "files": ["**/*.md"],
+ "processor": "markdown/markdown"
+ },
+ {
+ "files": ["**/*.md/*.js"],
+ "parserOptions": {
+ "ecmaFeatures": {
+ "impliedStrict": true
+ }
+ },
+ "rules": {
+ "lines-around-comment": "off"
+ }
+ }
+ ]
};
diff --git a/README.md b/README.md
index f29f8ce..dae1a54 100644
--- a/README.md
+++ b/README.md
@@ -3,43 +3,175 @@
[![npm Version](https://img.shields.io/npm/v/eslint-plugin-markdown.svg)](https://www.npmjs.com/package/eslint-plugin-markdown)
[![Build Status](https://img.shields.io/github/workflow/status/eslint/eslint-plugin-markdown/CI/master.svg)](https://github.com/eslint/eslint-plugin-markdown/actions)
-![Screenshot](screenshot.png)
+Lint JS, JSX, TypeScript, and more inside Markdown.
-An [ESLint](http://eslint.org/) plugin to lint JavaScript in Markdown.
+
+
+> 🚧 This documentation is for an unfinished v2 release in progress in the `master` branch. The latest stable documentation is in the [`v1` branch](https://github.com/eslint/eslint-plugin-markdown/tree/v1).
## Usage
-Install the plugin:
+### Installing
+
+Install the plugin alongside ESLint v6 or greater:
```sh
-npm install --save-dev eslint eslint-plugin-markdown
+npm install --save-dev eslint eslint-plugin-markdown@next
```
-Add it to your `.eslintrc` and enable the processor on Markdown files:
+### Configuring
-```json
-{
- "plugins": [
- "markdown"
- ],
- "overrides": [
+Add the plugin to your `.eslintrc` and use the `processor` option in an `overrides` entry to enable the plugin's `markdown/markdown` processor on Markdown files.
+Each fenced code block inside a Markdown document has a virtual filename appended to the Markdown file's path.
+The virtual filename's extension will match the fenced code block's syntax tag, so for example, ```js
code blocks in README.md
would match README.md/*.js
.
+For more information on configuring processors, refer to the [ESLint documentation](https://eslint.org/docs/user-guide/configuring#specifying-processor).
+
+```js
+// .eslintrc.js
+module.exports = {
+ // 1. Add the plugin.
+ plugins: ["markdown"],
+ overrides: [
{
- "files": ["*.md"],
- "processor": "markdown/markdown"
+ // 2. Enable the Markdown processor for all .md files.
+ files: ["**/*.md"],
+ processor: "markdown/markdown"
+ },
+ {
+ // 3. Optionally, customize the configuration ESLint uses for ```js
+ // fenced code blocks inside .md files.
+ files: ["**/*.md/*.js"],
+ // ...
+ rules: {
+ // ...
+ }
}
]
-}
+};
+```
+
+#### Migrating from `eslint-plugin-markdown` v1
+
+`eslint-plugin-markdown` v1 used an older version of ESLint's processor API.
+The Markdown processor automatically ran on `.md`, `.mkdn`, `.mdown`, and `.markdown` files, and it only extracted fenced code blocks marked with `js`, `javascript`, `jsx`, or `node` syntax.
+Configuration specifically for fenced code blocks went inside an `overrides` entry with a `files` pattern matching the containing Markdown document's filename that applied to all fenced code blocks inside the file.
+
+```js
+// .eslintrc.js for eslint-plugin-markdown v1
+module.exports = {
+ plugins: ["markdown"],
+ overrides: [
+ {
+ files: ["**/*.md"],
+ // In v1, configuration for fenced code blocks went inside an
+ // `overrides` entry with a .md pattern, for example:
+ parserOptions: {
+ ecmaFeatures: {
+ impliedStrict: true
+ }
+ },
+ rules: {
+ "no-console": "off"
+ }
+ }
+ ]
+};
+```
+
+[RFC3](https://github.com/eslint/rfcs/blob/master/designs/2018-processors-improvements/README.md) designed a new processor API to remove these limitations, and the new API was [implemented](https://github.com/eslint/eslint/pull/11552) as part of ESLint v6.
+`eslint-plugin-markdown` v2 uses this new API.
+
+```bash
+$ npm install --save-dev eslint@latest eslint-plugin-markdown@next
+```
+
+All of the Markdown file extensions that were previously hard-coded are now fully configurable in `.eslintrc.js`.
+Use the new `processor` option to apply the `markdown/markdown` processor on any Markdown documents matching a `files` pattern.
+Each fenced code block inside a Markdown document has a virtual filename appended to the Markdown file's path.
+The virtual filename's extension will match the fenced code block's syntax tag, so for example, ```js
code blocks in README.md
would match README.md/*.js
.
+
+```js
+// eslintrc.js for eslint-plugin-markdown v2
+module.exports = {
+ plugins: ["markdown"],
+ overrides: [
+ {
+ // In v2, explicitly apply eslint-plugin-markdown's `markdown`
+ // processor on any Markdown files you want to lint.
+ files: ["**/*.md"],
+ processor: "markdown/markdown"
+ },
+ {
+ // In v2, configuration for fenced code blocks is separate from the
+ // containing Markdown file. Each code block has a virtual filename
+ // appended to the Markdown file's path.
+ files: ["**/*.md/*.js"],
+ // Configuration for fenced code blocks goes with the override for
+ // the code block's virtual filename, for example:
+ parserOptions: {
+ ecmaFeatures: {
+ impliedStrict: true
+ }
+ },
+ rules: {
+ "no-console": "off"
+ }
+ }
+ ]
+};
```
-If you use ESLint v7, it [automatically lints file extensions from config files](https://github.com/eslint/rfcs/blob/0253e3a95511c65d622eaa387eb73f824249b467/designs/2019-additional-lint-targets/README.md), so you don't have to use the `--ext` option.
+If you need to precisely mimic the behavior of v1 with the hard-coded Markdown extensions and fenced code block syntaxes, you can use those as glob patterns in `overrides[].files`:
+
+```js
+// eslintrc.js for v2 mimicking v1 behavior
+module.exports = {
+ plugins: ["markdown"],
+ overrides: [
+ {
+ files: ["**/*.{md,mkdn,mdown,markdown}"],
+ processor: "markdown/markdown"
+ },
+ {
+ files: ["**/*.{md,mkdn,mdown,markdown}/*.{js,javascript,jsx,node}"]
+ // ...
+ }
+ ]
+};
+```
-If you use ESLint v6, use the `--ext` option to run ESLint on `.md` files:
+### Running
+
+#### ESLint v7
+
+You can run ESLint as usual and do not need to use the `--ext` option.
+ESLint v7 [automatically lints file extensions specified in `overrides[].files` patterns in config files](https://github.com/eslint/rfcs/blob/0253e3a95511c65d622eaa387eb73f824249b467/designs/2019-additional-lint-targets/README.md).
+
+#### ESLint v6
+
+Use the [`--ext` option](https://eslint.org/docs/user-guide/command-line-interface#ext) to include `.js` and `.md` extensions in ESLint's file search:
```sh
eslint --ext js,md .
```
-It will lint [fenced code blocks](https://help.github.com/articles/github-flavored-markdown/#fenced-code-blocks) in your Markdown documents:
+### Autofixing
+
+With this plugin, [ESLint's `--fix` option](https://eslint.org/docs/user-guide/command-line-interface#fixing-problems) can automatically fix some issues in your Markdown fenced code blocks.
+To enable this, pass the `--fix` flag when you run ESLint:
+
+```bash
+eslint --fix .
+```
+
+## What Gets Linted?
+
+With this plugin, ESLint will lint [fenced code blocks](https://help.github.com/articles/github-flavored-markdown/#fenced-code-blocks) in your Markdown documents:
````markdown
```js
@@ -62,7 +194,8 @@ hello();
```
```jsx
-// This gets linted too if you enable --ext jsx
+// This can be linted too if you add `.jsx` files to `overrides` in ESLint v7
+// or pass `--ext jsx` in ESLint v6.
var div =