Skip to content

Commit

Permalink
doc: update config examples for ESLint v9
Browse files Browse the repository at this point in the history
  • Loading branch information
@BenoitZugmeyer
BenoitZugmeyer committed May 20, 2024
1 parent 5860da0 commit 3b5c760
Showing 1 changed file with 236 additions and 35 deletions.
271 changes: 236 additions & 35 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,16 +35,33 @@ Simply install via `npm install --save-dev eslint-plugin-html` and add the plugi
configuration. See
[ESLint documentation](http://eslint.org/docs/user-guide/configuring#configuring-plugins).

Example:
<details open>
<summary>Example with ESLint 9 and above (flat config)</summary>

```javascript
import html from "eslint-plugin-html"

export default [
{
files: ["**/*.html"],
plugins: { html },
},
]
```

</details>

<details>
<summary>Example with ESLint 8 and below</summary>

```json
{
"plugins": [
"html"
]
"plugins": ["html"]
}
```

</details>

## Disabling ESLint

To temporarily disable ESLint, use the `<!-- eslint-disable -->` HTML comment. Re-enable it with
Expand Down Expand Up @@ -91,14 +108,35 @@ option](https://eslint.org/docs/user-guide/configuring#specifying-parser-options
if the script are modules. `eslint-plugin-html` will use this option as well to know if the scopes
should be shared (the default) or not. To change this, just set it in your ESLint configuration:

<details open>
<summary>ESLint 9 and above (flat config)</summary>

```javascript
export default [
{
// ...
languageOptions: {
sourceType: "module",
},
},
]
```

</details>

<details>
<summary>ESLint 8 and below</summary>

```json
{
"parserOptions": {
"sourceType": "module"
}
}
```

</details>

To illustrate this behavior, consider this HTML extract:

```html
Expand Down Expand Up @@ -142,79 +180,197 @@ By default, this plugin will only consider files ending with those extensions as
`.handlebars`, `.hbs`, `.htm`, `.html`, `.mustache`, `.nunjucks`, `.php`, `.tag`, `.twig`, `.we`.
You can set your own list of HTML extensions by using this setting. Example:

<details open>
<summary>ESLint 9 and above (flat config)</summary>

```javascript
export default [
{
files: ["**/*.html", "**/*.we"],
plugins: { html },
settings: {
"html/html-extensions": [".html", ".we"], // consider .html and .we files as HTML
},
},
]
```

Note: you need to specify extensions twice, which is not ideal. This should be imporved in the
future.

</details>

<details>
<summary>ESLint 8 and below</summary>

```json
{
"plugins": [ "html" ],
"settings": {
"html/html-extensions": [".html", ".we"], // consider .html and .we files as HTML
}
"plugins": ["html"],
"settings": {
"html/html-extensions": [".html", ".we"] // consider .html and .we files as HTML
}
}
```

</details>

### `html/xml-extensions`

By default, this plugin will only consider files ending with those extensions as XML: `.xhtml`,
`.xml`. You can set your own list of XML extensions by using this setting. Example:

<details open>
<summary>ESLint 9 and above (flat config)</summary>

```javascript
export default [
{
files: ["**/*.html"],
plugins: { html },
settings: {
"html/xtml-extensions": [".html"], // consider .html files as XML
},
},
]
```

Note: you need to specify extensions twice, which is not ideal. This should be imporved in the
future.

</details>

<details>
<summary>ESLint 8 and below</summary>

```json
{
"plugins": [ "html" ],
"settings": {
"html/xml-extensions": [".html"], // consider .html files as XML
}
"plugins": ["html"],
"settings": {
"html/xml-extensions": [".html"] // consider .html files as XML
}
}
```

</details>

### `html/indent`

By default, the code between `<script>` tags is dedented according to the first non-empty line. The
setting `html/indent` allows to ensure that every script tags follow an uniform indentation. Like
the `indent` rule, you can pass a number of spaces, or `"tab"` to indent with one tab. Prefix this
value with a `+` to be relative to the `<script>` tag indentation. Example:

<details open>
<summary>ESLint 9 and above (flat config)</summary>

```javascript
export default [
{
files: ["**/*.html"],
plugins: { html },
settings: {
"html/indent": "0", // code should start at the beginning of the line (no initial indentation).
"html/indent": "+2", // indentation is the <script> indentation plus two spaces.
"html/indent": "tab", // indentation is one tab at the beginning of the line.
},
},
]
```

</details>

<details>
<summary>ESLint 8 and below</summary>

```json
{
"plugins": [ "html" ],
"settings": {
"html/indent": "0", // code should start at the beginning of the line (no initial indentation).
"html/indent": "+2", // indentation is the <script> indentation plus two spaces.
"html/indent": "tab", // indentation is one tab at the beginning of the line.
}
"plugins": ["html"],
"settings": {
"html/indent": "0", // code should start at the beginning of the line (no initial indentation).
"html/indent": "+2", // indentation is the <script> indentation plus two spaces.
"html/indent": "tab" // indentation is one tab at the beginning of the line.
}
}
```

</details>

### `html/report-bad-indent`

By default, this plugin won't warn if it encounters a problematic indentation (ex: a line is under
indented). If you want to make sure the indentation is correct, use the `html/report-bad-indent` in
conjunction with the `indent` rule. Pass `"warn"` or `1` to display warnings, `"error"` or `2` to
display errors. Example:

<details open>
<summary>ESLint 9 and above (flat config)</summary>

```javascript
export default [
{
files: ["**/*.html"],
plugins: { html },
settings: {
"html/report-bad-indent": "error",
},
},
]
```

</details>

<details>
<summary>ESLint 8 and below</summary>

```json
{
"plugins": [ "html" ],
"settings": {
"html/report-bad-indent": "error",
}
"plugins": ["html"],
"settings": {
"html/report-bad-indent": "error"
}
}
```

</details>

### `html/javascript-tag-names`

By default, the code between `<script>` tags is considered as JavaScript. You can customize which
tags should be considered JavaScript by providing one or multiple tag names.

Example:

<details open>
<summary>ESLint 9 and above (flat config)</summary>

```javascript
export default [
{
files: ["**/*.html"],
plugins: { html },
settings: {
"html/javascript-tag-names": ["script", "customscript"],
},
},
]
```

</details>

<details>
<summary>ESLint 8 and below</summary>

```json
{
"plugins": [ "html" ],
"settings": {
"html/javascript-tag-names": ["script", "customscript"],
}
"plugins": ["html"],
"settings": {
"html/javascript-tag-names": ["script", "customscript"]
}
}
```

</details>

### `html/javascript-mime-types`

By default, the code between `<script>` tags is considered as JavaScript code only if there is no
Expand All @@ -223,31 +379,76 @@ By default, the code between `<script>` tags is considered as JavaScript code on
customize the types that should be considered as JavaScript by providing one or multiple MIME types.
If a MIME type starts with a `/`, it will be considered as a regular expression. Example:

<details open>
<summary>ESLint 9 and above (flat config)</summary>

```javascript
export default [
{
files: ["**/*.html"],
plugins: { html },
settings: {
"html/javascript-mime-types": ["text/javascript", "text/jsx"], // also use script tags with a "text/jsx" type attribute
"html/javascript-mime-types": "/^text\\/(javascript|jsx)$/", // same thing
},
},
]
```

</details>

<details>
<summary>ESLint 8 and below</summary>

```json
{
"plugins": [ "html" ],
"settings": {
"html/javascript-mime-types": ["text/javascript", "text/jsx"], // also use script tags with a "text/jsx" type attribute
"html/javascript-mime-types": "/^text\\/(javascript|jsx)$/", // same thing
}
"plugins": ["html"],
"settings": {
"html/javascript-mime-types": ["text/javascript", "text/jsx"], // also use script tags with a "text/jsx" type attribute
"html/javascript-mime-types": "/^text\\/(javascript|jsx)$/" // same thing
}
}
```

</details>

### `html/ignore-tags-without-type`

By default, the code between `<script>` tags is considered JavaScript if there is no `type`
attribute. You can set this setting to `true` to ignore script tags without a `type` attribute.
Example:

<details open>
<summary>ESLint 9 and above (flat config)</summary>

```javascript
export default [
{
files: ["**/*.html"],
plugins: { html },
settings: {
"html/ignore-tags-without-type": true,
},
},
]
```

</details>

<details>
<summary>ESLint 8 and below</summary>

```json
{
"plugins": [ "html" ],
"settings": {
"html/ignore-tags-without-type": true,
}
"plugins": ["html"],
"settings": {
"html/ignore-tags-without-type": true
}
}
```

</details>

## Troubleshooting

### No file linted when running `eslint` on a directory
Expand Down

0 comments on commit 3b5c760

Please sign in to comment.