Handle legacy content and empty pages

guides/legacy/asset-compilation.md → guides/advanced-use/asset-compilation.md

@@ -1,19 +1,22 @@
-<!-- Unedited copy of asset-compilation -->
+<!-- Cover very very basic Broccoli info. Link to Oli's tutorials. See the Ember Times Readers questions for a great writeup of what broccoli is -->
 
-### Raw Assets
+When working on an Ember app, sometimes you may want to customize how certain kinds of assets are handled. This is referred to as "asset compilation."
 
-* `public/assets` vs `app/styles`
+For information on stylesheets, please see the dedicated section, [Stylesheet compilation](../stylesheets/)
 
-To add images, fonts, or other assets, place them in the `public/assets` directory. For
-example, if you place `logo.png` in `public/assets/images`, you can reference it in
+## Raw Assets
+
+To include images, fonts, or other assets, place them in the `public/assets` directory.
+
+For example, if you place `logo.png` in `public/assets/images`, you can reference it in
 templates with `assets/images/logo.png` or in stylesheets with
 `url('/assets/images/logo.png')`.
 
 This functionality of Ember CLI comes from
 [broccoli-asset-rev](https://github.com/rickharrison/broccoli-asset-rev). Be
 sure to check out all the options and usage notes.
 
-### JS Transpiling
+## JS Transpiling
 
 Ember CLI automatically transpiles future JavaScript (ES6/ES2015, ES2016 and beyond) into standard ES5
 JavaScript that runs on every browser using [Babel JS](https://babeljs.io) with the [Ember CLI Babel](https://github.com/babel/ember-cli-babel) addon.
@@ -23,7 +26,7 @@ need to be transpiled to ES5 by **analyzing your project's browser support targe
 that maps to a [browserlist](https://github.com/ai/browserslist) support rule. These are defined in your
 `config/targets.js` file, which [Ember CLI generates](https://github.com/ember-cli/ember-cli/blob/master/blueprints/app/files/config/targets.js) like so:
 
-```js
+```javascript
 /* eslint-env node */
 module.exports = {
   browsers: [
@@ -43,7 +46,7 @@ simply set any of the options found [here](https://github.com/babel/babel-preset
 For example, if you wanted to explicitly exclude generator function transpilation from your
 output, your configuration would look like this:
 
-```js
+```javascript
 // ember-cli-build.js
 
 /* eslint-env node */
@@ -72,18 +75,16 @@ module.exports = function(defaults) {
 
 As of Version 2.13, Ember CLI uses Babel 6.X for transpilation. Ember CLI versions prior to 2.13 use Babel Babel 5.X, and you can check its documentation for a comprehensive list of [all available transformations](https://github.com/babel/babel.github.io/blob/5.0.0/docs/usage/transformers/index.md) and [options](https://github.com/babel/babel.github.io/blob/5.0.0/docs/usage/options.md).
 
-
-
-### Source Maps
+## Source Maps
 
 Ember CLI supports producing source maps for your concatenated and minified JS source files.
 
 Source maps are configured by the EmberApp `sourcemaps` option, and
-are disabled in production by default. Pass `sourcemaps: {enabled: true}` to your EmberApp constructor to enable source maps for javascript. Use the `extensions` option to add other formats, such as coffeescript and CSS: `{extensions: ['js', 'css', 'coffee']}`. JS is supported out-of-the-box. CSS is not currently supported. For other source formats (Sass, Coffee, etc) refer to their addons.
+are disabled in production by default. Pass `sourcemaps: {enabled: true}` to your EmberApp constructor to enable source maps for JavaScript. Use the `extensions` option to add other formats, such as CSS: `{extensions: ['js', 'css']}`. JS is supported out-of-the-box. CSS is not currently supported. For other source formats, refer to their addons.
 
-Default ember-cli-build.js:
+Default `ember-cli-build.js`:
 
-```js
+```javascript
 const EmberApp = require('ember-cli/lib/broccoli/ember-app');
 
 module.exports = function(defaults) {
@@ -99,52 +100,68 @@ module.exports = function(defaults) {
 };
 ```
 
+## Minifying
 
-### CoffeeScript
+Compiled css-files are minified by `broccoli-clean-css` or `broccoli-csso`,
+if it is installed locally. You can pass minifer-specific options to them using
+the `minifyCSS:options` object in your ember-cli-build. Minification is enabled by
+default in the production-env and can be disabled using the `minifyCSS:enabled`
+switch.
 
-To enable [CoffeeScript](http://coffeescript.org/), you must
-first add [ember-cli-coffeescript](https://github.com/kimroen/ember-cli-coffeescript) to your
-NPM modules:
+Similarly, the js-files are minified with `broccoli-uglify-js` in the
+production-env by default. You can pass custom options to the minifier via the
+`minifyJS:options` object in your ember-cli-build. To enable or disable JS minification
+you may supply a boolean value for `minifyJS:enabled`.
 
-```bash
-ember install ember-cli-coffeescript
-```
+For example, to disable minifying of CSS and JS, add in `ember-cli-build.js`:
 
-The modified `package.json` should be checked into source control. CoffeeScript
-can be used in your app's source and in tests, just use the `.coffee` extension
-on any file. We recommend using version >= 1.16.0 of ember-cli-coffeescript to avoid the need
-to escape `import` and `export` statements.
+```js
+// ember-cli-build.js
+const EmberApp = require('ember-cli/lib/broccoli/ember-app');
 
-Note that earlier versions of the transpiler had explicit support for
-CoffeeScript, but that support has been removed.
+module.exports = function(defaults) {
+  let app = new EmberApp(defaults, {
+    minifyJS: {
+      enabled: false
+    },
+    minifyCSS: {
+      enabled: false
+    }
+  });
 
-### EmberScript
+  //...
+  return app.toTree();
+};
+```
 
-To enable [EmberScript](http://emberscript.com), you must
-first add [broccoli-ember-script](https://github.com/aradabaugh/broccoli-ember-script) to your
-NPM modules:
+### Exclude from minification
 
-```bash
-npm install broccoli-ember-script --save-dev
-```
+Some files should be excluded from minification, such as copied-and-pasted third party scripts that are already minified.
 
-Note that the ES6 module transpiler is not directly supported with Emberscript,
-to allow use of ES6 modules use the `` ` `` character to escape raw Javascript
-similar to the CoffeeScript example above.
+To exclude assets from `dist/assets` from being minified, one can pass options for
+[broccoli-uglify-sourcemap](https://github.com/ef4/broccoli-uglify-sourcemap) like so:
 
-### Emblem
+```js
+// ember-cli-build.js
+const EmberApp = require('ember-cli/lib/broccoli/ember-app');
 
-For [Emblem](http://emblemjs.com/), run the following commands:
+module.exports = function(defaults) {
+  let app = new EmberApp(defaults, {
+    minifyJS: {
+      options: {
+        exclude: ["**/vendor.js"]
+      }
+    }
+  });
 
-```bash
-ember install ember-cli-emblem
+  //...
+  return app.toTree();
+};
 ```
 
-If you're using the older broccoli-emblem-compiler addon, you need to switch to
-ember-cli-emblem. The older broccoli-emblem-compiler compiles directly to JS
-instead of Handlebars and therefore is broken on all newer version of HTMLBars.
+This would exclude the resulting `vendor.js` file from being minified.
 
-### Fingerprinting and CDN URLs
+## Fingerprinting and CDN URLs
 
 Fingerprinting is done using the addon
 [broccoli-asset-rev](https://github.com/rickharrison/broccoli-asset-rev)
@@ -176,7 +193,7 @@ of the md5. Pass `null` to suppress the hash, which can be useful when using `pr
 As an example, this `ember-cli-build` will exclude any file in the fonts/169929
 directory as well as add a cloudfront domain to each fingerprinted asset.
 
-```js
+```javascript
 // ember-cli-build.js
 const EmberApp = require('ember-cli/lib/broccoli/ember-app');
 
@@ -209,7 +226,7 @@ background: url('https://subdomain.cloudfront.net/images/foo-735d6c098496507e26b
 
 You can disable fingerprinting in your `ember-cli-build.js`:
 
-```js
+```javascript
 // ember-cli-build.js
 const EmberApp = require('ember-cli/lib/broccoli/ember-app');
 
@@ -228,22 +245,22 @@ module.exports = function(defaults) {
 Or remove the entry from your `EmberApp` and  `broccoli-asset-rev`
 from your `package.json`.
 
-### Application Configuration
+## Application Configuration
 
 Application configurations from your `ember-cli-build.js` file will be stored inside a
 special meta tag in `dist/index.html`.
 
 sample meta tag:
 
-```js
+```javascript
 <meta name="user/config/environment" content="%7B%22modulePre.your.config">
 ```
 
 This meta tag is required for your ember application to function properly.
 If you prefer to have this tag be part of your compiled javascript files
 instead, you may use the `storeConfigInMeta` flag in `ember-cli-build.js`.
 
-```js
+```javascript
 // ember-cli-build.js
 const EmberApp = require('ember-cli/lib/broccoli/ember-app');
 
@@ -257,7 +274,7 @@ module.exports = function(defaults) {
 };
 ```
 
-#### Configuring output paths
+### Configuring output paths
 
 The compiled files are output to the following paths:
 
@@ -298,7 +315,7 @@ The compiled files are output to the following paths:
 
 To change these paths, specify the `outputPaths` config option in `ember-cli-build.js`. The default setting is shown here:
 
-```js
+```javascript
 // ember-cli-build.js
 const EmberApp = require('ember-cli/lib/broccoli/ember-app');
 
@@ -328,7 +345,7 @@ You may edit any of these output paths, but make sure to update the paths specif
 `app.outputPaths.app.html` default it is `index.html`, and `tests/index.html`. If this is not done,
 your app will not be served with correct asset names.
 
-```js
+```javascript
 // ember-cli-build.js
 const EmberApp = require('ember-cli/lib/broccoli/ember-app');
 
@@ -354,7 +371,7 @@ different extension.
 When using CSS preprocessing, only the `app/styles/app.scss` (or `.less` etc)
 is compiled. If you need to process multiple files, you must add another key:
 
-```js
+```javascript
 // ember-cli-build.js
 const EmberApp = require('ember-cli/lib/broccoli/ember-app');
 
@@ -375,13 +392,13 @@ module.exports = function(defaults) {
 };
 ```
 
-#### Integration
+## Integration
 
 When using Ember inside another project, you may want to launch Ember only when
 a specific route is accessed. If you're preloading the Ember javascript before
 you access the route, you have to disable `autoRun`:
 
-```js
+```javascript
 // ember-cli-build.js
 const EmberApp = require('ember-cli/lib/broccoli/ember-app');
 
@@ -398,7 +415,7 @@ module.exports = function(defaults) {
 To manually run Ember:
 `require("app-name/app")["default"].create({/* app settings */});`
 
-#### Subresource integrity
+## Subresource integrity
 
 SRI calculation is done using the addon
 [ember-cli-sri](https://github.com/jonathanKingston/ember-cli-sri)
@@ -409,7 +426,7 @@ your applications. Subresource integrity is a security concept used to check
 JavaScript and stylesheets are loaded with the correct content when using a
 CDN.
 
-#### Why
+### Why
 
 The reason to add this to your application is to protect against poisoned CDNs
 breaking JavaScript or CSS.
@@ -420,6 +437,6 @@ breaking JavaScript or CSS.
   - The latest [GitHub DDoS attack](http://googleonlinesecurity.blogspot.co.uk/2015/04/a-javascript-based-ddos-attack-as-seen.html)
 - Protection against corrupted code on less trusted servers
 
-#### Customize
+### Customize
 
 To customize SRI generation see: [ember-cli-sri](https://github.com/jonathanKingston/ember-cli-sri)

guides/advanced-use/file-layout.md

@@ -1 +1,3 @@
 <!-- A place to talk about the resolver (see ember-cli.com), module imports, and eventually, Module Unification when it becomes a thing -->
+
+<!-- This page is not included in the table of contents and therefore not part of the build yet -->