Skip to content

Commit

Permalink
Docs: Relocate recommended rule section in docs
Browse files Browse the repository at this point in the history
This is a cut-and-paste commit. I'm going to update these to reflect the
recommended config and want to put them under the "Advanced
Configuration" section. I did this in a precursor commit to make
reviewing the actual textual diff easier in the next commit.
  • Loading branch information
btmills committed Aug 13, 2020
1 parent d80be9e commit 0b1a905
Showing 1 changed file with 64 additions and 64 deletions.
128 changes: 64 additions & 64 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,70 @@ module.exports = {
};
```

## Unsatisfiable Rules

Since code blocks are not files themselves but embedded inside a Markdown document, some rules do not apply to Markdown code blocks, and messages from these rules are automatically suppressed:

- `eol-last`
- `unicode-bom`

### Project or directory-wide overrides for code snippets

Given that code snippets often lack full context, and adding full context through configuration comments may be too cumbersome to apply for each snippet, one may wish to instead set defaults for all one's JavaScript snippets in a manner that applies to all Markdown files within your project (or a specific directory).

ESLint allows a configuration property `overrides` which has a `files` property which accepts a [glob pattern](https://eslint.org/docs/user-guide/configuring#configuration-based-on-glob-patterns), allowing you to designate files (such as all `md` files) whose rules will be overridden.

The following example shows the disabling of a few commonly problematic rules for code snippets.
It also points to the fact that some rules (e.g., `padded-blocks`) may be more appealing for disabling given that one may wish for documentation to be more liberal in providing padding for readability.

```js
// .eslintrc.js
module.exports = {
plugins: ["markdown"],
overrides: [
{
files: ["**/*.md"],
processor: "markdown/markdown"
},
{
files: ["**/*.md/*.js"],
rules: {
"no-undef": "off",
"no-unused-vars": "off",
"no-console": "off",
"padded-blocks": "off"
}
}
]
};
```

### Overriding `strict`

The `strict` rule is technically satisfiable inside of Markdown code blocks, but writing a `"use strict"` directive at the top of every code block is tedious and distracting.
We recommend a glob pattern for `.md` files containing `.js` blocks to disable `strict` and enable the `impliedStrict` [parser option](https://eslint.org/docs/user-guide/configuring#specifying-parser-options) so the code blocks still parse in strict mode:

```js
// .eslintrc.js
module.exports = {
plugins: ["markdown"],
overrides: [
{
files: ["**/*.md"],
processor: "markdown/markdown"
},
{
files: ["**/*.md/*.js"],
parserOptions: {
ecmaFeatures: {
impliedStrict: true
}
}
}
]
};
```

#### Migrating from `eslint-plugin-markdown` v1

`eslint-plugin-markdown` v1 used an older version of ESLint's processor API.
Expand Down Expand Up @@ -292,70 +356,6 @@ console.log("This code block is linted normally.");
```
````

## Unsatisfiable Rules

Since code blocks are not files themselves but embedded inside a Markdown document, some rules do not apply to Markdown code blocks, and messages from these rules are automatically suppressed:

- `eol-last`
- `unicode-bom`

### Project or directory-wide overrides for code snippets

Given that code snippets often lack full context, and adding full context through configuration comments may be too cumbersome to apply for each snippet, one may wish to instead set defaults for all one's JavaScript snippets in a manner that applies to all Markdown files within your project (or a specific directory).

ESLint allows a configuration property `overrides` which has a `files` property which accepts a [glob pattern](https://eslint.org/docs/user-guide/configuring#configuration-based-on-glob-patterns), allowing you to designate files (such as all `md` files) whose rules will be overridden.

The following example shows the disabling of a few commonly problematic rules for code snippets.
It also points to the fact that some rules (e.g., `padded-blocks`) may be more appealing for disabling given that one may wish for documentation to be more liberal in providing padding for readability.

```js
// .eslintrc.js
module.exports = {
plugins: ["markdown"],
overrides: [
{
files: ["**/*.md"],
processor: "markdown/markdown"
},
{
files: ["**/*.md/*.js"],
rules: {
"no-undef": "off",
"no-unused-vars": "off",
"no-console": "off",
"padded-blocks": "off"
}
}
]
};
```

### Overriding `strict`

The `strict` rule is technically satisfiable inside of Markdown code blocks, but writing a `"use strict"` directive at the top of every code block is tedious and distracting.
We recommend a glob pattern for `.md` files containing `.js` blocks to disable `strict` and enable the `impliedStrict` [parser option](https://eslint.org/docs/user-guide/configuring#specifying-parser-options) so the code blocks still parse in strict mode:

```js
// .eslintrc.js
module.exports = {
plugins: ["markdown"],
overrides: [
{
files: ["**/*.md"],
processor: "markdown/markdown"
},
{
files: ["**/*.md/*.js"],
parserOptions: {
ecmaFeatures: {
impliedStrict: true
}
}
}
]
};
```

## Editor Integrations

### VSCode
Expand Down

0 comments on commit 0b1a905

Please sign in to comment.