Updates Documentation Links

README.md

@@ -1,34 +1,34 @@
 # Huron: A Prototype Build System
 
-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.
+Huron is a one-stop shop for generating both in-browser style guides and in-browser prototypes. Huron integrates with [Webpack][webpack_home] to provide a CLI that processes Knyle Style Sheets [(KSS)][kss_home] documentation into style guides and prototypes. Huron's use of Webpack's Hot Module Reloading [HMR][webpack_hmr] system provides a quick and seamless development experience.
 
 ## Get started example
-For a bare-bones demo, [see this example repository](https://github.com/alleyinteractive/huron-examples).
+For a bare-bones demo, [see this example repository][huron_examples].
 
 ## Installation
-Huron can be installed via [NPM](https://www.npmjs.com/package/huron).
+Huron can be installed via [NPM][npm_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](src/default-config/README.md) documentation.
+Once installed, you'll need to write a configuration. The default settings and how to modify them is documented in the [configuration][configuration_docs] 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:8080/dist/[prototype-name].html`, in which port 8080 and `dist` are the default settings for `port` and `root` respectively. You can find the defaults for all huron options and how to change them in the [configuration](src/default-config/README.md) documentation.
+Once the CLI has started, you can access your prototype(s) at `localhost:8080/dist/[prototype-name].html`, in which port 8080 and `dist` are the default settings for `port` and `root` respectively. You can find the defaults for all huron options and how to change them in the [configuration][configuration_docs] 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](src/default-config/README.md) file.
+The files will be accessible through whatever folder you specified as your huron root in the [configuration][configuration_docs] 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:
+KSS is a documentation syntax and styleguide generator. All documentation should be located in your stylesheets, and should largely follow the regular [KSS syntax][kss_syntax]. However, Huron uses [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:
 * **Title** - This is the first line of your KSS comment block
 * **Description** - This starts on the second line of your KSS comment block (may be multiple lines), and will be exported to a separate file by Huron after running through a markdown compiler. As is probably obvious, this means you may use markdown your KSS descriptions
 * **Modifiers** - These are different variations of your component. Modifiers are used _exclusively_ in the Huron styleguide helper tags, and are not required to render a variant of a template in your prototypes (we'll get into that later). So for example, you could include a 'with-images' variant of your component markup, but not include it in the KSS modifiers block. This would allow you to still use that variant in your prototypes, but would not show up in the styleguide.
@@ -65,29 +65,49 @@ 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 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 readme](src/default-config/README.md). 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][html_webpack_plugin]. Configuration of each prototype is discussed in the [config readme][configuration_docs]. 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`.
  	* `[data-huron-type]` - This attribute roughly corresponds to the KSS field you want to insert. There are several options for this:
  		* `template` - This is the type you'll use most frequently, and will insert anything in your KSS `markup` field.
  		* `description` - Type to insert the KSS description field
  		* `prototype` - This is mostly used by the HTML webpack plugin to insert your prototype content, but you can use it as well if necessary.
- 		* `section` - Insert the entire KSS section using the `templates/section.hbs` template. More on this template is located in the [templates readme](templates/README.md).
+ 		* `section` - Insert the entire KSS section using the `templates/section.hbs` template. More on this template is located in the [templates readme][template_docs].
  	* `[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).
+ * A separate HTML document is automatically built for each of your configured prototypes using the HTML webpack plugin and a custom [Handlebars template][hbs_template]. More information on this can be found in the [templates readme][template_docs].
 
 ## Using CSS Modules
-If you're using CSS modules in your production site, it makes sense to also use it when developing in-browser prototypes. Huron supports usage of certain CSS modules implementations (specifically any that is capable of producing JSON output containing localized classes). All that's needed in order to configure this is the `classNames` configuration property, more details for which are in the [configuration docs](src/default-config/README.md). Once you have that set up, all classes will be be provided to every template. These classes are available on a `classNames` object, under which all classes are nested and organized by filename. For example, if your build produces two JSON files for localized classes called `article.json` and `home.json`, you can access those classes in your huron templates via `classNames.article[className]` and `classNames.home[className]` respectively.
+If you're using CSS modules in your production site, it makes sense to also use it when developing in-browser prototypes. Huron supports usage of certain CSS modules implementations (specifically any that is capable of producing JSON output containing localized classes). All that's needed in order to configure this is the `classNames` configuration property, more details for which are in the [configuration docs][configuration_docs]. Once you have that set up, all classes will be be provided to every template. These classes are available on a `classNames` object, under which all classes are nested and organized by filename. For example, if your build produces two JSON files for localized classes called `article.json` and `home.json`, you can access those classes in your huron templates via `classNames.article[className]` and `classNames.home[className]` respectively.
 
-A sample of how to set this up can be found in the [`huron-examples` repo](https://github.com/alleyinteractive/huron-examples)
+A sample of how to set this up can be found in the [`huron-examples` repo][huron_examples]
 
 ## 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](src/default-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.
+* [Configuration][configuration_docs] - Configuration for Huron and for your local webpack setup
+* [Templates][template_docs] - Peripheral template documentation
+* [CLI][cli_docs] - General information on the Huron CLI. Source code is further documented via jsdoc
+* [Web][web_docs] - General information on browser script for inserting/replacing markup. Source code is further documented via jsdoc
+* [Dist][dist_docs] - General information on the distribution (build) directory.
+
+<!-- External links -->
+[webpack_home]: https://webpack.js.org/
+[webpack_hmr]: https://webpack.js.org/concepts/hot-module-replacement/
+[kss_home]: http://warpspire.com/kss/
+[kss_syntax]: http://warpspire.com/kss/syntax/
+[kss_node]: https://github.com/kss-node/kss-node
+[html_webpack_plugin]: https://github.com/ampedandwired/html-webpack-plugin
+
+<!-- Huron links -->
+[npm_huron]: https://www.npmjs.com/package/huron
+[huron_examples]: https://github.com/alleyinteractive/huron-examples/
+
+<!-- Docs -->
+[configuration_docs]: src/defaultConfig/README.md
+[template_docs]: templates/README.md
+[hbs_template]: templates/prototypeTemplate.hbs
+[cli_docs]: src/cli/README.md
+[web_docs]: src/web/README.md
+[dist_docs]: dist/README.md

src/cli/README.md

@@ -2,9 +2,12 @@
 
 Huron's CLI is extremely simple and only requires two flags.
 * `--config` a flag to point Huron to your webpack config, which also contains a configuration for Huron itself
-* `--production` a flag to tell Huron whether or not you're building for production. By default (without this flag set), Huron will build and server your assets via HMR and [webpack-dev-server](https://webpack.github.io/docs/webpack-dev-server.html).
+* `--production` a flag to tell Huron whether or not you're building for production. By default (without this flag set), Huron will build and server your assets via HMR and [webpack-dev-server][webpack_dev_server].
 * You may also run `huron help` to see documentation on each CLI flag
 
 Example build command: `node huron/dist/cli/huron-cli.js --config 'client/config/webpack.config.js' --production`. 
 
-The source code for this CLI is documented via jsdoc. Run `npm install` inside the Huron directory and then run `npm run doc`. Documentation index page will be located at `source-docs/index.html`.
+The source code for this CLI is documented via jsdoc. Run `npm install` inside the Huron directory and then run `npm run doc`. Documentation index page will be located at `source-docs/index.html`.
+
+<!-- External links -->
+[webpack_dev_server]: https://webpack.js.org/guides/development/#using-webpack-dev-server