Merge pull request #816 from jfroom/docs-preprocessors

docs(config): preprocessor transformation clarification

docs/config/01-configuration-file.md

@@ -213,6 +213,8 @@ Preprocessors can be loaded through [plugins].
 Please note just about all preprocessors in Karma (other than CoffeeScript and some other defaults)
 require an additional library to be installed (via NPM).
 
+Be aware that preprocessors may be transforming the files and file types that are available at run time.
+
 Click <a href="preprocessors.html">here</a> for more information.
 
 

docs/config/02-files.md

@@ -39,6 +39,8 @@ Each pattern is either a simple string or an object with four properties:
 * **Default.** `true`
 * **Description.** Should the files be served by Karma's webserver?
 
+## Preprocessor tranformations
+Depending on preprocessor configuration, be aware that files loaded may be transformed and no longer available in their native format. For instance, if html2js preprocessor is enabled, the actual .html files are no longer served - but rather available as `window.__html__['my.html']`. Read more about [preprocessors].
 
 ## Complete example
 Here is a complete example showing the different options that are possible.
@@ -50,6 +52,7 @@ files: [
   'test/unit/*.spec.js',
 
   // this file gets served but will be ignored by the watcher
+  // note if html2js preprocessor is active, reference as `window.__html__['compiled/index.html']`
   {pattern: 'compiled/index.html', watched: false},
 
   // this file only gets watched but otherwise ignored
@@ -58,3 +61,4 @@ files: [
 ```
 
 [glob]: https://github.com/isaacs/node-glob
+[preprocessors]: 04-preprocessors.html

docs/config/04-preprocessors.md

@@ -15,6 +15,8 @@ Note: Most of the preprocessors needs to be loaded as [plugins].
 These preprocessors/plugins are shipped with Karma by default:
 - [coffee]
 - [html2js]
+  - Note any .html files listed in the files section must be referenced at run time as `window.__html__['template.html']`. [Learn more](html2js).
+  - If this preprocessor is disabled, included .html files will need `base/` added to beginning of their path reference. See [discussion in issue 788][issue788].
 
 Additional preprocessors can be loaded through [plugins], such as:
 - [coverage]
@@ -94,3 +96,4 @@ return `false` and the preprocessor would not be executed on the CoffeeScript fi
 [ember]: https://github.com/karma-runner/karma-ember-preprocessor
 [custom plugins]: ../dev/plugins.html
 [plugins]: plugins.html
+[issue788]: https://github.com/karma-runner/karma/issues/788