Merge pull request #77 from alleyinteractive/update-readmes

Updates documentation.

README.md

@@ -1,22 +1,31 @@
-# Huron: A Prototype Build System built by Alley Interactive
+# Huron: A Prototype Build System
 
-Huron is intended as a one-stop shop for generating both an in-browser styleguide and a series of in-browser prototypes. Huron utilizes a custom CLI to process Knyle Style Sheets [(KSS)](http://warpspire.com/kss/) documentation and webpack to build the styleguides and prototypes. In addition, Huron makes heavy use of webpack's Hot Module Reloading [HMR](https://webpack.github.io/docs/hot-module-replacement.html) system to provide a quick and seamless development experience.
+Huron is a one-stop shop for generating both in-browser style guides and in-browser prototypes. Huron integrates with [Webpack](https://webpack.github.io/) to provide a CLI that processes Knyle Style Sheets [(KSS)](http://warpspire.com/kss/) documentation into style guides and prototypes. Huron's use of Webpack's Hot Module Reloading [HMR](https://webpack.github.io/docs/hot-module-replacement.html) system provides a quick and seamless development experience.
 
-## Table of contents
-This file contains basic information on Huron installation and writing prototypes. However, there are several other subsections of this documentation:
-
-* [Configuration](config/README.md) - Configuration for Huron and for your local webpack setup
-* [Templates](templates/README.md) - Peripheral template documentation
-* [CLI](src/cli/README.md) - General information on the Huron CLI. Source code is further documented via jsdoc
-* [Web](src/web/README.md) - General information on browser script for inserting/replacing markup. Source code is further documented via jsdoc
-* [Dist](dist/README.md) - General information on the distribution (build) directory.
+## Get started example
+For a bare-bones demo, [see this example repository](https://github.com/alleyinteractive/huron-examples).
 
 ## Installation
-* Huron can be installed via [NPM](https://www.npmjs.com/package/huron). Add Huron to your `package.json` file.
-* Don't forget to run `npm install` once you're done!
-* Once `npm install` finishes, you'll need to write a configuration or use the default. The default settings and how to modify them is documented in the [configuration](config/README.md) readme.
-* Start the CLI using the `dist/cli/huron-cli.js` file.
-* Once the CLI has started, if you didn't run the CLI with the `--production` flag, you can access your prototype(s) at `localhost:[huron.port]/[huron.root]/[prototype-name].html`. You can find the defaults for the `port` and `root` options and how to change them in the config documentation, but using the defaults this URL would resolve to `localhost:8080/dist/index.html`.
+Huron can be installed via [NPM](https://www.npmjs.com/package/huron).
+```
+npm install huron --save
+```
+
+Once installed, you'll need to write a configuration. The default settings and how to modify them is documented in the [configuration](config/README.md) documentation.
+
+Then, start the CLI with the respective paths to your configs:
+```
+npm run huron -w webpack.config.js -c huron.config.js
+```
+
+Once the CLI has started, you can access your prototype(s) at `localhost:[huron.port]/[huron.root]/[prototype-name].html`. You can find the defaults for the `port` and `root` options and how to change them in the [configuration](config/README.md) documentation.
+
+To build your prototype files for production, run
+```
+npm run huron-build -w webpack.config.js -c huron.config.js
+```
+
+The files will be accessible through whatever folder you specified as your huron root in the [configuration](config/README.md) file.
 
 ## Writing KSS, templates and data
 KSS is a documentation syntax and styleguide generator. All documentation should be located in your stylesheets, and should largely follow the regular [KSS syntax](http://warpspire.com/kss/syntax/). However, Huron uses [kss-node](https://github.com/kss-node/kss-node) which includes some changes, and there are a few differences specific to Huron as well. All your KSS should include the following:
@@ -56,7 +65,7 @@ KSS is a documentation syntax and styleguide generator. All documentation should
  * _NOTE: As of now, Huron only supports one KSS documentation block per file, meaning it's heavily geared toward CSS preprocessors like SASS or LESS. This is an issue on our radar, however, and will be implemented at some point._
 
 ## Writing prototypes
-In Huron, everything is a "prototype" (even a styleguide). Unlike previous versions, you now only have to write the prototype _content_ instead of wrangling all the surrounding HTML document boilerplate as well. This is accomplished via the [HTML webpack plugin](https://github.com/ampedandwired/html-webpack-plugin). Configuration of each prototype is discussed in the [config directory](config/README.md) readme. All you need to know for now is your prototype files should be located in a `prototypes` directory within your SASS/CSS source directory, and should be named in the format `prototype-[prototype name].html`.
+In Huron, everything is a "prototype" (even a style guide). Unlike previous versions, you now only have to write the prototype _content_ instead of wrangling all the surrounding HTML document boilerplate as well. This is accomplished via the [HTML webpack plugin](https://github.com/ampedandwired/html-webpack-plugin). Configuration of each prototype is discussed in the [config directory](config/README.md) readme. All you need to know for now is your prototype files should be located in a `prototypes` directory within your SASS/CSS source directory, and should be named in the format `prototype-[prototype name].html`.
  * You may include any valid HTML markup in your prototype.
  * Huron uses its own custom syntax for inserting templates from your KSS. This is accomplished via three data attributes:
  	* `[data-huron-id]` - The KSS styleguide section reference URI containing the template you want. As described above, to get the reference URI you simply convert any `.` to `-` in the section reference you wrote in the KSS. For example, the section `header.navigation` would be inserted using a `huron-id` of `header-navigation`.
@@ -68,3 +77,12 @@ In Huron, everything is a "prototype" (even a styleguide). Unlike previous versi
  	* `[data-huron-modifier]` - Used to specify a particular top-level data field with which to render your markup. Using the example data above, you could use `data-huron-modifier="type-two"` to use the data fields within the `type-two` property to render and insert your KSS markup.
  * You may attach the Huron data attributes to any tag, but generally we use a generic `<div>`
  * A separate HTML document is automatically built for each of your configured prototypes using the HTML webpack plugin and a custom EJS [template](templates/prototype-template.ejs). More information on this can be found in the [templates readme](templates/README.md).
+
+## For more specific information
+This file contains basic information on Huron installation and writing prototypes. However, there are several other subsections of this documentation:
+
+* [Configuration](config/README.md) - Configuration for Huron and for your local webpack setup
+* [Templates](templates/README.md) - Peripheral template documentation
+* [CLI](src/cli/README.md) - General information on the Huron CLI. Source code is further documented via jsdoc
+* [Web](src/web/README.md) - General information on browser script for inserting/replacing markup. Source code is further documented via jsdoc
+* [Dist](dist/README.md) - General information on the distribution (build) directory.

package.json

@@ -2,7 +2,7 @@
   "name": "huron",
   "description": "An in-browser prototyping tool built on top of webpack and kss-node",
   "author": "Alley Interactive",
-  "version": "2.1.3",
+  "version": "2.1.4",
   "repository": {
     "type": "git",
     "url": "https://github.com/alleyinteractive/huron"