From 94e079869ba1359c184a06cedbef0d5e24392933 Mon Sep 17 00:00:00 2001
From: Jon Winton <winton.jon@gmail.com>
Date: Mon, 5 Nov 2018 14:07:46 -0500
Subject: [PATCH] clayconfig docs (#108)

* adding readme docs

* small tweaks

* small tweak
---
 README.md | 43 ++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 42 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 460d2ea..3c9ba29 100644
--- a/README.md
+++ b/README.md
@@ -268,7 +268,7 @@ body:
       must:
         -
           terms:
-            siteSlug: 
+            siteSlug:
               - intelligencer # show only pages for a specific site
         -
           match:
@@ -360,6 +360,8 @@ Compile assets based on standardized Clay conventions. Assets are compiled to a
 
 Specifying `--watch` on `claycli compile` or any of its subcommands will compile assets once, then watch source files (and their dependencies) for changes. Specifying `--minify` (or setting `CLAYCLI_COMPILE_MINIFIED`) will run assets through minification and bundling if applicable. The `CLAYCLI_COMPILE_ASSET_HOST` and `CLAYCLI_COMPILE_ASSET_PATH` variables are used by the `styles` and `fonts` subcommands to generate links to media and font files in the compiled CSS.
 
+A project specific clay config file is also supported, [read more here](https://github.com/clay/claycli#project-specific-config-file).
+
 #### Arguments
 
 * `-w, --watch` enables watching of source files after compilation
@@ -650,6 +652,45 @@ clay compile scripts --minify
 clay compile scripts --globs 'global/js/!(*.test).js'
 ```
 
+### Project Specific Config File
+
+Not all projects are the same, and for project specific compilation changes you can add a `claycli.config.js` file to your project's root. This file must simply export an Object whose contains key/value pairs are read during compilation. Good use cases for this file include:
+
+* Adding PostCSS plugins to [`styles`](https://github.com/clay/claycli#styles) compilation
+* Updating options passed into Autoprefixer
+* Changing Babel browser target to meet your env support requirements
+
+#### Arguments
+
+The `claycli.config.js` file currently supports the following arguments:
+
+* `plugins` (_Array_): list of PostCSS plugins that will be concatenated to the end of the list already supported by the `styles` compilation command
+* `babelTargets` (_String|Array_): the value of this property is passed to the [Babel `targets` option](https://babeljs.io/docs/en/babel-preset-env#targets) to describe the environments your compiled scripts support
+* `autoprefixerOptions` (_Object_): an Object which is [passed directly to `autoprefixer`](https://www.npmjs.com/package/autoprefixer#options) for style and Kiln plugin compilation
+
+#### Example
+
+```js
+'use strict';
+
+module.exports = {
+  plugins: [
+    require('postcss-functions')({
+      functions: {
+        em: function (pixels, browserContext) {
+          var browserContext = parseInt(browserContext, 10) || 16,
+            pixels = parseFloat(pixels);
+
+          return pixels / browserContext + 'em';
+        }
+      }
+    })
+  ],
+  babelTargets: '> 0.25%, not dead',
+  autoprefixerOptions: { browsers: ['last 2 versions', 'ie >= 9', 'ios >= 7', 'android >= 4.4.2'] }
+};
+```
+
 # Programmatic API
 
 The core `claycli` functionality is exposed as an api, allowing you to use it in Node.js. All main commands are properties of the exported `claycli` object.