chore: enable eslint-plugin-mdx for linting Markdown files (#241)

JounQin · web-flow · commit fb7209b080d7 · 2025-03-15T01:24:23.000+08:00
diff --git a/.eslintignore b/.eslintignore
@@ -9,3 +9,4 @@ test/fixtures/typescript-d-ts/
 # we want to ignore "test/fixtures" here, but unfortunately doing so would
 # interfere with unit test and fail it for some reason.
 # test/fixtures
+CHANGELOG.md
diff --git a/.eslintrc.js b/.eslintrc.js
@@ -10,6 +10,7 @@ module.exports = {
     'plugin:eslint-plugin/recommended',
     'plugin:import-x/recommended',
     'plugin:json/recommended-legacy',
+    'plugin:mdx/recommended',
     'plugin:n/recommended',
     'plugin:unicorn/recommended',
     'plugin:yml/standard',
@@ -45,6 +46,13 @@ module.exports = {
     'n/no-missing-import': 'off',
     'n/no-missing-require': 'off',
     'n/no-unsupported-features/es-syntax': 'off',
+    'unicorn/filename-case': [
+      'error',
+      {
+        case: 'kebabCase',
+        ignore: [String.raw`^(CONTRIBUTING|README)\.md$`],
+      },
+    ],
     'unicorn/no-array-callback-reference': 'off',
     'unicorn/no-array-reduce': 'off',
     'unicorn/no-null': 'off',
@@ -118,7 +126,14 @@ module.exports = {
     {
       files: 'global.d.ts',
       rules: {
-        'import-x/no-extraneous-dependencies': 0,
+        'import-x/no-extraneous-dependencies': 'off',
+      },
+    },
+    {
+      files: 'README.md',
+      rules: {
+        // https://github.com/bmish/eslint-doc-generator/issues/655
+        'no-irregular-whitespace': 'off',
       },
     },
   ],
diff --git a/.remarkrc b/.remarkrc
@@ -0,0 +1,19 @@
+{
+  "plugins": [
+    "@1stg/preset",
+    [
+      "lint-no-shortcut-reference-link",
+      false
+    ],
+    [
+      "lint-no-undefined-references",
+      {
+        "allow": [
+          "!NOTE",
+          "!TIP",
+          "!WARNING"
+        ]
+      }
+    ]
+  ]
+}
diff --git a/README.md b/README.md
@@ -160,9 +160,6 @@ settings:
     node: true
 ```
 
-[`@typescript-eslint/parser`]: https://github.com/typescript-eslint/typescript-eslint/tree/HEAD/packages/parser
-[`eslint-import-resolver-typescript`]: https://github.com/import-js/eslint-import-resolver-typescript
-
 ## Configuration (new: `eslint.config.js`)
 
 From [`v8.21.0`](https://github.com/eslint/eslint/releases/tag/v8.21.0), ESLint announced a new config system.
@@ -337,11 +334,6 @@ the process's current working directory if no `package.json` is found.
 
 If you are interesting in writing a resolver, see the [spec](./resolvers/README.md) for more details.
 
-[`resolve`]: https://www.npmjs.com/package/resolve
-[`externals`]: https://webpack.github.io/docs/library-and-externals.html
-[Node]: https://www.npmjs.com/package/eslint-import-resolver-node
-[webpack]: https://www.npmjs.com/package/eslint-import-resolver-webpack
-
 ## Settings
 
 You may set the following settings in your `.eslintrc`:
@@ -505,14 +497,11 @@ settings:
     lifetime: 5 # 30 is the default
 ```
 
-[`eslint_d`]: https://www.npmjs.com/package/eslint_d
-[`eslint-loader`]: https://www.npmjs.com/package/eslint-loader
-
 ### `import-x/internal-regex`
 
 A regex for packages should be treated as internal. Useful when you are utilizing a monorepo setup or developing a set of packages that depend on each other.
 
-By default, any package referenced from [`import-x/external-module-folders`](#importexternal-module-folders) will be considered as "external", including packages in a monorepo like yarn workspace or lerna environment. If you want to mark these packages as "internal" this will be useful.
+By default, any package referenced from [`import-x/external-module-folders`](#import-xexternal-module-folders) will be considered as "external", including packages in a monorepo like yarn workspace or lerna environment. If you want to mark these packages as "internal" this will be useful.
 
 For example, if your packages in a monorepo are all in `@scope`, you can configure `import-x/internal-regex` like this
 
@@ -593,3 +582,12 @@ In Package Settings / SublimeLinter / User Settings:
 
 I believe this defaults to `3`, so you may not need to alter it depending on your
 project folder max depth.
+
+[`@typescript-eslint/parser`]: https://github.com/typescript-eslint/typescript-eslint/tree/HEAD/packages/parser
+[`eslint-import-resolver-typescript`]: https://github.com/import-js/eslint-import-resolver-typescript
+[`resolve`]: https://www.npmjs.com/package/resolve
+[`externals`]: https://webpack.github.io/docs/library-and-externals.html
+[Node]: https://www.npmjs.com/package/eslint-import-resolver-node
+[webpack]: https://www.npmjs.com/package/eslint-import-resolver-webpack
+[`eslint_d`]: https://www.npmjs.com/package/eslint_d
+[`eslint-loader`]: https://www.npmjs.com/package/eslint-loader
diff --git a/docs/rules/consistent-type-specifier-style.md b/docs/rules/consistent-type-specifier-style.md
@@ -31,8 +31,6 @@ This rule either enforces or bans the use of inline type-only markers for named
 
 This rule includes a fixer that will automatically convert your specifiers to the correct form - however the fixer will not respect your preferences around de-duplicating imports. If this is important to you, consider using the [`import-x/no-duplicates`] rule.
 
-[`import-x/no-duplicates`]: ./no-duplicates.md
-
 ## Options
 
 The rule accepts a single string option which may be one of:
@@ -89,3 +87,5 @@ import {typeof Foo} from 'Foo';
 If you aren't using Flow or TypeScript 4.5+, then this rule does not apply and need not be used.
 
 If you don't care about, and don't want to standardize how named specifiers are imported then you should not use this rule.
+
+[`import-x/no-duplicates`]: ./no-duplicates.md
diff --git a/docs/rules/default.md b/docs/rules/default.md
@@ -16,9 +16,6 @@ Redux's npm module includes this key, and thereby is lintable, for example.
 
 A module path that is [ignored] or not [unambiguously an ES module] will not be reported when imported.
 
-[ignored]: ../README.md#importignore
-[unambiguously an ES module]: https://github.com/bmeck/UnambiguousJavaScriptGrammar
-
 ## Rule Details
 
 Given:
@@ -78,3 +75,5 @@ either, so such a situation will be reported in the importing module.
 [ES7]: https://github.com/leebyron/ecmascript-more-export-from
 [`import-x/ignore`]: ../../README.md#importignore
 [`jsnext:main`]: https://github.com/rollup/rollup/wiki/jsnext:main
+[ignored]: ../../README.md#importignore
+[unambiguously an ES module]: https://github.com/bmeck/UnambiguousJavaScriptGrammar
diff --git a/docs/rules/dynamic-import-chunkname.md b/docs/rules/dynamic-import-chunkname.md
@@ -103,7 +103,7 @@ If you want to allow dynamic imports without a webpackChunkName, you can set `al
 
 Given `{ "allowEmpty": true }`:
 
-<!-- markdownlint-disable-next-line MD024 -- duplicate header -->
+<!-- lint disable no-duplicate-headings-in-section -->
 
 ### valid
 
@@ -118,7 +118,7 @@ import(
 )
 ```
 
-<!-- markdownlint-disable-next-line MD024 -- duplicate header -->
+<!-- lint disable no-duplicate-headings-in-section -->
 
 ### invalid
 
diff --git a/docs/rules/extensions.md b/docs/rules/extensions.md
@@ -22,7 +22,7 @@ By providing an object you can configure each extension separately.
 }]
 ```
 
-For example `{ "js": "always", "json": "never" }` would always enforce the use of the `.js` extension but never allow the use of the `.json` extension.
+For example `{ "js": "always", "json": "never" }` would always enforce the use of the `.js` extension but never allow the use of the `.json` extension.
 
 By providing both a string and an object, the string will set the default setting for all extensions, and the object can be used to set granular overrides for specific extensions.
 
@@ -66,8 +66,8 @@ For example, given the following folder structure:
 
 ```pt
 ├── foo
-│   ├── bar.js
-│   ├── bar.json
+│   ├── bar.js
+│   ├── bar.json
 ```
 
 and this import statement:
diff --git a/docs/rules/max-dependencies.md b/docs/rules/max-dependencies.md
@@ -47,7 +47,7 @@ Ignores `type` imports. Type imports are a feature released in TypeScript 3.8, y
 
 Given `{"max": 2, "ignoreTypeImports": true}`:
 
-<!-- markdownlint-disable-next-line MD024 -- duplicate header -->
+<!-- lint disable no-duplicate-headings-in-section -->
 
 ### Fail
 
@@ -57,7 +57,7 @@ import b from './b'
 import c from './c'
 ```
 
-<!-- markdownlint-disable-next-line MD024 -- duplicate header -->
+<!-- lint disable no-duplicate-headings-in-section -->
 
 ### Pass
 
diff --git a/docs/rules/named.md b/docs/rules/named.md
@@ -14,10 +14,6 @@ Redux's npm module includes this key, and thereby is lintable, for example.
 
 A module path that is [ignored] or not [unambiguously an ES module] will not be reported when imported. Note that type imports and exports, as used by [Flow], are always ignored.
 
-[ignored]: ../../README.md#importignore
-[unambiguously an ES module]: https://github.com/bmeck/UnambiguousJavaScriptGrammar
-[Flow]: https://flow.org/
-
 ## Rule Details
 
 Given:
@@ -100,3 +96,6 @@ runtime, you will likely see false positives with this rule.
 [`jsnext:main`]: https://github.com/jsforum/jsforum/issues/5
 [`pkg.module`]: https://github.com/rollup/rollup/wiki/pkg.module
 [`import-x/ignore`]: ../../README.md#importignore
+[ignored]: ../../README.md#importignore
+[unambiguously an ES module]: https://github.com/bmeck/UnambiguousJavaScriptGrammar
+[Flow]: https://flow.org/
diff --git a/docs/rules/namespace.md b/docs/rules/namespace.md
@@ -18,9 +18,6 @@ Redux's npm module includes this key, and thereby is lintable, for example.
 
 A module path that is [ignored] or not [unambiguously an ES module] will not be reported when imported.
 
-[ignored]: ../README.md#importignore
-[unambiguously an ES module]: https://github.com/bmeck/UnambiguousJavaScriptGrammar
-
 ## Rule Details
 
 Currently, this rule does not check for possible
@@ -98,8 +95,10 @@ still can't be statically analyzed any further.
 
 - Lee Byron's [ES7] export proposal
 - [`import-x/ignore`] setting
-- [`jsnext:main`](Rollup)
+- [`jsnext:main`]
 
 [ES7]: https://github.com/leebyron/ecmascript-more-export-from
 [`import-x/ignore`]: ../../README.md#importignore
 [`jsnext:main`]: https://github.com/rollup/rollup/wiki/jsnext:main
+[ignored]: ../../README.md#importignore
+[unambiguously an ES module]: https://github.com/bmeck/UnambiguousJavaScriptGrammar
diff --git a/docs/rules/no-default-export.md b/docs/rules/no-default-export.md
@@ -4,8 +4,6 @@
 
 Prohibit default exports. Mostly an inverse of [`prefer-default-export`].
 
-[`prefer-default-export`]: ./prefer-default-export.md
-
 ## Rule Details
 
 The following patterns are considered warnings:
@@ -63,3 +61,5 @@ export * from './other-module'
 ## When Not To Use It
 
 If you don't care if default imports are used, or if you prefer default imports over named imports.
+
+[`prefer-default-export`]: ./prefer-default-export.md
diff --git a/docs/rules/no-mutable-exports.md b/docs/rules/no-mutable-exports.md
@@ -46,9 +46,9 @@ want to enable the following core ESLint rules:
 - [no-func-assign]
 - [no-class-assign]
 
-[no-func-assign]: https://eslint.org/docs/rules/no-func-assign
-[no-class-assign]: https://eslint.org/docs/rules/no-class-assign
-
 ## When Not To Use It
 
 If your environment correctly implements mutable export bindings.
+
+[no-func-assign]: https://eslint.org/docs/rules/no-func-assign
+[no-class-assign]: https://eslint.org/docs/rules/no-class-assign
diff --git a/docs/rules/no-named-as-default-member.md b/docs/rules/no-named-as-default-member.md
@@ -17,8 +17,6 @@ Furthermore, [in Babel 5 this is actually how things worked][blog]. This was
 fixed in Babel 6. Before upgrading an existing codebase to Babel 6, it can be
 useful to run this lint rule.
 
-[blog]: https://kentcdodds.com/blog/misunderstanding-es6-modules-upgrading-babel-tears-and-a-solution
-
 ## Rule Details
 
 Given:
@@ -50,3 +48,5 @@ const bar = foo.bar
 import foo from './foo.js'
 const { bar } = foo
 ```
+
+[blog]: https://kentcdodds.com/blog/misunderstanding-es6-modules-upgrading-babel-tears-and-a-solution
diff --git a/docs/rules/no-named-default.md b/docs/rules/no-named-default.md
@@ -8,8 +8,6 @@ Rationale: the syntax exists to import default exports expressively, let's use i
 
 Note that type imports, as used by [Flow], are always ignored.
 
-[Flow]: https://flow.org/
-
 ## Rule Details
 
 Given:
@@ -34,3 +32,5 @@ import foo, { bar } from './foo.js'
 import { default as foo } from './foo.js'
 import { default as foo, bar } from './foo.js'
 ```
+
+[Flow]: https://flow.org/
diff --git a/docs/rules/no-named-export.md b/docs/rules/no-named-export.md
@@ -4,8 +4,6 @@
 
 Prohibit named exports. Mostly an inverse of [`no-default-export`].
 
-[`no-default-export`]: ./no-default-export.md
-
 ## Rule Details
 
 The following patterns are considered warnings:
@@ -77,3 +75,5 @@ export default from './other-module'
 ## When Not To Use It
 
 If you don't care if named imports are used, or if you prefer named imports over default imports.
+
+[`no-default-export`]: ./no-default-export.md
diff --git a/docs/rules/order.md b/docs/rules/order.md
@@ -102,7 +102,7 @@ This rule supports the following options:
 
 ### `groups: [array]`
 
-How groups are defined, and the order to respect. `groups` must be an array of `string` or [`string`]. The only allowed `string`s are:
+How groups are defined, and the order to respect. `groups` must be an array of `string` or `string[]`. The only allowed `string`s are:
 `"builtin"`, `"external"`, `"internal"`, `"unknown"`, `"parent"`, `"sibling"`, `"index"`, `"object"`, `"type"`.
 The enforced order is the same as the order of each element in a group. Omitted types are implicitly grouped together as the last element. Example:
 
@@ -224,6 +224,8 @@ Example:
 
 [Import Type](https://github.com/un-ts/eslint-plugin-import-x/blob/ea7c13eb9b18357432e484b25dfa4451eca69c5b/src/utils/import-type.ts#L145) is resolved as a fixed string in predefined set, it can't be a `patterns` (e.g., `react`, `react-router-dom`, etc).
 
+<!-- lint disable maximum-heading-length -->
+
 ### `newlines-between: [ignore|always|always-and-inside-groups|never]`
 
 Enforces or forbids new lines between import groups:
@@ -295,6 +297,8 @@ import index from './'
 import sibling from './foo'
 ```
 
+<!-- lint disable maximum-heading-length -->
+
 ### `alphabetize: {order: asc|desc|ignore, orderImportKind: asc|desc|ignore, caseInsensitive: true|false}`
 
 Sort the order within each group in alphabetical manner based on **import path**:
diff --git a/package.json b/package.json
@@ -64,6 +64,7 @@
     "@1stg/commitlint-config": "^5.0.0",
     "@1stg/lint-staged": "^4.0.4",
     "@1stg/prettier-config": "^4.0.4",
+    "@1stg/remark-preset": "^3.0.0",
     "@1stg/simple-git-hooks": "^0.2.4",
     "@1stg/tsconfig": "^3.0.0",
     "@angular-eslint/template-parser": "^19.2.1",
@@ -109,6 +110,7 @@
     "eslint-plugin-import-x": "link:.",
     "eslint-plugin-jest": "^28.11.0",
     "eslint-plugin-json": "^4.0.1",
+    "eslint-plugin-mdx": "^3.2.0",
     "eslint-plugin-n": "^17.16.2",
     "eslint-plugin-prettier": "^5.2.3",
     "eslint-plugin-unicorn": "^56.0.1",
diff --git a/resolvers/README.md b/resolvers/README.md
diff --git a/yarn.lock b/yarn.lock
