docs: cleanup docs, add markdownlint, tweak eslint-doc-generator options (#64)

Author: bmish

.markdownlint.json

@@ -0,0 +1,9 @@
+{
+    "line-length": false,
+    "no-inline-html": {
+        "allowed_elements": ["details"]
+    },
+    "ul-style": {
+        "style": "dash"
+    }
+}

.markdownlintignore

@@ -0,0 +1,3 @@
+CHANGELOG.md
+LICENSE
+node_modules

README.md

@@ -57,43 +57,41 @@ npm install --save-dev eslint eslint-plugin-n
 
 <!-- begin auto-generated rules list -->
 
-💼 Configurations enabled in.\
-✅ Set in the `recommended` configuration.\
-☑️ Set in the `recommended-module` configuration.\
-✔️ Set in the `recommended-script` configuration.\
+💼 [Configurations](https://github.com/eslint-community/eslint-plugin-n#-configs) enabled in.\
+✅ Set in the `recommended` [configuration](https://github.com/eslint-community/eslint-plugin-n#-configs).\
 🔧 Automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/user-guide/command-line-interface#--fix).\
 ❌ Deprecated.
 
 ### Best Practices
 
-| Name                                                 | Description              | 💼      | 🔧 | ❌  |
-| :--------------------------------------------------- | :----------------------- | :------ | :- | :- |
-| [no-deprecated-api](docs/rules/no-deprecated-api.md) | disallow deprecated APIs | ✅ ☑️ ✔️ |    |    |
+| Name                                                 | Description              | 💼 | 🔧 | ❌  |
+| :--------------------------------------------------- | :----------------------- | :- | :- | :- |
+| [no-deprecated-api](docs/rules/no-deprecated-api.md) | disallow deprecated APIs | ✅  |    |    |
 
 ### Possible Errors
 
-| Name                                                                                         | Description                                                                 | 💼      | 🔧 | ❌  |
-| :------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------- | :------ | :- | :- |
-| [handle-callback-err](docs/rules/handle-callback-err.md)                                     | require error handling in callbacks                                         |         |    |    |
-| [no-callback-literal](docs/rules/no-callback-literal.md)                                     | enforce Node.js-style error-first callback pattern is followed              |         |    |    |
-| [no-exports-assign](docs/rules/no-exports-assign.md)                                         | disallow the assignment to `exports`                                        | ✅ ☑️ ✔️ |    |    |
-| [no-extraneous-import](docs/rules/no-extraneous-import.md)                                   | disallow `import` declarations which import extraneous modules              | ✅ ☑️ ✔️ |    |    |
-| [no-extraneous-require](docs/rules/no-extraneous-require.md)                                 | disallow `require()` expressions which import extraneous modules            | ✅ ☑️ ✔️ |    |    |
-| [no-hide-core-modules](docs/rules/no-hide-core-modules.md)                                   | disallow third-party modules which are hiding core modules                  |         |    | ❌  |
-| [no-missing-import](docs/rules/no-missing-import.md)                                         | disallow `import` declarations which import non-existence modules           | ✅ ☑️ ✔️ |    |    |
-| [no-missing-require](docs/rules/no-missing-require.md)                                       | disallow `require()` expressions which import non-existence modules         | ✅ ☑️ ✔️ |    |    |
-| [no-new-require](docs/rules/no-new-require.md)                                               | disallow `new` operators with calls to `require`                            |         |    |    |
-| [no-path-concat](docs/rules/no-path-concat.md)                                               | disallow string concatenation with `__dirname` and `__filename`             |         |    |    |
-| [no-process-exit](docs/rules/no-process-exit.md)                                             | disallow the use of `process.exit()`                                        | ✅ ☑️ ✔️ |    |    |
-| [no-unpublished-bin](docs/rules/no-unpublished-bin.md)                                       | disallow `bin` files that npm ignores                                       | ✅ ☑️ ✔️ |    |    |
-| [no-unpublished-import](docs/rules/no-unpublished-import.md)                                 | disallow `import` declarations which import private modules                 | ✅ ☑️ ✔️ |    |    |
-| [no-unpublished-require](docs/rules/no-unpublished-require.md)                               | disallow `require()` expressions which import private modules               | ✅ ☑️ ✔️ |    |    |
-| [no-unsupported-features](docs/rules/no-unsupported-features.md)                             | disallow unsupported ECMAScript features on the specified version           |         |    | ❌  |
-| [no-unsupported-features/es-builtins](docs/rules/no-unsupported-features/es-builtins.md)     | disallow unsupported ECMAScript built-ins on the specified version          | ✅ ☑️ ✔️ |    |    |
-| [no-unsupported-features/es-syntax](docs/rules/no-unsupported-features/es-syntax.md)         | disallow unsupported ECMAScript syntax on the specified version             | ✅ ☑️ ✔️ |    |    |
-| [no-unsupported-features/node-builtins](docs/rules/no-unsupported-features/node-builtins.md) | disallow unsupported Node.js built-in APIs on the specified version         | ✅ ☑️ ✔️ |    |    |
-| [process-exit-as-throw](docs/rules/process-exit-as-throw.md)                                 | require that `process.exit()` expressions use the same code path as `throw` | ✅ ☑️ ✔️ |    |    |
-| [shebang](docs/rules/shebang.md)                                                             | require correct usage of shebang                                            | ✅ ☑️ ✔️ | 🔧 |    |
+| Name                                                                                         | Description                                                                 | 💼 | 🔧 | ❌  |
+| :------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------- | :- | :- | :- |
+| [handle-callback-err](docs/rules/handle-callback-err.md)                                     | require error handling in callbacks                                         |    |    |    |
+| [no-callback-literal](docs/rules/no-callback-literal.md)                                     | enforce Node.js-style error-first callback pattern is followed              |    |    |    |
+| [no-exports-assign](docs/rules/no-exports-assign.md)                                         | disallow the assignment to `exports`                                        | ✅  |    |    |
+| [no-extraneous-import](docs/rules/no-extraneous-import.md)                                   | disallow `import` declarations which import extraneous modules              | ✅  |    |    |
+| [no-extraneous-require](docs/rules/no-extraneous-require.md)                                 | disallow `require()` expressions which import extraneous modules            | ✅  |    |    |
+| [no-hide-core-modules](docs/rules/no-hide-core-modules.md)                                   | disallow third-party modules which are hiding core modules                  |    |    | ❌  |
+| [no-missing-import](docs/rules/no-missing-import.md)                                         | disallow `import` declarations which import non-existence modules           | ✅  |    |    |
+| [no-missing-require](docs/rules/no-missing-require.md)                                       | disallow `require()` expressions which import non-existence modules         | ✅  |    |    |
+| [no-new-require](docs/rules/no-new-require.md)                                               | disallow `new` operators with calls to `require`                            |    |    |    |
+| [no-path-concat](docs/rules/no-path-concat.md)                                               | disallow string concatenation with `__dirname` and `__filename`             |    |    |    |
+| [no-process-exit](docs/rules/no-process-exit.md)                                             | disallow the use of `process.exit()`                                        | ✅  |    |    |
+| [no-unpublished-bin](docs/rules/no-unpublished-bin.md)                                       | disallow `bin` files that npm ignores                                       | ✅  |    |    |
+| [no-unpublished-import](docs/rules/no-unpublished-import.md)                                 | disallow `import` declarations which import private modules                 | ✅  |    |    |
+| [no-unpublished-require](docs/rules/no-unpublished-require.md)                               | disallow `require()` expressions which import private modules               | ✅  |    |    |
+| [no-unsupported-features](docs/rules/no-unsupported-features.md)                             | disallow unsupported ECMAScript features on the specified version           |    |    | ❌  |
+| [no-unsupported-features/es-builtins](docs/rules/no-unsupported-features/es-builtins.md)     | disallow unsupported ECMAScript built-ins on the specified version          | ✅  |    |    |
+| [no-unsupported-features/es-syntax](docs/rules/no-unsupported-features/es-syntax.md)         | disallow unsupported ECMAScript syntax on the specified version             | ✅  |    |    |
+| [no-unsupported-features/node-builtins](docs/rules/no-unsupported-features/node-builtins.md) | disallow unsupported Node.js built-in APIs on the specified version         | ✅  |    |    |
+| [process-exit-as-throw](docs/rules/process-exit-as-throw.md)                                 | require that `process.exit()` expressions use the same code path as `throw` | ✅  |    |    |
+| [shebang](docs/rules/shebang.md)                                                             | require correct usage of shebang                                            | ✅  | 🔧 |    |
 
 ### Stylistic Issues
 
@@ -124,11 +122,13 @@ npm install --save-dev eslint eslint-plugin-n
 
 This plugin provides three configs:
 
-- `plugin:n/recommended` considers both CommonJS and ES Modules. If [`"type":"module"` field](https://medium.com/@nodejs/announcing-a-new-experimental-modules-1be8d2d6c2ff#b023) existed in package.json then it considers files as ES Modules. Otherwise it considers files as CommonJS. In addition, it considers `*.mjs` files as ES Modules and `*.cjs` files as CommonJS.
-- `plugin:n/recommended-module` considers all files as ES Modules.
-- `plugin:n/recommended-script` considers all files as CommonJS.
+| Name | Description |
+| :-- | :-- |
+| `plugin:n/recommended` | Considers both CommonJS and ES Modules. If [`"type":"module"` field](https://medium.com/@nodejs/announcing-a-new-experimental-modules-1be8d2d6c2ff#b023) existed in package.json then it considers files as ES Modules. Otherwise it considers files as CommonJS. In addition, it considers `*.mjs` files as ES Modules and `*.cjs` files as CommonJS. |
+| `plugin:n/recommended-module` | Considers all files as ES Modules. |
+| `plugin:n/recommended-script` | Considers all files as CommonJS. |
 
-Those preset config:
+These preset configs:
 
 - enable [no-process-exit](http://eslint.org/docs/rules/no-process-exit) rule because [the official document](https://nodejs.org/api/process.html#process_process_exit_code) does not recommend a use of `process.exit()`.
 - enable plugin rules which are given ✅ in the above table.

docs/rules/callback-return.md

@@ -102,8 +102,8 @@ function bar(err, send) {
 
 Because it is difficult to understand the meaning of a program through static analysis, this rule has limitations:
 
-* *false negatives* when this rule reports correct code, but the program calls the callback more than one time (which is incorrect behavior)
-* *false positives* when this rule reports incorrect code, but the program calls the callback only one time (which is correct behavior)
+- *false negatives* when this rule reports correct code, but the program calls the callback more than one time (which is incorrect behavior)
+- *false positives* when this rule reports incorrect code, but the program calls the callback only one time (which is correct behavior)
 
 #### Passing the callback by reference
 

docs/rules/exports-style.md

@@ -21,7 +21,7 @@ In this case, `exports.bar` will be lost since only the instance of `module.expo
 
 This rule enforces the export style.
 
-If you use `module.exports`, this rule disallows `exports`.<br>
+If you use `module.exports`, this rule disallows `exports`.\
 If you use `exports`, this rule disallows `module.exports`.
 
 You can select it by an option.
@@ -48,7 +48,7 @@ This rule has a string option.
 
 #### module.exports
 
-Examples of :-1: **incorrect** code for the `"module.exports"` option:
+Examples of 👎 **incorrect** code for the `"module.exports"` option:
 
 ```js
 /*eslint n/exports-style: ["error", "module.exports"]*/
@@ -57,7 +57,7 @@ exports.foo = 1
 exports.bar = 2
 ```
 
-Examples of :+1: **correct** code for the `"module.exports"` option:
+Examples of 👍 **correct** code for the `"module.exports"` option:
 
 ```js
 /*eslint n/exports-style: ["error", "module.exports"]*/
@@ -72,7 +72,7 @@ module.exports.baz = 3
 
 #### exports
 
-Examples of :-1: **incorrect** code for the `"exports"` option:
+Examples of 👎 **incorrect** code for the `"exports"` option:
 
 ```js
 /*eslint n/exports-style: ["error", "exports"]*/
@@ -85,7 +85,7 @@ module.exports = {
 module.exports.baz = 3
 ```
 
-Examples of :+1: **correct** code for the `"exports"` option:
+Examples of 👍 **correct** code for the `"exports"` option:
 
 ```js
 /*eslint n/exports-style: ["error", "exports"]*/
@@ -96,7 +96,7 @@ exports.bar = 2
 
 #### allowBatchAssign
 
-Examples of :+1: **correct** code for the `"exports"` and `{"allowBatchAssign": true}` option:
+Examples of 👍 **correct** code for the `"exports"` and `{"allowBatchAssign": true}` option:
 
 ```js
 /*eslint n/exports-style: ["error", "exports", {"allowBatchAssign": true}]*/

docs/rules/file-extension-in-import.md

@@ -41,15 +41,15 @@ This rule has a string option and an object option.
 
 #### always
 
-Examples of :-1: **incorrect** code for the `"always"` option:
+Examples of 👎 **incorrect** code for the `"always"` option:
 
 ```js
 /*eslint n/file-extension-in-import: ["error", "always"]*/
 
 import foo from "./path/to/a/file"
 ```
 
-Examples of :+1: **correct** code for the `"always"` option:
+Examples of 👍 **correct** code for the `"always"` option:
 
 ```js
 /*eslint n/file-extension-in-import: ["error", "always"]*/
@@ -60,15 +60,15 @@ import foo from "./path/to/a/file.js"
 
 #### never
 
-Examples of :-1: **incorrect** code for the `"never"` option:
+Examples of 👎 **incorrect** code for the `"never"` option:
 
 ```js
 /*eslint n/file-extension-in-import: ["error", "never"]*/
 
 import foo from "./path/to/a/file.js"
 ```
 
-Examples of :+1: **correct** code for the `"never"` option:
+Examples of 👍 **correct** code for the `"never"` option:
 
 ```js
 /*eslint n/file-extension-in-import: ["error", "never"]*/
@@ -79,7 +79,7 @@ import foo from "./path/to/a/file"
 
 #### .xxx
 
-Examples of :+1: **correct** code for the `["always", { ".js": "never" }]` option:
+Examples of 👍 **correct** code for the `["always", { ".js": "never" }]` option:
 
 ```js
 /*eslint n/file-extension-in-import: ["error", "always", { ".js": "never" }]*/

docs/rules/handle-callback-err.md

@@ -68,9 +68,9 @@ so you need a more flexible configuration to ensure that the rule reports all un
 
 If the configured name of the error variable begins with a `^` it is considered to be a regexp pattern.
 
-* If the option is `"^(err|error|anySpecificError)$"`, the rule reports unhandled errors where the parameter name can be `err`, `error` or `anySpecificError`.
-* If the option is `"^.+Error$"`, the rule reports unhandled errors where the parameter name ends with `Error` (for example, `connectionError` or `validationError` will match).
-* If the option is `"^.*(e|E)rr"`, the rule reports unhandled errors where the parameter name matches any string that contains `err` or `Err` (for example, `err`, `error`, `anyError`, `some_err` will match).
+- If the option is `"^(err|error|anySpecificError)$"`, the rule reports unhandled errors where the parameter name can be `err`, `error` or `anySpecificError`.
+- If the option is `"^.+Error$"`, the rule reports unhandled errors where the parameter name ends with `Error` (for example, `connectionError` or `validationError` will match).
+- If the option is `"^.*(e|E)rr"`, the rule reports unhandled errors where the parameter name matches any string that contains `err` or `Err` (for example, `err`, `error`, `anyError`, `some_err` will match).
 
 ## 🔎 Implementation
 

docs/rules/no-callback-literal.md

@@ -8,7 +8,7 @@ When invoking a callback function which uses the Node.js error-first callback pa
 
 When a function is named `cb` or `callback`, then it must be invoked with a first argument that is `undefined`, `null`, an `Error` class, or a subclass or `Error`.
 
-Examples of :-1: **incorrect** code for this rule:
+Examples of 👎 **incorrect** code for this rule:
 
 ```js
 /*eslint n/no-callback-literal: "error" */
@@ -18,7 +18,7 @@ cb({ a: 1 });
 callback(0);
 ```
 
-Examples of :+1: **correct** code for this rule:
+Examples of 👍 **correct** code for this rule:
 
 ```js
 /*eslint n/no-callback-literal: "error" */

docs/rules/no-deprecated-api.md

@@ -1,6 +1,6 @@
 # Disallow deprecated APIs (`n/no-deprecated-api`)
 
-💼 This rule is enabled in the following configs: ✅ `recommended`, ☑️ `recommended-module`, ✔️ `recommended-script`.
+💼 This rule is enabled in the ✅ `recommended` [config](https://github.com/eslint-community/eslint-plugin-n#-configs).
 
 <!-- end auto-generated rule header -->
 
@@ -9,7 +9,7 @@ The community is going to remove those API from Node in future, so we should not
 
 ## 📖 Rule Details
 
-Examples of :-1: **incorrect** code for this rule:
+Examples of 👎 **incorrect** code for this rule:
 
 ```js
 /*eslint n/no-deprecated-api: "error" */
@@ -272,7 +272,7 @@ This option can include the following values:
 - `util._extend`
 - `vm.runInDebugContext`
 
-Examples of :+1: **correct** code for the `{"ignoreModuleItems": ["new buffer.Buffer()"]}`:
+Examples of 👍 **correct** code for the `{"ignoreModuleItems": ["new buffer.Buffer()"]}`:
 
 ```js
 /*eslint n/no-deprecated-api: [error, {ignoreModuleItems: ["new buffer.Buffer()"]}] */
@@ -304,7 +304,7 @@ This option can include the following values:
 - `process.binding`
 - `process.env.NODE_REPL_HISTORY_FILE`
 
-Examples of :+1: **correct** code for the `{"ignoreGlobalItems": ["new Buffer()"]}`:
+Examples of 👍 **correct** code for the `{"ignoreGlobalItems": ["new Buffer()"]}`:
 
 ```js
 /*eslint n/no-deprecated-api: [error, {ignoreGlobalItems: ["new Buffer()"]}] */

docs/rules/no-exports-assign.md

@@ -1,6 +1,6 @@
 # Disallow the assignment to `exports` (`n/no-exports-assign`)
 
-💼 This rule is enabled in the following configs: ✅ `recommended`, ☑️ `recommended-module`, ✔️ `recommended-script`.
+💼 This rule is enabled in the ✅ `recommended` [config](https://github.com/eslint-community/eslint-plugin-n#-configs).
 
 <!-- end auto-generated rule header -->