Skip to content

Commit

Permalink
[Docs] Add markdownlint for documentation formatting consistency
Browse files Browse the repository at this point in the history
  • Loading branch information
bmish authored and ljharb committed Aug 21, 2022
1 parent 11306e1 commit ae34341
Show file tree
Hide file tree
Showing 52 changed files with 215 additions and 180 deletions.
6 changes: 6 additions & 0 deletions .markdownlint.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
{
"line-length": false,
"no-inline-html": false,
"no-hard-tabs": { "spaces_per_tab": 2 },
"ul-style": { "style": "dash" }
}
3 changes: 3 additions & 0 deletions .markdownlintignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
CHANGELOG.md
LICENSE
node_modules
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,9 @@ This change log adheres to standards from [Keep a CHANGELOG](https://keepachange
* [Docs] Consistent rule descriptions and doc sections ([#3361][] @bmish)
* [Docs] Standardize deprecated rule notice ([#3364][] @bmish)
* [Docs] Fix typos ([#3366][] @bmish)
* [Docs] Add markdownlint for documentation formatting consistency ([#3367][] @bmish)

[#3367]: https://github.com/jsx-eslint/eslint-plugin-react/pull/3367
[#3366]: https://github.com/jsx-eslint/eslint-plugin-react/pull/3366
[#3365]: https://github.com/jsx-eslint/eslint-plugin-react/pull/3365
[#3364]: https://github.com/jsx-eslint/eslint-plugin-react/pull/3364
Expand Down
23 changes: 11 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
# `eslint-plugin-react` <sup>[![Version Badge][npm-version-svg]][package-url]</sup>

===================

[![github actions][actions-image]][actions-url]
Expand All @@ -8,16 +9,15 @@

React specific linting rules for `eslint`

# Installation
## Installation

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

It is also possible to install ESLint globally rather than locally (using npm install eslint --global). However, this is not recommended, and any plugins or shareable configs that you use must be installed locally in either case.

# Configuration

## Configuration

Use [our preset](#recommended) to get reasonable defaults:

Expand Down Expand Up @@ -109,7 +109,7 @@ Enable the rules that you would like to use.
}
```

# List of supported rules
## List of supported rules

✔: Enabled in the [`recommended`](#recommended) configuration.\
🔧: Fixable with [`eslint --fix`](https://eslint.org/docs/user-guide/command-line-interface#fixing-problems).\
Expand Down Expand Up @@ -179,7 +179,7 @@ Enable the rules that you would like to use.
| | | | [react/void-dom-elements-no-children](docs/rules/void-dom-elements-no-children.md) | Disallow void DOM elements (e.g. `<img />`, `<br />`) from receiving children |
<!-- AUTO-GENERATED-CONTENT:END -->

## JSX-specific rules
### JSX-specific rules

<!-- AUTO-GENERATED-CONTENT:START (JSX_RULES) -->
|| 🔧 | 💡 | Rule | Description |
Expand Down Expand Up @@ -225,15 +225,15 @@ Enable the rules that you would like to use.
| | 🔧 | | [react/jsx-wrap-multilines](docs/rules/jsx-wrap-multilines.md) | Disallow missing parentheses around multiline JSX |
<!-- AUTO-GENERATED-CONTENT:END -->

## Other useful plugins
### Other useful plugins

- Rules of Hooks: [eslint-plugin-react-hooks](https://github.com/facebook/react/tree/master/packages/eslint-plugin-react-hooks)
- JSX accessibility: [eslint-plugin-jsx-a11y](https://github.com/evcohen/eslint-plugin-jsx-a11y)
- React Native: [eslint-plugin-react-native](https://github.com/Intellicode/eslint-plugin-react-native)

# Shareable configurations
## Shareable configurations

## Recommended
### Recommended

This plugin exports a `recommended` configuration that enforces React good practices.

Expand All @@ -247,7 +247,7 @@ To enable this configuration use the `extends` property in your `.eslintrc` conf

See [`eslint` documentation](https://eslint.org/docs/user-guide/configuring/configuration-files#extending-configuration-files) for more information about extending configuration files.

## All
### All

This plugin also exports an `all` configuration that includes every available rule.
This pairs well with the `eslint:all` rule.
Expand All @@ -263,11 +263,10 @@ This pairs well with the `eslint:all` rule.

**Note**: These configurations will import `eslint-plugin-react` and enable JSX in [parser options](https://eslint.org/docs/user-guide/configuring/language-options#specifying-parser-options).

# License
## License

`eslint-plugin-react` is licensed under the [MIT License](https://opensource.org/licenses/mit-license.php).


[npm-url]: https://npmjs.org/package/eslint-plugin-react
[npm-image]: https://img.shields.io/npm/v/eslint-plugin-react.svg

Expand Down
1 change: 0 additions & 1 deletion SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,6 @@ This is the list of versions of `eslint-plugin-react` which are currently being
| 7.x | :white_check_mark: |
| < 7.x | :x: |


## Reporting a Vulnerability

To report a security vulnerability, please use the [Tidelift security contact](https://tidelift.com/security). Tidelift will coordinate the fix and disclosure.
7 changes: 4 additions & 3 deletions docs/rules/boolean-prop-naming.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@ var Hello = createReactClass({
render: function() { return <div />; };
});
```

```jsx
type Props = {
isEnabled: boolean
Expand Down Expand Up @@ -94,8 +95,8 @@ The custom message to display upon failure to match the rule. This overrides the

If you choose to use a custom message, you have access to two template variables.

* `propName` – the name of the prop that does not match the pattern
* `pattern` – the pattern against which all prop names are tested
- `propName` – the name of the prop that does not match the pattern
- `pattern` – the pattern against which all prop names are tested

For example, if a prop is named `something`, and if the rule's pattern is set to `"^(is|has)[A-Z]([A-Za-z0-9]?)+"`, you could set the custom message as follows:

Expand All @@ -105,7 +106,7 @@ message: 'It is better if your prop ({{ propName }}) matches this pattern: ({{ p

And the failure would look like so:

```
```plaintext
It is better if your prop (something) matches this pattern: (^is[A-Z]([A-Za-z0-9]?)+)
```

Expand Down
2 changes: 1 addition & 1 deletion docs/rules/default-props-match-prop-types.md
Original file line number Diff line number Diff line change
Expand Up @@ -192,7 +192,7 @@ If you don't care about stray `defaultsProps` in your components, you can disabl

- [require-default-props](./require-default-props.md)

# Resources
## Resources

- [Official React documentation on defaultProps](https://facebook.github.io/react/docs/typechecking-with-proptypes.html#default-prop-values)

Expand Down
1 change: 1 addition & 0 deletions docs/rules/destructuring-assignment.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
🔧 This rule is automatically fixable using the `--fix` [flag](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.

Rule can be set to either of `always` or `never`;

```js
"react/destructuring-assignment": [<enabled>, 'always']
```
Expand Down
6 changes: 3 additions & 3 deletions docs/rules/display-name.md
Original file line number Diff line number Diff line change
Expand Up @@ -130,6 +130,6 @@ For this rule to work we need to detect React components, this could be very har

For now we should detect components created with:

* `createReactClass()`
* an ES6 class that inherit from `React.Component` or `Component`
* a stateless function that return JSX or the result of a `React.createElement` call.
- `createReactClass()`
- an ES6 class that inherit from `React.Component` or `Component`
- a stateless function that return JSX or the result of a `React.createElement` call.
4 changes: 2 additions & 2 deletions docs/rules/forbid-elements.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,8 @@ This rule checks all JSX elements and `React.createElement` calls and verifies t

An array of strings and/or objects. An object in this array may have the following properties:

* `element` (required): the name of the forbidden element (e.g. `'button'`, `'Modal'`)
* `message`: additional message that gets reported
- `element` (required): the name of the forbidden element (e.g. `'button'`, `'Modal'`)
- `message`: additional message that gets reported

A string item in the array is a shorthand for `{ element: string }`.

Expand Down
2 changes: 1 addition & 1 deletion docs/rules/iframe-missing-sandbox.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

The sandbox attribute enables an extra set of restrictions for the content in the iframe. Using sandbox attribute is considered a good security practice.

See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#attr-sandbox
See <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#attr-sandbox>

## Rule Details

Expand Down
8 changes: 4 additions & 4 deletions docs/rules/jsx-closing-bracket-location.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,10 +56,10 @@ The second form allows you to distinguish between non-empty and self-closing tag

Enforced location for the closing bracket.

* `tag-aligned`: must be aligned with the opening tag.
* `line-aligned`: must be aligned with the line containing the opening tag.
* `after-props`: must be placed right after the last prop.
* `props-aligned`: must be aligned with the last prop.
- `tag-aligned`: must be aligned with the opening tag.
- `line-aligned`: must be aligned with the line containing the opening tag.
- `after-props`: must be placed right after the last prop.
- `props-aligned`: must be aligned with the last prop.

Defaults to `tag-aligned`.

Expand Down
22 changes: 12 additions & 10 deletions docs/rules/jsx-curly-brace-presence.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,18 +30,18 @@ or alternatively
...
```

### Valid options for <string>
### Valid options for `<string>`

They are `always`, `never` and `ignore` for checking on JSX props and children.

* `always`: always enforce curly braces inside JSX props, children, and/or JSX prop values that are JSX Elements
* `never`: never allow unnecessary curly braces inside JSX props, children, and/or JSX prop values that are JSX Elements
* `ignore`: ignore the rule for JSX props, children, and/or JSX prop values that are JSX Elements
- `always`: always enforce curly braces inside JSX props, children, and/or JSX prop values that are JSX Elements
- `never`: never allow unnecessary curly braces inside JSX props, children, and/or JSX prop values that are JSX Elements
- `ignore`: ignore the rule for JSX props, children, and/or JSX prop values that are JSX Elements

If passed in the option to fix, this is how a style violation will get fixed

* `always`: wrap a JSX attribute in curly braces/JSX expression and/or a JSX child the same way but also with double quotes
* `never`: get rid of curly braces from a JSX attribute and/or a JSX child
- `always`: wrap a JSX attribute in curly braces/JSX expression and/or a JSX child the same way but also with double quotes
- `never`: get rid of curly braces from a JSX attribute and/or a JSX child

- All fixing operations use double quotes.

Expand Down Expand Up @@ -76,6 +76,7 @@ They can be fixed to:
```

Examples of **incorrect** code for this rule, when configured with `{ props: "always", children: "always", "propElementValues": "always" }`:

```jsx
<App prop=<div /> />;
```
Expand All @@ -87,6 +88,7 @@ They can be fixed to:
```

Examples of **incorrect** code for this rule, when configured with `{ props: "never", children: "never", "propElementValues": "never" }`:

```jsx
<App prop={<div />} />;
```
Expand All @@ -113,6 +115,7 @@ Examples of **incorrect** code for this rule, when configured with `"always"`:
```

They can be fixed to:

```jsx
<App>{"Hello world"}</App>;
<App prop={"Hello world"} attr={"foo"}>{"Hello world"}</App>;
Expand All @@ -134,7 +137,7 @@ It can fixed to:

The fix also deals with template literals, strings with quotes, and strings with escapes characters.

* If the rule is set to get rid of unnecessary curly braces and the template literal inside a JSX expression has no expression, it will throw a warning and be fixed with double quotes. For example:
- If the rule is set to get rid of unnecessary curly braces and the template literal inside a JSX expression has no expression, it will throw a warning and be fixed with double quotes. For example:

```jsx
<App prop={`Hello world`}>{`Hello world`}</App>;
Expand All @@ -146,11 +149,10 @@ will be warned and fixed to:
<App prop="Hello world">Hello world</App>;
```

* If the rule is set to enforce curly braces and the strings have quotes, it will be fixed with double quotes for JSX children and the normal way for JSX attributes. Also, double quotes will be escaped in the fix.
- If the rule is set to enforce curly braces and the strings have quotes, it will be fixed with double quotes for JSX children and the normal way for JSX attributes. Also, double quotes will be escaped in the fix.

For example:


```jsx
<App prop='Hello "foo" world'>Hello 'foo' "bar" world</App>;
```
Expand All @@ -161,7 +163,7 @@ will warned and fixed to:
<App prop={"Hello \"foo\" world"}>{"Hello 'foo' \"bar\" world"}</App>;
```

* If the rule is set to get rid of unnecessary curly braces(JSX expression) and there are characters that need to be escaped in its JSX form, such as quote characters, [forbidden JSX text characters](https://facebook.github.io/jsx/), escaped characters and anything that looks like HTML entity names, the code will not be warned because the fix may make the code less readable.
- If the rule is set to get rid of unnecessary curly braces(JSX expression) and there are characters that need to be escaped in its JSX form, such as quote characters, [forbidden JSX text characters](https://facebook.github.io/jsx/), escaped characters and anything that looks like HTML entity names, the code will not be warned because the fix may make the code less readable.

Examples of **correct** code for this rule, even when configured with `"never"`:

Expand Down
12 changes: 6 additions & 6 deletions docs/rules/jsx-curly-newline.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,18 +18,19 @@ This rule accepts either an object option:
singleline: "consistent" | "forbid" | "require", // default to 'consistent'
}
```

Option `multiline` takes effect when the jsx expression inside the curlies occupies multiple lines.

Option `singleline` takes effect when the jsx expression inside the curlies occupies a single line.

* `consistent` enforces either both curly braces have a line break directly inside them, or no line breaks are present.
* `forbid` disallows linebreaks directly inside curly braces.
* `require` enforces the presence of linebreaks directly inside curlies.
- `consistent` enforces either both curly braces have a line break directly inside them, or no line breaks are present.
- `forbid` disallows linebreaks directly inside curly braces.
- `require` enforces the presence of linebreaks directly inside curlies.

or a string option:

* `consistent` (default) is an alias for `{ multiline: "consistent", singleline: "consistent" }`.
* `never` is an alias for `{ multiline: "forbid", singleline: "forbid" }`
- `consistent` (default) is an alias for `{ multiline: "consistent", singleline: "consistent" }`.
- `never` is an alias for `{ multiline: "forbid", singleline: "forbid" }`

or an

Expand Down Expand Up @@ -143,7 +144,6 @@ Examples of **correct** code for this rule:
</div>
```


## When Not To Use It

You can turn this rule off if you are not concerned with the consistency of padding linebreaks inside of JSX attributes or expressions.
12 changes: 6 additions & 6 deletions docs/rules/jsx-curly-spacing.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,14 +14,14 @@ It either requires or disallows spaces between those braces and the values insid

There are two main options for the rule:

* `{"when": "always"}` enforces a space inside of curly braces
* `{"when": "never"}` disallows spaces inside of curly braces (default)
- `{"when": "always"}` enforces a space inside of curly braces
- `{"when": "never"}` disallows spaces inside of curly braces (default)

There are also two properties that allow specifying how the rule should work with the attributes (`attributes`) and the expressions (`children`). The possible values are:

* `true` enables checking for the spacing using the options (default for `attributes`), e.g. `{"attributes": false}` disables checking the attributes
* `false` disables checking for the spacing (default for `children`, for backward compatibility), e.g. `{"children": true}` enables checking the expressions
* an object containing options that override the global options, e.g. `{"when": "always", "children": {"when": "never"}}` enforces a space inside attributes, but disallows spaces inside expressions
- `true` enables checking for the spacing using the options (default for `attributes`), e.g. `{"attributes": false}` disables checking the attributes
- `false` disables checking for the spacing (default for `children`, for backward compatibility), e.g. `{"children": true}` enables checking the expressions
- an object containing options that override the global options, e.g. `{"when": "always", "children": {"when": "never"}}` enforces a space inside attributes, but disallows spaces inside expressions

### never

Expand Down Expand Up @@ -203,7 +203,7 @@ You can specify an additional `spacing` property that is an object with the foll
}}]
```

* `objectLiterals`: This controls different spacing requirements when the value inside the jsx curly braces is an object literal.
- `objectLiterals`: This controls different spacing requirements when the value inside the jsx curly braces is an object literal.

All spacing options accept either the string `"always"` or the string `"never"`. Note that the default value for all "spacing" options matches the first "always"/"never" option provided.

Expand Down
4 changes: 2 additions & 2 deletions docs/rules/jsx-equals-spacing.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,8 @@ This rule will enforce consistency of spacing around equal signs in JSX attribut

There are two options for the rule:

* `"always"` enforces spaces around the equal sign
* `"never"` disallows spaces around the equal sign (default)
- `"always"` enforces spaces around the equal sign
- `"never"` disallows spaces around the equal sign (default)

Depending on your coding conventions, you can choose either option by specifying it in your configuration:

Expand Down
8 changes: 4 additions & 4 deletions docs/rules/jsx-first-prop-new-line.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,10 +10,10 @@ Note: The fixer does not include indentation. Please rerun lint to correct those

This rule checks whether the first property of all JSX elements is correctly placed. There are the possible configurations:

* `always`: The first property should always be placed on a new line.
* `never` : The first property should never be placed on a new line, e.g. should always be on the same line as the Component opening tag.
* `multiline`: The first property should always be placed on a new line when the JSX tag takes up multiple lines.
* `multiline-multiprop`: The first property should always be placed on a new line if the JSX tag takes up multiple lines and there are multiple properties. This is the `default` value.
- `always`: The first property should always be placed on a new line.
- `never` : The first property should never be placed on a new line, e.g. should always be on the same line as the Component opening tag.
- `multiline`: The first property should always be placed on a new line when the JSX tag takes up multiple lines.
- `multiline-multiprop`: The first property should always be placed on a new line if the JSX tag takes up multiple lines and there are multiple properties. This is the `default` value.

Examples of **incorrect** code for this rule, when configured with `"always"`:

Expand Down
4 changes: 2 additions & 2 deletions docs/rules/jsx-fragments.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

🔧 This rule is automatically fixable using the `--fix` [flag](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.

In JSX, a React fragment is created either with `<React.Fragment>...</React.Fragment>`, or, using the shorthand syntax, `<>...</>`.
In JSX, a React [fragment] is created either with `<React.Fragment>...</React.Fragment>`, or, using the shorthand syntax, `<>...</>`.

## Rule Details

Expand Down Expand Up @@ -58,6 +58,6 @@ Examples of **correct** code for this rule:
<React.Fragment key="key"><Foo /></React.Fragment>
```

[fragments]: https://reactjs.org/docs/fragments.html
[fragment]: https://reactjs.org/docs/fragments.html
[shared_settings]: /README.md#configuration
[short_syntax]: https://reactjs.org/docs/fragments.html#short-syntax
Loading

0 comments on commit ae34341

Please sign in to comment.