diff --git a/docs/docs/eslint.md b/docs/docs/eslint.md index 79fb64e1ef081..6460c03a4da5f 100644 --- a/docs/docs/eslint.md +++ b/docs/docs/eslint.md @@ -38,10 +38,8 @@ module.exports = { } ``` -### Disabling ESLint - -Create an empty .eslintrc.js file at the root of your project to disable linting. +Note: When there is no ESLint file Gatsby implicitly adds a barebones ESLint loader. This loader pipes ESLint feedback into the terminal window where you are running or building Gatsby and also to the console in your browser developer tools. This gives you consolidated, immediate feedback on newly-saved files. When you include a custom `.eslintrc` file, Gatsby gives you full control over the ESLint configuration. This means that it will override the built-in `eslint-loader` and you need to enable any and all rules yourself. One way to do this is to use the Community plugin [`gatsby-eslint-plugin`](/packages/gatsby-plugin-eslint/). This also means that the default [ESLint config Gatsby ships with](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/utils/eslint-config.js) will be entirely overwritten. If you would still like to take advantage of those rules, you'll need to copy them to your local file. -When there is no ESLint file Gatsby implicitly adds a barebones ESLint loader. The empty file will disable this behavior as Gatsby assumes once you have an ESLint file you are in charge of linting. +### Disabling ESLint -Note: If you provide a custom `.eslintrc.js` file, Gatsby gives you full control about the ESLint configuration. This means that it will disable the built-in `eslint-loader` and you need to enable it yourself. One way to do so is to use the Community plugin [`gatsby-eslint-plugin`](/packages/gatsby-plugin-eslint/). +Creating an empty `.eslintrc` file at the root of your project will disable ESLint for your site. The empty file will disable the built-in `eslint-loader` because Gatsby assumes once you have an ESLint file you are in charge of linting. diff --git a/docs/docs/making-your-site-accessible.md b/docs/docs/making-your-site-accessible.md index e3db6d52fc7b5..e34467d51bb40 100644 --- a/docs/docs/making-your-site-accessible.md +++ b/docs/docs/making-your-site-accessible.md @@ -35,21 +35,23 @@ For websites, rendering [static HTML](/docs/glossary#static) pages means that Ja ### Linting with eslint-jsx-plugin-a11y -Gatsby ships with `eslint-config-react-app` by default, which includes the `eslint-jsx-plugin-a11y` package. [eslint-plugin-jsx-a11y](https://github.com/evcohen/eslint-plugin-jsx-a11y) is an accessibility [linting](/docs/glossary#linting) tool for your code, helping you develop more inclusive Gatsby projects. This plugin encourages you to include alternative text for image tags, validates [ARIA](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA) props, and eliminates redundant role properties, among other things. It's a start to testing for accessibility: [further recommendations](#how-to-improve-accessibility) can be found below. +Gatsby ships with the `eslint-jsx-plugin-a11y` package and warnings for all of its rules enabled by default. [eslint-plugin-jsx-a11y](https://github.com/evcohen/eslint-plugin-jsx-a11y) is an accessibility [linting](/docs/glossary#linting) tool for your code, helping you develop more inclusive Gatsby projects by reducing the time to find accessibility errors. This plugin encourages you to include alternative text for image tags, validates [ARIA](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA) props, and eliminates redundant role properties, among other things. -Including this plugin and its [recommended rule set](https://github.com/facebook/create-react-app/tree/master/packages/eslint-config-react-app#accessibility-checks) reduces the time required to implement accessibility by reminding you throughout development. The rules enabled in `eslint-plugin-jsx-a11y` by default can be [customized in `.eslintrc`](/docs/eslint/#configuring-eslint). +For more on supported rules, check out the docs for [`eslint-plugin-jsx-a11y`](https://github.com/evcohen/eslint-plugin-jsx-a11y). You can customize those rules in your [`.eslintrc`](/docs/eslint/#configuring-eslint). ```json:title=.eslintrc { "extends": ["react-app", "plugin:jsx-a11y/recommended"], "plugins": ["jsx-a11y"], "rules": { - "jsx-a11y/rule-name": 2 + "jsx-a11y/rule-name": "warning" } } ``` -For more on supported rules, check out the docs for [`eslint-plugin-jsx-a11y`](https://github.com/evcohen/eslint-plugin-jsx-a11y). +Note: Including a local `.eslintrc` file will [override](/docs/eslint/#configuring-eslint) all of Gatsby's default linting and disable the built-in `eslint-loader`, meaning your tweaked rules won't make it to your browser's developer console or your terminal window but will still be displayed if you have ESLint plugins enabled in your IDE. If you would like to change this behavior and make sure the `eslint-loader` pulls in your customizations, you'll need to enable the loader yourself. One way to do this is by using the Community plugin [`gatsby-plugin-eslint`](https://www.gatsbyjs.org/packages/gatsby-plugin-eslint/). Additionally, if you would still like to take advantage of some subset of the default [ESLint config Gatsby ships with](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/utils/eslint-config.js), you'll need to copy them manually to your local `.eslintrc` file. + +This is a start to testing for accessibility: [further recommendations](#how-to-improve-accessibility) can be found below. ## How to improve accessibility?