diff --git a/README.md b/README.md
index 30a303c..44b349b 100644
--- a/README.md
+++ b/README.md
@@ -1,12 +1,17 @@
# babel-plugin-react-css-modules
-[](https://gitspo.com/mentions/gajus/babel-plugin-react-css-modules)
[](https://travis-ci.org/gajus/babel-plugin-react-css-modules)
[](https://www.npmjs.org/package/babel-plugin-react-css-modules)
[](https://github.com/gajus/canonical)
[](https://gitter.im/babel-plugin-react-css-modules/Lobby)
[](https://twitter.com/kuizinas)
+> # Looking for maintainers
+>
+> This project is not actively maintained by the original author. However, I am happy to nominate new maintainers.
+> If you wish to contribute to `babel-plugin-react-css-modules`, please begin by raising PRs that fix existing issues.
+> PRs must pass CI/CD tests, include tests (if they change behavior or fix a bug), and include documentation.
+
Transforms `styleName` to `className` using compile time [CSS module](#css-modules) resolution.
@@ -163,7 +168,7 @@ NODE_ENV=production ./test
## How does it work?
1. Builds index of all stylesheet imports per file (imports of files with `.css` or `.scss` extension).
-1. Uses [postcss](https://github.com/postcss/postcss) to parse the matching CSS files.
+1. Uses [postcss](https://github.com/postcss/postcss) to parse the matching CSS files into a lookup of CSS module references.
1. Iterates through all [JSX](https://facebook.github.io/react/docs/jsx-in-depth.html) element declarations.
1. Parses the `styleName` attribute value into anonymous and named CSS module references.
1. Finds the CSS class name matching the CSS module reference:
@@ -194,7 +199,7 @@ Configure the options for the plugin within your `.babelrc` as follows:
|`context`|`string`|Must match webpack [`context`](https://webpack.js.org/configuration/entry-context/#context) configuration. [`css-loader`](https://github.com/webpack/css-loader) inherits `context` values from webpack. Other CSS module implementations might use different context resolution logic.|`process.cwd()`|
|`exclude`|`string`|A RegExp that will exclude otherwise included files e.g., to exclude all styles from node_modules `exclude: 'node_modules'`|
|`filetypes`|`?FiletypesConfigurationType`|Configure [postcss syntax loaders](https://github.com/postcss/postcss#syntaxes) like sugarss, LESS and SCSS and extra plugins for them. ||
-|`generateScopedName`|`?GenerateScopedNameConfigurationType`|Refer to [Generating scoped names](https://github.com/css-modules/postcss-modules#generating-scoped-names). If you use this option, make sure it matches the value of `localIdentName` in webpack config. See this [issue](https://github.com/gajus/babel-plugin-react-css-modules/issues/108#issuecomment-334351241) |`[path]___[name]__[local]___[hash:base64:5]`|
+|`generateScopedName`|`?GenerateScopedNameConfigurationType`|Refer to [Generating scoped names](https://github.com/css-modules/postcss-modules#generating-scoped-names). If you use this option, make sure it matches the value of `localIdentName` [in webpack config](https://webpack.js.org/loaders/css-loader/#localidentname). See this [issue](https://github.com/gajus/babel-plugin-react-css-modules/issues/108#issuecomment-334351241) |`[path]___[name]__[local]___[hash:base64:5]`|
|`removeImport`|`boolean`|Remove the matching style import. This option is used to enable server-side rendering.|`false`|
|`webpackHotModuleReloading`|`boolean`|Enables hot reloading of CSS in webpack|`false`|
|`handleMissingStyleName`|`"throw"`, `"warn"`, `"ignore"`|Determines what should be done for undefined CSS modules (using a `styleName` for which there is no CSS module defined). Setting this option to `"ignore"` is equivalent to setting `errorWhenNotFound: false` in [react-css-modules](https://github.com/gajus/react-css-modules#errorwhennotfound). |`"throw"`|
@@ -239,7 +244,7 @@ To add support for different CSS syntaxes (e.g. SCSS), perform the following two
npm install postcss-scss --save-dev
```
-2. Add a filetype syntax mapping to the Babel plugin configuration
+2. Add a `filetypes` syntax mapping to the Babel plugin configuration. For example for SCSS:
```json
"filetypes": {
@@ -249,7 +254,7 @@ To add support for different CSS syntaxes (e.g. SCSS), perform the following two
}
```
- And optionaly specify extra plugins
+ And optionally specify extra plugins:
```json
"filetypes": {
@@ -262,7 +267,9 @@ To add support for different CSS syntaxes (e.g. SCSS), perform the following two
}
```
- Postcss plugins can have options specified by wrapping the name and an options object in an array inside your config
+ > NOTE: [`postcss-nested`](https://github.com/postcss/postcss-nested) is added as an extra plugin for demonstration purposes only. It's not needed with [`postcss-scss`](https://github.com/postcss/postcss-scss) because SCSS already supports nesting.
+
+ Postcss plugins can have options specified by wrapping the name and an options object in an array inside your config:
```json
"plugins": [
@@ -490,3 +497,32 @@ To enable live reloading of the CSS:
> Note:
>
> This is a [webpack](https://webpack.github.io/) specific option. If you are using `babel-plugin-react-css-modules` in a different setup and require CSS live reloading, raise an issue describing your setup.
+
+### I get a "Cannot use styleName attribute for style name '`[X]`' without importing at least one stylesheet." error
+
+First, ensure that you are correctly importing the CSS file following the [conventions](#conventions).
+
+If you are correctly importing but using different CSS (such as SCSS), this is likely happening because your CSS file wasn't able to be successfully parsed. You need to [configure a syntax loader](#configurate-syntax-loaders).
+
+### I get a "Could not resolve the styleName '`[X]`' error but the class exists in the CSS included in the browser.
+
+First, verify that the CSS is being included in the browser. Remove from `styleName` the reference to the CSS class that's failing and view the page. Search through the `