Add documentation

README.md

@@ -6,12 +6,114 @@
 [![Dependencies][david-image]][david-url]
 [![devDependencies][david-dev-image]][david-dev-url]
 
-Documentation forthcoming…
+A [Babel][babel] plugin to process CSS files via [PostCSS][postcss].
+
+Using [PostCSS Modules][postcss-modules], it can transform:
+
+```js
+import styles from './styles';
+```
+
+```css
+.example { color: cyan; }
+```
+
+Into an object that has properties mirroring the style names:
+
+```js
+var styles = {"example":"_example_amfqe_1"};
+```
+
+## Configuration
+
+Install the transform as well as `postcss` and any PostCSS plugins you want to
+use:
+
+```bash
+npm install --save-dev \
+  babel-plugin-transform-postcss \
+  postcss \
+  postcss-modules
+```
+
+Add the trasnform to your babel configuration, i.e. `.babelrc`:
+
+```json
+{
+  "presets": [
+    ["env", { "targets": { "node": "current" }}]
+  ],
+  "plugins": [
+    "transform-postcss",
+  ],
+}
+```
+
+Create a [`postcss.config.js`][postcss-load-config]:
+
+```js
+module.exports = (ctx) => ({
+  plugins: [
+    require('postcss-modules')({
+      getJSON: ctx.extractModules || () => {},
+    }),
+  ],
+});
+```
+
+## Details
+
+The transform will transform all imports & require statements that have a `.css`
+extension and run them through `postcss`. To determine the PostCSS config, it
+uses [`postcss-load-config`][postcss-load-config] with
+[additional context values](#postcss-load-config-context). One of those config
+values, [`extractModules`](#extractmodules_-any-modules-object) should be
+invoked in order to define the value of the resulting import.
+
+No CSS is actually included in the resulting JavaScript. It is expected that you
+transform your CSS using the same `postcss.config.js` file as the one used by
+this transform. We recommend:
+
+- [`postcss-cli`][postcss-cli] (v3 or later)
+- [`gulp-postcsssrc`][gulp-postcssrc]
+
+### PostCSS Load Config Context
+
+#### `extractModules(_: any, modules: object)`
+
+This option is a function that may be passed directly on to
+[`postcss-modules`][postcss-modules] as the [`getJSON`
+argument][postcss-modules-get-json]. Other uses, while unlikely, are
+permittable, as well.
+
+The function accepts two arguments. The transform uses only the
+second value passed to the function. That value is the object value that
+replaces the `import`/`require`.
+
+
+## Prior Art
+
+This plugin is based of the work of:
+
+- [`css-modules-transform`][css-modules-transform]
+- [`css-modules-require-hook`][css-modules-require-hook]
+
+Unlike the above, it supports both synchronous and asynchronous PostCSS plugins.
 
 ## License
 
 This project is distributed under the MIT license.
 
+[babel]: https://babeljs.io/
+[postcss]: http://postcss.org/
+[postcss-cli]: https://github.com/postcss/postcss-cli
+[postcss-modules]: https://github.com/css-modules/postcss-modules
+[postcss-modules-get-json]: https://github.com/css-modules/postcss-modules#saving-exported-classes
+[postcss-load-config]: https://github.com/michael-ciniawsky/postcss-load-config
+[css-modules-transform]: https://github.com/michalkvasnicak/babel-plugin-css-modules-transform
+[css-modules-require-hook]: https://github.com/css-modules/css-modules-require-hook
+[gulp-postcssrc]: https://github.com/michael-ciniawsky/gulp-postcssrc
+
 [travis-image]: http://img.shields.io/travis/wbyoung/babel-plugin-transform-postcss.svg?style=flat
 [travis-url]: http://travis-ci.org/wbyoung/babel-plugin-transform-postcss
 [npm-image]: http://img.shields.io/npm/v/babel-plugin-transform-postcss.svg?style=flat