Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
docs: enable a few more markdownlint rules and fix violations (#15368)
  • Loading branch information
bmish committed Nov 30, 2021
1 parent 4ebc062 commit e233920
Show file tree
Hide file tree
Showing 74 changed files with 90 additions and 174 deletions.
4 changes: 0 additions & 4 deletions .markdownlint.yml
@@ -1,11 +1,9 @@
default: true

# Exclusions for deliberate/widespread violations
MD001: false # Header levels should only increment by one level at a time
MD002: false # First header should be a h1 header
MD007: # Unordered list indentation
indent: 4
MD012: false # Multiple consecutive blank lines
MD013: false # Line length
MD014: false # Dollar signs used before commands without showing output
MD019: false # Multiple spaces after hash on atx style header
Expand All @@ -15,7 +13,5 @@ MD026: false # Trailing punctuation in header
MD029: false # Ordered list item prefix
MD030: false # Spaces after list markers
MD033: false # Allow inline HTML
MD034: false # Bare URL used
MD040: false # Fenced code blocks should have a language specified
MD041: false # First line in file should be a top level header
MD046: false # Code block style
2 changes: 2 additions & 0 deletions .markdownlintignore
@@ -1 +1,3 @@
CHANGELOG.md
node_modules
tmp
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Expand Up @@ -24,4 +24,4 @@ Please sign our [Contributor License Agreement](https://cla.js.foundation/eslint
## Full Documentation

Our full contribution guidelines can be found at:
https://eslint.org/docs/developer-guide/contributing/
<https://eslint.org/docs/developer-guide/contributing/>
16 changes: 3 additions & 13 deletions README.md
Expand Up @@ -47,19 +47,19 @@ Prerequisites: [Node.js](https://nodejs.org/) (`^12.22.0`, `^14.17.0`, or `>=16.

You can install ESLint using npm:

```
```sh
$ npm install eslint --save-dev
```

You should then set up a configuration file:

```
```sh
$ ./node_modules/.bin/eslint --init
```

After that, you can run ESLint on any file or directory like this:

```
```sh
$ ./node_modules/.bin/eslint yourfile.js
```

Expand Down Expand Up @@ -207,8 +207,6 @@ These folks keep the project moving and are resources for help.

<!-- NOTE: This section is autogenerated. Do not manually edit.-->



<!--teamstart-->

### Technical Steering Committee (TSC)
Expand All @@ -232,7 +230,6 @@ Milos Djermanovic
</a>
</td></tr></tbody></table>


### Reviewers

The people who review and implement new features.
Expand All @@ -249,9 +246,6 @@ Toru Nagashima
</a>
</td></tr></tbody></table>




### Committers

The people who review and fix bugs and help triage issues.
Expand Down Expand Up @@ -288,12 +282,8 @@ Nitin Kumar
</a>
</td></tr></tbody></table>


<!--teamend-->




## <a name="sponsors"></a>Sponsors

The following companies, organizations, and individuals support ESLint's ongoing maintenance and development. [Become a Sponsor](https://opencollective.com/eslint) to get your logo on our README and website.
Expand Down
2 changes: 0 additions & 2 deletions docs/developer-guide/code-path-analysis.md
Expand Up @@ -189,8 +189,6 @@ bar();

![Loop Event's Example 5](./code-path-analysis/loop-event-example-for-5.svg)



## Usage Examples

### To check whether or not this is reachable
Expand Down
26 changes: 13 additions & 13 deletions docs/developer-guide/contributing/pull-requests.md
Expand Up @@ -30,7 +30,7 @@ Details about each step are found below.

The first step to sending a pull request is to create a new branch in your ESLint fork. Give the branch a descriptive name that describes what it is you're fixing, such as:

```
```sh
$ git checkout -b issue1234
```

Expand All @@ -42,14 +42,14 @@ You should do all of your development for the issue in this branch.

Make the changes to the code and tests, following the [code conventions](../code-conventions.md) as you go. Once you have finished, commit the changes to your branch:

```
```sh
$ git add -A
$ git commit
```

All ESLint projects follow [Conventional Commits](https://www.conventionalcommits.org/) for our commit messages. Here's an example commit message:

```
```pt
tag: Short description of what you did

Longer description here if necessary
Expand Down Expand Up @@ -79,7 +79,7 @@ The message summary should be a one-sentence description of the change, and it m

Here are some good commit message summary examples:

```
```pt
build: Update Travis to only test Node 0.10
fix: Semi rule incorrectly flagging extra semicolon
chore: Upgrade Esprima to 1.2, switch to using comment attachment
Expand All @@ -91,7 +91,7 @@ The commit message format is important because these messages are used to create

Before you send the pull request, be sure to rebase onto the upstream source. This ensures your code is running on the latest available code.

```
```sh
git fetch upstream
git rebase upstream/main
```
Expand All @@ -100,7 +100,7 @@ git rebase upstream/main

After rebasing, be sure to run all of the tests once again to make sure nothing broke:

```
```sh
npm test
```

Expand All @@ -123,13 +123,13 @@ With your code ready to go, this is a good time to double-check your submission

Next, push your changes to your clone:

```
```sh
git push origin issue1234
```

If you are unable to push because some references are old, do a forced push instead:

```
```sh
git push -f origin issue1234
```

Expand All @@ -149,21 +149,21 @@ Once your pull request is sent, it's time for the team to review it. As such, pl

If your commit message is in the incorrect format, you'll be asked to update it. You can do so via:

```
```sh
$ git commit --amend
```

This will open up your editor so you can make changes. After that, you'll need to do a forced push to your branch:

```
```sh
$ git push origin issue1234 -f
```

### Updating the Code

If we ask you to make code changes, there's no need to close the pull request and create a new one. Just go back to the branch on your fork and make your changes. Then, when you're ready, you can add your changes into the branch:

```
```sh
$ git add -A
$ git commit
$ git push origin issue1234
Expand All @@ -177,13 +177,13 @@ The commit messages in subsequent commits do not need to be in any specific form

If your code is out-of-date, we might ask you to rebase. That means we want you to apply your changes on top of the latest upstream code. Make sure you have set up a [development environment](../development-environment.md) and then you can rebase using these commands:

```
```sh
$ git fetch upstream
$ git rebase upstream/main
```

You might find that there are merge conflicts when you attempt to rebase. Please [resolve the conflicts](https://help.github.com/articles/resolving-merge-conflicts-after-a-git-rebase/) and then do a forced push to your branch:

```
```sh
$ git push origin issue1234 -f
```
6 changes: 3 additions & 3 deletions docs/developer-guide/development-environment.md
Expand Up @@ -14,7 +14,7 @@ Go to <https://github.com/eslint/eslint> and click the "Fork" button. Follow the

Once you've cloned the repository, run `npm install` to get all the necessary dependencies:

```
```sh
$ cd eslint
$ npm install
```
Expand All @@ -27,7 +27,7 @@ The *upstream source* is the main ESLint repository where active development hap

To add the upstream source for ESLint, run the following in your repository:

```
```sh
git remote add upstream git@github.com:eslint/eslint.git
```

Expand All @@ -49,7 +49,7 @@ Please see the [generator documentation](https://github.com/eslint/generator-esl

Running the tests is the best way to ensure you have correctly set up your development environment. Make sure you're in the `eslint` directory and run:

```
```sh
npm test
```

Expand Down
6 changes: 3 additions & 3 deletions docs/developer-guide/nodejs-api.md
Expand Up @@ -473,7 +473,7 @@ const linter2 = new Linter();
```

In this example, rules run on `linter1` will get `path/to/project` when calling `context.getCwd()`.
Those run on `linter2` will get `process.cwd()` if the global `process` object is defined or `undefined` otherwise (e.g. on the browser https://eslint.org/demo).
Those run on `linter2` will get `process.cwd()` if the global `process` object is defined or `undefined` otherwise (e.g. on the browser <https://eslint.org/demo>).

### Linter#verify

Expand Down Expand Up @@ -783,7 +783,7 @@ Any additional properties of a test case will be passed directly to the linter a

If a valid test case only uses the `code` property, it can optionally be provided as a string containing the code, rather than an object with a `code` key.

#### Testing errors with `messageId`
### Testing errors with `messageId`

If the rule under test uses `messageId`s, you can use `messageId` property in a test case to assert reported error's `messageId` instead of its `message`.

Expand All @@ -805,7 +805,7 @@ For messages with placeholders, a test case can also use `data` property to addi

Please note that `data` in a test case does not assert `data` passed to `context.report`. Instead, it is used to form the expected message text which is then compared with the received `message`.

#### Testing Suggestions
### Testing Suggestions

Suggestions can be tested by defining a `suggestions` key on an errors object. The options to check for the suggestions are the following (all are optional):

Expand Down
9 changes: 5 additions & 4 deletions docs/developer-guide/shareable-configs.md
Expand Up @@ -32,9 +32,11 @@ Once your shareable config is ready, you can [publish to npm](https://docs.npmjs

You should declare your dependency on ESLint in `package.json` using the [peerDependencies](https://docs.npmjs.com/files/package.json#peerdependencies) field. The recommended way to declare a dependency for future proof compatibility is with the ">=" range syntax, using the lowest required ESLint version. For example:

```
"peerDependencies": {
"eslint": ">= 3"
```json
{
"peerDependencies": {
"eslint": ">= 3"
}
}
```

Expand Down Expand Up @@ -76,7 +78,6 @@ You can also omit the `eslint-config-` and it will be automatically assumed by E

npm [scoped modules](https://docs.npmjs.com/misc/scope) are also supported in a number of ways.


By using the module name:

```json
Expand Down
3 changes: 1 addition & 2 deletions docs/developer-guide/working-with-custom-formatters.md
Expand Up @@ -29,7 +29,7 @@ eslint -f ./my-awesome-formatter.js src/

In order to use a local file as a custom formatter, you must begin the filename with a dot (such as `./my-awesome-formatter.js` or `../formatters/my-awesome-formatter.js`).

### The `data` Argument
## The `data` Argument

The exported function receives an optional second argument named `data`. The `data` object provides extended information related to the analysis results. Currently, the `data` object consists of a single property named `rulesMeta`. This property is a dictionary of rule metadata, keyed with `ruleId`. The value for each entry is the `meta` property from the corresponding rule object. The dictionary contains an entry for each rule that was run during the analysis.

Expand Down Expand Up @@ -358,7 +358,6 @@ error semi
src/configs/bundler.js:6:10
```


### Complex Argument Passing

If you find the custom formatter pattern doesn't provide enough options for the way you'd like to format ESLint results, the best option is to use ESLint's built-in [JSON formatter](https://eslint.org/docs/user-guide/formatters/) and pipe the output to a second program. For example:
Expand Down
1 change: 0 additions & 1 deletion docs/rules/accessor-pairs.md
Expand Up @@ -232,7 +232,6 @@ const Quux = class {
}
```


## Known Limitations

Due to the limits of static analysis, this rule does not account for possible side effects and in certain cases
Expand Down
1 change: 0 additions & 1 deletion docs/rules/array-bracket-newline.md
Expand Up @@ -267,7 +267,6 @@ var e = [
];
```


## When Not To Use It

If you don't want to enforce line breaks after opening and before closing array brackets, don't enable this rule.
Expand Down
1 change: 0 additions & 1 deletion docs/rules/array-callback-return.md
Expand Up @@ -144,7 +144,6 @@ myArray.forEach(item => {
});
```


## Known Limitations

This rule checks callback functions of methods with the given names, *even if* the object which has the method is *not* an array.
Expand Down
1 change: 0 additions & 1 deletion docs/rules/arrow-parens.md
Expand Up @@ -20,7 +20,6 @@ a => {}
Following this style will help you find arrow functions (`=>`) which may be mistakenly included in a condition
when a comparison such as `>=` was the intent.


```js
/*eslint-env es6*/

Expand Down
1 change: 0 additions & 1 deletion docs/rules/callback-return.md
Expand Up @@ -165,7 +165,6 @@ 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.


## Further Reading

* [The Art Of Node: Callbacks](https://github.com/maxogden/art-of-node#callbacks)
Expand Down
4 changes: 2 additions & 2 deletions docs/rules/class-methods-use-this.md
Expand Up @@ -99,7 +99,7 @@ This rule has two options:

### exceptMethods

```
```js
"class-methods-use-this": [<enabled>, { "exceptMethods": [<...exceptions>] }]
```

Expand Down Expand Up @@ -131,7 +131,7 @@ class A {

## enforceForClassFields

```
```js
"class-methods-use-this": [<enabled>, { "enforceForClassFields": true | false }]
```

Expand Down
2 changes: 0 additions & 2 deletions docs/rules/comma-spacing.md
Expand Up @@ -110,13 +110,11 @@ 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)
Expand Down
2 changes: 0 additions & 2 deletions docs/rules/comma-style.md
Expand Up @@ -157,15 +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.


## 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)

0 comments on commit e233920

Please sign in to comment.