docs: consistency changes (#15404)

* docs: consistency changes

* chore: review comments

* chore: update marked

* chore: more review comments

.github/ISSUE_TEMPLATE/NEW_SYNTAX.md

@@ -20,7 +20,7 @@ assignees: ''
 
 **Please provide the TC39 URL for the syntax proposal:**
 
-
+<!-- for example, <https://github.com/tc39/proposal-top-level-await> -->
 
 **Please provide some example code for the new syntax:**
 
@@ -41,3 +41,5 @@ Please check off all items that have already been completed. Be sure to paste th
 - [ ] `eslint` update: <!-- paste PR URL for this syntax here -->
 
 **Are you willing to submit a pull request to implement this syntax?**
+
+<!-- markdownlint-disable-file MD004 -->

.github/PULL_REQUEST_TEMPLATE.md

@@ -42,5 +42,6 @@
 
 #### What changes did you make? (Give an overview)
 
-
 #### Is there anything you'd like reviewers to focus on?
+
+<!-- markdownlint-disable-file MD004 -->

.markdownlint.yml

@@ -2,6 +2,8 @@ default: true
 
 # Exclusions for deliberate/widespread violations
 MD002: false     # First header should be a h1 header
+MD004:           # Unordered list style
+    style: asterisk
 MD007:           # Unordered list indentation
     indent: 4
 MD013: false     # Line length

Makefile.js

@@ -15,6 +15,7 @@ const checker = require("npm-license"),
     dateformat = require("dateformat"),
     fs = require("fs"),
     glob = require("glob"),
+    marked = require("marked"),
     markdownlint = require("markdownlint"),
     os = require("os"),
     path = require("path"),
@@ -790,7 +791,9 @@ target.checkRuleFiles = function() {
         const basename = path.basename(filename, ".js");
         const docFilename = `docs/rules/${basename}.md`;
         const docText = cat(docFilename);
+        const docMarkdown = marked.lexer(docText, { gfm: true, silent: false });
         const ruleCode = cat(filename);
+        const knownHeaders = ["Rule Details", "Options", "Environments", "Examples", "Known Limitations", "When Not To Use It", "Related Rules", "Compatibility", "Further Reading"];
 
         /**
          * Check if basename is present in rule-types.json file.
@@ -820,7 +823,35 @@ target.checkRuleFiles = function() {
         }
 
         /**
-         * Check if deprecated information is in rule code and READNE.md.
+         * Check if all H2 headers are known and in the expected order
+         * Only H2 headers are checked as H1 and H3 are variable and/or rule specific.
+         * @returns {boolean} true if all headers are known and in the right order
+         */
+        function hasKnownHeaders() {
+            const headers = docMarkdown.filter(token => token.type === "heading" && token.depth === 2).map(header => header.text);
+
+            for (const header of headers) {
+                if (!knownHeaders.includes(header)) {
+                    return false;
+                }
+            }
+
+            /*
+             * Check only the subset of used headers for the correct order
+             */
+            const presentHeaders = knownHeaders.filter(header => headers.includes(header));
+
+            for (let i = 0; i < presentHeaders.length; ++i) {
+                if (presentHeaders[i] !== headers[i]) {
+                    return false;
+                }
+            }
+
+            return true;
+        }
+
+        /**
+         * Check if deprecated information is in rule code and README.md.
          * @returns {boolean} true if present
          * @private
          */
@@ -853,6 +884,12 @@ target.checkRuleFiles = function() {
                 console.error("Missing id in the doc page's title of rule %s", basename);
                 errors++;
             }
+
+            // check for proper doc headers
+            if (!hasKnownHeaders()) {
+                console.error("Unknown or misplaced header in the doc page of rule %s, allowed headers (and their order) are: '%s'", basename, knownHeaders.join("', '"));
+                errors++;
+            }
         }
 
         // check for recommended configuration

docs/developer-guide/working-with-custom-formatters.md

@@ -100,23 +100,23 @@ also be manually applied to that page. -->
 
 Each object in the `results` array is a `result` object. Each `result` object contains the path of the file that was linted and information about linting issues that were encountered. Here are the properties available on each `result` object:
 
-*   **filePath**: The absolute path to the file that was linted.
-*   **messages**: An array of `message` objects. See below for more info about messages.
-*   **errorCount**: The number of errors for the given file.
-*   **warningCount**: The number of warnings for the given file.
-*   **source**: The source code for the given file. This property is omitted if this file has no errors/warnings or if the `output` property is present.
-*   **output**: The source code for the given file with as many fixes applied as possible. This property is omitted if no fix is available.
+* **filePath**: The absolute path to the file that was linted.
+* **messages**: An array of `message` objects. See below for more info about messages.
+* **errorCount**: The number of errors for the given file.
+* **warningCount**: The number of warnings for the given file.
+* **source**: The source code for the given file. This property is omitted if this file has no errors/warnings or if the `output` property is present.
+* **output**: The source code for the given file with as many fixes applied as possible. This property is omitted if no fix is available.
 
 ### The `message` Object
 
 Each `message` object contains information about the ESLint rule that was triggered by some source code. The properties available on each `message` object are:
 
-*   **ruleId**: the ID of the rule that produced the error or warning.
-*   **severity**: the severity of the failure, `1` for warnings and `2` for errors.
-*   **message**: the human readable description of the error.
-*   **line**: the line where the issue is located.
-*   **column**: the column where the issue is located.
-*   **nodeType**: the type of the node in the [AST](https://github.com/estree/estree/blob/master/spec.md#node-objects)
+* **ruleId**: the ID of the rule that produced the error or warning.
+* **severity**: the severity of the failure, `1` for warnings and `2` for errors.
+* **message**: the human readable description of the error.
+* **line**: the line where the issue is located.
+* **column**: the column where the issue is located.
+* **nodeType**: the type of the node in the [AST](https://github.com/estree/estree/blob/master/spec.md#node-objects)
 
 ## The `context` Argument
 

docs/rules/accessor-pairs.md

@@ -281,6 +281,11 @@ See [no-dupe-class-members](no-dupe-class-members.md) if you also want to disall
 
 You can turn this rule off if you are not concerned with the simultaneous presence of setters and getters on objects.
 
+## Related Rules
+
+* [no-dupe-keys](no-dupe-keys.md)
+* [no-dupe-class-members](no-dupe-class-members.md)
+
 ## Further Reading
 
 * [Object Setters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/set)

docs/rules/array-bracket-newline.md

@@ -271,10 +271,10 @@ var e = [
 
 If you don't want to enforce line breaks after opening and before closing array brackets, don't enable this rule.
 
-## Compatibility
-
-* **JSCS:** [validateNewlineAfterArrayElements](https://jscs-dev.github.io/rule/validateNewlineAfterArrayElements)
-
 ## Related Rules
 
 * [array-bracket-spacing](array-bracket-spacing.md)
+
+## Compatibility
+
+* **JSCS:** [validateNewlineAfterArrayElements](https://jscs-dev.github.io/rule/validateNewlineAfterArrayElements)

docs/rules/array-element-newline.md

@@ -374,10 +374,6 @@ var [i = function foo() {
 
 If you don't want to enforce linebreaks between array elements, don't enable this rule.
 
-## Compatibility
-
-* **JSCS:** [validateNewlineAfterArrayElements](https://jscs-dev.github.io/rule/validateNewlineAfterArrayElements)
-
 ## Related Rules
 
 * [array-bracket-spacing](array-bracket-spacing.md)
@@ -388,3 +384,7 @@ If you don't want to enforce linebreaks between array elements, don't enable thi
 * [max-statements-per-line](max-statements-per-line.md)
 * [block-spacing](block-spacing.md)
 * [brace-style](brace-style.md)
+
+## Compatibility
+
+* **JSCS:** [validateNewlineAfterArrayElements](https://jscs-dev.github.io/rule/validateNewlineAfterArrayElements)

docs/rules/callback-return.md

@@ -165,11 +165,11 @@ There are some cases where you might want to call a callback function more than
  may lead to incorrect behavior. In those cases you may want to reserve a special name for those callbacks and
  not include that in the list of callbacks that trigger warnings.
 
+## Related Rules
+
+* [handle-callback-err](handle-callback-err.md)
+
 ## Further Reading
 
 * [The Art Of Node: Callbacks](https://github.com/maxogden/art-of-node#callbacks)
 * [Nodejitsu: What are the error conventions?](https://docs.nodejitsu.com/articles/errors/what-are-the-error-conventions/)
-
-## Related Rules
-
-* [handle-callback-err](handle-callback-err.md)

docs/rules/camelcase.md

@@ -241,7 +241,7 @@ Examples of **correct** code for this rule with the `{ "ignoreGlobals": true }`
 const foo = no_camelcased;
 ```
 
-## allow
+### allow
 
 Examples of **correct** code for this rule with the `allow` option:
 

docs/rules/comma-spacing.md

@@ -110,11 +110,6 @@ var arr = [,2 ,3]
 
 If your project will not be following a consistent comma-spacing pattern, turn this rule off.
 
-## Further Reading
-
-* [JavaScript](http://javascript.crockford.com/code.html)
-* [Dojo Style Guide](https://dojotoolkit.org/reference-guide/1.9/developer/styleguide.html)
-
 ## Related Rules
 
 * [array-bracket-spacing](array-bracket-spacing.md)
@@ -125,3 +120,8 @@ If your project will not be following a consistent comma-spacing pattern, turn t
 * [space-after-keywords](space-after-keywords.md)
 * [space-unary-ops](space-unary-ops.md)
 * [space-return-throw-case](space-return-throw-case.md)
+
+## Further Reading
+
+* [JavaScript](http://javascript.crockford.com/code.html)
+* [Dojo Style Guide](https://dojotoolkit.org/reference-guide/1.9/developer/styleguide.html)

docs/rules/comma-style.md

@@ -157,13 +157,13 @@ var o = {fst:1,
 
 This rule can safely be turned off if your project does not care about enforcing a consistent comma style.
 
+## Related Rules
+
+* [operator-linebreak](operator-linebreak.md)
+
 ## Further Reading
 
 For more information on the Comma First style:
 
 * [A better coding convention for lists and object literals in JavaScript by isaacs](https://gist.github.com/isaacs/357981)
 * [npm coding style guideline](https://docs.npmjs.com/misc/coding-style)
-
-## Related Rules
-
-* [operator-linebreak](operator-linebreak.md)

docs/rules/complexity.md

@@ -124,14 +124,6 @@ is equivalent to
 
 If you can't determine an appropriate complexity limit for your code, then it's best to disable this rule.
 
-## Further Reading
-
-* [Cyclomatic Complexity](https://en.wikipedia.org/wiki/Cyclomatic_complexity)
-* [Complexity Analysis of JavaScript Code](https://ariya.io/2012/12/complexity-analysis-of-javascript-code)
-* [More about Complexity in JavaScript](https://craftsmanshipforsoftware.com/2015/05/25/complexity-for-javascript/)
-* [About Complexity](https://web.archive.org/web/20160808115119/http://jscomplexity.org/complexity)
-* [Discussion about Complexity in ESLint and more links](https://github.com/eslint/eslint/issues/4808#issuecomment-167795140)
-
 ## Related Rules
 
 * [max-depth](max-depth.md)
@@ -141,3 +133,11 @@ If you can't determine an appropriate complexity limit for your code, then it's
 * [max-nested-callbacks](max-nested-callbacks.md)
 * [max-params](max-params.md)
 * [max-statements](max-statements.md)
+
+## Further Reading
+
+* [Cyclomatic Complexity](https://en.wikipedia.org/wiki/Cyclomatic_complexity)
+* [Complexity Analysis of JavaScript Code](https://ariya.io/2012/12/complexity-analysis-of-javascript-code)
+* [More about Complexity in JavaScript](https://craftsmanshipforsoftware.com/2015/05/25/complexity-for-javascript/)
+* [About Complexity](https://web.archive.org/web/20160808115119/http://jscomplexity.org/complexity)
+* [Discussion about Complexity in ESLint and more links](https://github.com/eslint/eslint/issues/4808#issuecomment-167795140)

docs/rules/default-case-last.md

@@ -116,10 +116,10 @@ if (foo !== 0) {
 doSomethingAnyway();
 ```
 
-## Further Reading
-
-* [MDN switch statement](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/switch)
-
 ## Related Rules
 
 * [default-case](default-case.md)
+
+## Further Reading
+
+* [MDN switch statement](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/switch)

docs/rules/func-call-spacing.md

@@ -17,12 +17,12 @@ new Date ();
 
 This rule requires or disallows spaces between the function name and the opening parenthesis that calls it.
 
-## options
+## Options
 
 This rule has a string option:
 
-- `"never"` (default) disallows space between the function name and the opening parenthesis.
-- `"always"` requires space between the function name and the opening parenthesis.
+* `"never"` (default) disallows space between the function name and the opening parenthesis.
+* `"always"` requires space between the function name and the opening parenthesis.
 
 Further, in `"always"` mode, a second object option is available that contains a single boolean `allowNewlines` property.
 
@@ -97,9 +97,9 @@ This rule can safely be turned off if your project does not care about enforcing
 
 ## Related Rules
 
-- [no-spaced-func](no-spaced-func.md) (deprecated)
+* [no-spaced-func](no-spaced-func.md) (deprecated)
 
 ## Compatibility
 
-- **JSCS**: [disallowSpacesInCallExpression](https://jscs-dev.github.io/rule/disallowSpacesInCallExpression)
-- **JSCS**: [requireSpacesInCallExpression](https://jscs-dev.github.io/rule/requireSpacesInCallExpression)
+* **JSCS**: [disallowSpacesInCallExpression](https://jscs-dev.github.io/rule/disallowSpacesInCallExpression)
+* **JSCS**: [requireSpacesInCallExpression](https://jscs-dev.github.io/rule/requireSpacesInCallExpression)

docs/rules/func-names.md

@@ -206,12 +206,12 @@ Examples of **correct** code for this rule with the `"never", { "generators": "a
 var foo = bar(function *baz() {});
 ```
 
-## Further Reading
-
-* [Functions Explained](http://markdaggett.com/blog/2013/02/15/functions-explained/)
-* [Function Names in ES6](http://2ality.com/2015/09/function-names-es6.html)
-
 ## Compatibility
 
 * **JSCS**: [requireAnonymousFunctions](https://jscs-dev.github.io/rule/requireAnonymousFunctions)
 * **JSCS**: [disallowAnonymousFunctions](https://jscs-dev.github.io/rule/disallowAnonymousFunctions)
+
+## Further Reading
+
+* [Functions Explained](http://markdaggett.com/blog/2013/02/15/functions-explained/)
+* [Function Names in ES6](http://2ality.com/2015/09/function-names-es6.html)

docs/rules/grouped-accessor-pairs.md

@@ -313,14 +313,14 @@ See [no-dupe-keys](no-dupe-keys.md) if you also want to disallow duplicate keys
 
 See [no-dupe-class-members](no-dupe-class-members.md) if you also want to disallow duplicate names in class definitions.
 
-## Further Reading
-
-* [Object Setters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/set)
-* [Object Getters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/get)
-* [Classes](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes)
-
 ## Related Rules
 
 * [accessor-pairs](accessor-pairs.md)
 * [no-dupe-keys](no-dupe-keys.md)
 * [no-dupe-class-members](no-dupe-class-members.md)
+
+## Further Reading
+
+* [Object Setters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/set)
+* [Object Getters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/get)
+* [Classes](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes)

docs/rules/id-denylist.md

@@ -10,16 +10,16 @@ This rule disallows specified identifiers in assignments and `function` definiti
 
 This rule will catch disallowed identifiers that are:
 
-- variable declarations
-- function declarations
-- object properties assigned to during object creation
-- class fields
-- class methods
+* variable declarations
+* function declarations
+* object properties assigned to during object creation
+* class fields
+* class methods
 
 It will not catch disallowed identifiers that are:
 
-- function calls (so you can still use functions you do not have control over)
-- object properties (so you can still use objects you do not have control over)
+* function calls (so you can still use functions you do not have control over)
+* object properties (so you can still use objects you do not have control over)
 
 ## Options