docs: use descriptive links instead of "click here" (#25897 )

* docs: use descriptive links instead of "click here"

Linking text such as "here" or "click here" is not accessible (and
doesn't look that great either). The best example of why it's better to
use link text that provides context is that some screen readers allow
navigation by links alone. If all links say "click here", then how does
the user know which one to go to?

I tried to make the minimal change necessary to make the link text
descriptive but had to reword a few sentences that didn't read well.

* Apply suggestions from code review

Co-authored-by: Lee Robinson <me@leerob.io>
Co-authored-by: JJ Kasper <jj@jjsweb.site>

2021-06-09 13:23:16 -05:00

2.2 KiB

Raw Blame History

Invalid PostCSS Configuration

Why This Error Occurred

PostCSS configuration was provided in an unsupported shape.

Possible Ways to Fix It

PostCSS configuration must be defined in the following shape:

module.exports = {
  plugins: [
    // A plugin that does not require configuration:
    'simple-plugin-example',

    // A plugin which needs a configuration object:
    [
      'plugin-with-configuration',
      {
        optionA: '...',
      },
    ],

    // A plugin that is toggled on or off based on environment:
    [
      'plugin-toggled',
      process.env.NODE_ENV === 'production'
        ? {
            optionA: '...',
          }
        : false,
    ],

    // Boolean expressions are also valid.
    // `true` enables the plugin, `false` disables the plugin:
    ['plugin-toggled-2', true /* a === b, etc */],
  ],
}

Common Errors

Before: plugin is require()'d

const pluginA = require('postcss-plugin-a')
module.exports = {
  plugins: [require('postcss-plugin'), pluginA],
}

After

module.exports = {
  plugins: ['postcss-plugin', 'postcss-plugin-a'],
}

Before: plugin is instantiated with configuration

module.exports = {
  plugins: [
    require('postcss-plugin')({
      optionA: '...',
    }),
  ],
}

After

module.exports = {
  plugins: [
    // Pay attention to this nested array. The first index is the plugin name,
    // the second index is the configuration.
    [
      'postcss-plugin',
      {
        optionA: '...',
      },
    ],
  ],
}

Before: plugin is missing configuration

module.exports = {
  plugins: [
    [
      'postcss-plugin-1',
      {
        optionA: '...',
      },
    ],
    // This single-entry array is detected as misconfigured because it's
    // missing the second element. To fix, unwrap the value.
    ['postcss-plugin-2'],
  ],
}

After

module.exports = {
  plugins: [
    [
      'postcss-plugin-1',
      {
        optionA: '...',
      },
    ],
    // Only string:
    'postcss-plugin-2',
  ],
}

2.2 KiB Raw Blame History

Invalid PostCSS Configuration

Why This Error Occurred

Possible Ways to Fix It

Common Errors

2.2 KiB

Raw Blame History