feat!: Switch to flat config

.github/workflows/ci.yml

@@ -16,7 +16,7 @@ jobs:
     - name: Install Node.js
       uses: actions/setup-node@v3
       with:
-        node-version: 16
+        node-version: lts/*
     - name: Install Packages
       run: npm install
       env:
@@ -29,14 +29,14 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest]
-        eslint: [6, 7, 8]
-        node: [12.22.0, 14, 16, 17, 18, 19, 20, 21]
+        eslint: [8]
+        node: [16, 17, 18, 19, 20, 21]
         include:
           - os: windows-latest
-            eslint: 7
+            eslint: 8
             node: 16
           - os: macOS-latest
-            eslint: 7
+            eslint: 8
             node: 16
     runs-on: ${{ matrix.os }}
     steps:

README.md

@@ -17,31 +17,80 @@ Lint JS, JSX, TypeScript, and more inside Markdown.
 
 ### Installing
 
-Install the plugin alongside ESLint v6 or greater:
+Install the plugin alongside ESLint v8 or greater:
 
 ```sh
 npm install --save-dev eslint eslint-plugin-markdown
 ```
 
 ### Configuring
 
-Extending the `plugin:markdown/recommended` config will enable the Markdown processor on all `.md` files:
+In your `eslint.config.js` file, import `eslint-plugin-markdown` and include the recommended config to enable the Markdown processor on all `.md` files:
+
+```js
+// eslint.config.js
+import markdown from "eslint-plugin-markdown";
+
+export default [
+    ...markdown.configs.recommended
+
+    // your other configs here
+];
+```
+
+If you are still using the deprecated `.eslintrc.js` file format for ESLint, you can extend the `plugin:markdown/recommended-legacy` config to enable the Markdown processor on all `.md` files:
 
 ```js
 // .eslintrc.js
 module.exports = {
-    extends: "plugin:markdown/recommended"
+    extends: "plugin:markdown/recommended-legacy"
 };
 ```
 
 #### Advanced Configuration
 
-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.
+You can manually include the Markdown processor by setting the `processor` option in your configuration file for all `.md` 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, <code>```js</code> code blocks in <code>README.md</code> would match <code>README.md/*.js</code>.
-[`overrides` glob patterns](https://eslint.org/docs/user-guide/configuring#configuration-based-on-glob-patterns) for these virtual filenames can customize configuration for code blocks without affecting regular code.
+You can use glob patterns for these virtual filenames to customize configuration for code blocks without affecting regular code.
 For more information on configuring processors, refer to the [ESLint documentation](https://eslint.org/docs/user-guide/configuring#specifying-processor).
 
+Here's an example:
+
+```js
+// eslint.config.js
+import markdown from "eslint-plugin-markdown";
+
+export default [
+    {
+        // 1. Add the plugin
+        plugins: {
+            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: {
+            // ...
+        }
+    }
+
+    // your other configs here
+];
+```
+
+In the deprecated `.eslintrc.js` format:
+
 ```js
 // .eslintrc.js
 module.exports = {
@@ -77,13 +126,47 @@ The `plugin:markdown/recommended` config disables these rules in Markdown files:
 - [`no-unused-vars`](https://eslint.org/docs/rules/no-unused-vars)
 - [`padded-blocks`](https://eslint.org/docs/rules/padded-blocks)
 
-Use [`overrides` glob patterns](https://eslint.org/docs/user-guide/configuring#configuration-based-on-glob-patterns) to disable more rules just for Markdown code blocks:
+Use glob patterns to disable more rules just for Markdown code blocks:
 
 ```js
+// / eslint.config.js
+import markdown from "eslint-plugin-markdown";
+
+export default [
+    {
+        plugins: {
+            markdown
+        }
+    },
+    {
+        files: ["**/*.md"],
+        processor: "markdown/markdown"
+    },
+    {
+        // 1. Target ```js code blocks in .md files.
+        files: ["**/*.md/*.js"],
+        rules: {
+            // 2. Disable other rules.
+            "no-console": "off",
+            "import/no-unresolved": "off"
+        }
+    }
+
+    // your other configs here
+];
+```
+
+And in the deprecated `.eslintrc.js` format:
+
+```js
+// .eslintrc.js
 module.exports = {
-    // ...
+    plugins: ["markdown"],
     overrides: [
-        // ...
+        {
+            files: ["**/*.md"],
+            processor: "markdown/markdown"
+        },
         {
             // 1. Target ```js code blocks in .md files.
             files: ["**/*.md/*.js"],
@@ -111,97 +194,13 @@ The `plugin:markdown/recommended` config disables these rules in Markdown files:
 - [`eol-last`](https://eslint.org/docs/rules/eol-last): The Markdown parser trims trailing newlines from code blocks.
 - [`unicode-bom`](https://eslint.org/docs/rules/unicode-bom): Markdown code blocks do not have Unicode Byte Order Marks.
 
-#### 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@latest
-```
-
-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, <code>```js</code> code blocks in <code>README.md</code> would match <code>README.md/*.js</code>.
-
-```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"
-            }
-        }
-    ]
-};
-```
+### Running
 
-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`:
+#### ESLint v8+
 
-```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 are using an `eslint.config.js` file, then you can run ESLint as usual and it will pick up file patterns in your config file. The `--ext` option is not available when using flat config.
 
-### Running
+If you are using an `.eslintrc.*` file, then you can run ESLint as usual and it will work as in ESLint v7.x.
 
 #### ESLint v7
 
@@ -279,10 +278,10 @@ The processor will convert HTML comments immediately preceding a code block into
 This permits configuring ESLint via configuration comments while keeping the configuration comments themselves hidden when the markdown is rendered.
 Comment bodies are passed through unmodified, so the plugin supports any [configuration comments](http://eslint.org/docs/user-guide/configuring) supported by ESLint itself.
 
-This example enables the `browser` environment, disables the `no-alert` rule, and configures the `quotes` rule to prefer single quotes:
+This example enables the `alert` global variable, disables the `no-alert` rule, and configures the `quotes` rule to prefer single quotes:
 
 ````markdown
-<!-- eslint-env browser -->
+<!-- global alert -->
 <!-- eslint-disable no-alert -->
 <!-- eslint quotes: ["error", "single"] -->
 
@@ -294,9 +293,9 @@ alert('Hello, world!');
 Each code block in a file is linted separately, so configuration comments apply only to the code block that immediately follows.
 
 ````markdown
-Assuming `no-alert` is enabled in `.eslintrc`, the first code block will have no error from `no-alert`:
+Assuming `no-alert` is enabled in `eslint.config.js`, the first code block will have no error from `no-alert`:
 
-<!-- eslint-env browser -->
+<!-- global alert -->
 <!-- eslint-disable no-alert -->
 
 ```js
@@ -305,7 +304,7 @@ alert("Hello, world!");
 
 But the next code block will have an error from `no-alert`:
 
-<!-- eslint-env browser -->
+<!-- global alert -->
 
 ```js
 alert("Hello, world!");