CoffeeScript 2
-What’s New In CoffeeScript 2?
+
+
+ What’s New In CoffeeScript 2?
The biggest change in CoffeeScript 2 is that now the CoffeeScript compiler produces modern JavaScript syntax (ES6, or ES2015 and later). A CoffeeScript => becomes a JS =>, a CoffeeScript class becomes a JS class and so on. Major new features in CoffeeScript 2 include async functions and JSX. You can read more in the changelog.
There are very few breaking changes from CoffeeScript 1.x to 2; we hope the upgrade process is smooth for most projects.
-Why CoffeeScript When There’s ES6?
+
+
+
+ Why CoffeeScript When There’s ES6?
CoffeeScript introduced many new features to the JavaScript world, such as => and destructuring and classes. We are happy that ECMA has seen their utility and adopted them into ECMAScript.
CoffeeScript’s intent, however, was never to be a superset of JavaScript. One of the guiding principles of CoffeeScript has been simplicity: not just removing JavaScript’s “bad parts,” but providing an elegant, concise syntax that eschews unnecessary punctuation whenever possible, to make code easier to read and reason about. This benefit of CoffeeScript remains, even in an ES2015+ world.
-
-
- Compatibility
-With the exception of modules (import and export statements) and JSX, all the modern JavaScript features that CoffeeScript supports can run natively in Node 7.6+, meaning that Node can run CoffeeScript’s output without any further processing required. You can run the tests in your browser to see if your browser can do the same. For older browsers or older versions of Node, transpilation is required.
+
+
+ Compatibility
+With the exception of modules (import and export statements) and JSX, all the modern JavaScript features that CoffeeScript supports can run natively in Node 7.6+, meaning that Node can run CoffeeScript’s output without any further processing required. You can run the tests in your browser to see if your browser can do the same. For older browsers or older versions of Node, however, transpilation is required.
Support for modern JavaScript syntax is important to ensure compatibility with frameworks that assume modern features. Now that CoffeeScript compiles classes to the class keyword, it’s possible to extend a JavaScript class; that wasn’t possible in CoffeeScript 1. Parity in how language features work is also important on its own; CoffeeScript “is just JavaScript,” and so things like function parameter default values should behave the same in CoffeeScript as in JavaScript. Some such features behave slightly differently in JavaScript than they did in CoffeeScript 1; in such cases we are conforming with the JavaScript spec, and we’ve documented the differences as breaking changes.
+
Transpilation
-CoffeeScript 2 generates JavaScript that uses the latest, modern syntax (a.k.a. ES6, or ES2015, or ES2016 or ES2017 etc.). In general, CoffeeScript 2’s output is supported as is by Node.js 7.6+, except for modules and JSX. Evergreen browsers such as the latest versions of Chrome and Safari have similar robust support. But if you want to support older browsers, or if you want to use modules or JSX, you must transpile CoffeeScript’s output.
+CoffeeScript 2 generates JavaScript that uses the latest, modern syntax. Your runtime might not support all of that syntax. If so, you need to transpile the JavaScript. To make things a little easier, CoffeeScript has built-in support for the popular Babel transpiler.
+Quickstart
+From the root of your project:
+npm install --save-dev babel-core babel-preset-env
+echo '{ "presets": ["env"] }' > .babelrc
+coffee --compile --transpile --inline-map some-file.coffee
+
+
About Transpilation
Transpilation is the conversion of source code into equivalent but different source code. In our case, we want to convert modern JavaScript into older JavaScript that will run in older versions of Node or older browsers; for example, { a } = obj into a = obj.a. This is done via transpilers like Babel, Bublé or Traceur Compiler.
CoffeeScript includes a --transpile option when used via the coffee command, or a transpile option when used via Node. To use either, Babel must be installed in your project:
npm install --save-dev babel-core
@@ -967,12 +984,8 @@ eval CoffeeScript.compile 'console.log "Mmmmm, I could real
See Babel’s website to learn about presets and plugins and the multitude of options you have.
Simply installing babel-preset-env isn’t enough. You also need to define the configuration options that you want Babel to use. You can do this by creating a .babelrc file in the folder containing the files you’re compiling, or in any parent folder up the path above those files. So if your project is in ~/app and your files are in ~/app/src, you can put .babelrc in either ~/app or in ~/app/src. You can also define the Babel options via a babel key in the package.json file for your project. A minimal .babelrc file (or package.json babel key) for use with babel-preset-env would be just { "presets": ["env"] }.
-So to put it all together, from the root of your project:
-npm install --save-dev babel-core babel-preset-env
-echo '{ "presets": ["env"] }' > .babelrc
-
-
And then you can use coffee --transpile and it will pipe CoffeeScript’s output through Babel using the options in this .babelrc file.
-If you’re using CoffeeScript via the Node API, where you call CoffeeScript.compile with a string to be compiled and an options object, the transpile key of the options object should be the Babel options:
+Once you have babel-core and babel-preset-env (or other presets or plugins) installed, and a .babelrc file (or package.json babel key) in place, you can use coffee --transpile to pipe CoffeeScript’s output through Babel using the options you’ve saved.
+If you’re using CoffeeScript via the Node API, where you call CoffeeScript.compile with a string to be compiled and an options object, the transpile key of the options object should be the Babel options:
CoffeeScript.compile(code, {transpile: {presets: ['env']}})
You can also transpile CoffeeScript’s output without using the transpile option, for example as part of a build chain. This lets you use transpilers other than Babel, and it gives you greater control over the process. There are many great task runners for setting up JavaScript build chains, such as Gulp, Webpack, Grunt and Broccoli.
diff --git a/documentation/sections/coffeescript_2.md b/documentation/sections/coffeescript_2.md
index 72b66b07..28246a3c 100644
--- a/documentation/sections/coffeescript_2.md
+++ b/documentation/sections/coffeescript_2.md
@@ -1,13 +1 @@
## CoffeeScript 2
-
-### What’s New In CoffeeScript 2?
-
-The biggest change in CoffeeScript 2 is that now the CoffeeScript compiler produces modern JavaScript syntax (ES6, or ES2015 and later). A CoffeeScript `=>` becomes a JS `=>`, a CoffeeScript `class` becomes a JS `class` and so on. Major new features in CoffeeScript 2 include [async functions](#async-functions) and [JSX](#jsx). You can read more in the [changelog](#changelog).
-
-There are very few [breaking changes from CoffeeScript 1.x to 2](#breaking-changes); we hope the upgrade process is smooth for most projects.
-
-### Why CoffeeScript When There’s ES6?
-
-CoffeeScript introduced many new features to the JavaScript world, such as [`=>`](#fat-arrow) and [destructuring](#destructuring) and [classes](#classes). We are happy that ECMA has seen their utility and adopted them into ECMAScript.
-
-CoffeeScript’s intent, however, was never to be a superset of JavaScript. One of the guiding principles of CoffeeScript has been _simplicity:_ not just removing JavaScript’s “bad parts,” but providing an elegant, concise syntax that eschews unnecessary punctuation whenever possible, to make code easier to read and reason about. This benefit of CoffeeScript remains, even in an ES2015+ world.
diff --git a/documentation/sections/compatibility.md b/documentation/sections/compatibility.md
index d1532cba..a6201f6c 100644
--- a/documentation/sections/compatibility.md
+++ b/documentation/sections/compatibility.md
@@ -1,5 +1,5 @@
-## Compatibility
+### Compatibility
-With the exception of [modules](#modules) (`import` and `export` statements) and [JSX](#jsx), all the modern JavaScript features that CoffeeScript supports can run natively in Node 7.6+, meaning that Node can run CoffeeScript’s output without any further processing required. You can [run the tests in your browser](http://coffeescript.org/v<%= majorVersion %>/test.html) to see if your browser can do the same. For older browsers or older versions of Node, [transpilation](#transpilation) is required.
+With the exception of [modules](#modules) (`import` and `export` statements) and [JSX](#jsx), all the modern JavaScript features that CoffeeScript supports can run natively in Node 7.6+, meaning that Node can run CoffeeScript’s output without any further processing required. You can [run the tests in your browser](http://coffeescript.org/v<%= majorVersion %>/test.html) to see if your browser can do the same. For older browsers or older versions of Node, however, [transpilation](#transpilation) is required.
-Support for modern JavaScript syntax is important to ensure compatibility with frameworks that assume modern features. Now that CoffeeScript compiles classes to the `class` keyword, it’s possible to `extend` a JavaScript class; that wasn’t possible in CoffeeScript 1. Parity in how language features work is also important on its own; CoffeeScript “is just JavaScript,” and so things like [function parameter default values](#breaking-changes-default-values) should behave the same in CoffeeScript as in JavaScript. Some such features behave slightly differently in JavaScript than they did in CoffeeScript 1; in such cases we are conforming with the JavaScript spec, and we’ve documented the differences as [breaking changes](#breaking-changes).
\ No newline at end of file
+Support for modern JavaScript syntax is important to ensure compatibility with frameworks that assume modern features. Now that CoffeeScript compiles classes to the `class` keyword, it’s possible to `extend` a JavaScript class; that wasn’t possible in CoffeeScript 1. Parity in how language features work is also important on its own; CoffeeScript “is just JavaScript,” and so things like [function parameter default values](#breaking-changes-default-values) should behave the same in CoffeeScript as in JavaScript. Some such features behave slightly differently in JavaScript than they did in CoffeeScript 1; in such cases we are conforming with the JavaScript spec, and we’ve documented the differences as [breaking changes](#breaking-changes).
diff --git a/documentation/sections/transpilation.md b/documentation/sections/transpilation.md
index 7f43b716..29446a9c 100644
--- a/documentation/sections/transpilation.md
+++ b/documentation/sections/transpilation.md
@@ -1,6 +1,18 @@
### Transpilation
-CoffeeScript 2 generates JavaScript that uses the latest, modern syntax (a.k.a. ES6, or ES2015, or ES2016 or ES2017 etc.). In general, [CoffeeScript 2’s output is supported as is by Node.js 7.6+](http://node.green/), except for [modules](#modules) and [JSX](#jsx). Evergreen browsers such as the latest versions of Chrome and Safari have similar robust support. But if you want to support older browsers, or if you want to use modules or JSX, you must transpile CoffeeScript’s output.
+CoffeeScript 2 generates JavaScript that uses the latest, modern syntax. Your runtime [might not support all of that syntax](#compatibility). If so, you need to _transpile_ the JavaScript. To make things a little easier, CoffeeScript has built-in support for the popular [Babel](http://babeljs.io/) transpiler.
+
+#### Quickstart
+
+From the root of your project:
+
+```bash
+npm install --save-dev babel-core babel-preset-env
+echo '{ "presets": ["env"] }' > .babelrc
+coffee --compile --transpile --inline-map some-file.coffee
+```
+
+#### About Transpilation
Transpilation is the conversion of source code into equivalent but different source code. In our case, we want to convert modern JavaScript into older JavaScript that will run in older versions of Node or older browsers; for example, `{ a } = obj` into `a = obj.a`. This is done via transpilers like [Babel](http://babeljs.io/), [Bublé](https://buble.surge.sh/) or [Traceur Compiler](https://github.com/google/traceur-compiler).
@@ -22,16 +34,9 @@ See [Babel’s website to learn about presets and plugins](https://babeljs.io/do
Simply installing `babel-preset-env` isn’t enough. You also need to define the configuration options that you want Babel to use. You can do this by creating a [`.babelrc` file](https://babeljs.io/docs/usage/babelrc/) in the folder containing the files you’re compiling, or in any parent folder up the path above those files. So if your project is in `~/app` and your files are in `~/app/src`, you can put `.babelrc` in either `~/app` or in `~/app/src`. You can also define the Babel options via a `babel` key in the `package.json` file for your project. A minimal `.babelrc` file (or `package.json` `babel` key) for use with `babel-preset-env` would be just `{ "presets": ["env"] }`.
-So to put it all together, from the root of your project:
+Once you have `babel-core` and `babel-preset-env` (or other presets or plugins) installed, and a `.babelrc` file (or `package.json` `babel` key) in place, you can use `coffee --transpile` to pipe CoffeeScript’s output through Babel using the options you’ve saved.
-```bash
-npm install --save-dev babel-core babel-preset-env
-echo '{ "presets": ["env"] }' > .babelrc
-```
-
-And then you can use `coffee --transpile` and it will pipe CoffeeScript’s output through Babel using the options in this `.babelrc` file.
-
-If you’re using CoffeeScript via the [Node API](nodejs_usage), where you call `CoffeeScript.compile` with a string to be compiled and an options object, the `transpile` key of the `options` object should be the Babel options:
+If you’re using CoffeeScript via the [Node API](nodejs_usage), where you call `CoffeeScript.compile` with a string to be compiled and an `options` object, the `transpile` key of the `options` object should be the Babel options:
```js
CoffeeScript.compile(code, {transpile: {presets: ['env']}})
diff --git a/documentation/sections/whats_new_in_coffeescript_2.md b/documentation/sections/whats_new_in_coffeescript_2.md
new file mode 100644
index 00000000..25e6a94d
--- /dev/null
+++ b/documentation/sections/whats_new_in_coffeescript_2.md
@@ -0,0 +1,5 @@
+### What’s New In CoffeeScript 2?
+
+The biggest change in CoffeeScript 2 is that now the CoffeeScript compiler produces modern JavaScript syntax (ES6, or ES2015 and later). A CoffeeScript `=>` becomes a JS `=>`, a CoffeeScript `class` becomes a JS `class` and so on. Major new features in CoffeeScript 2 include [async functions](#async-functions) and [JSX](#jsx). You can read more in the [changelog](#changelog).
+
+There are very few [breaking changes from CoffeeScript 1.x to 2](#breaking-changes); we hope the upgrade process is smooth for most projects.
diff --git a/documentation/sections/why_coffeescript.md b/documentation/sections/why_coffeescript.md
new file mode 100644
index 00000000..b5de5393
--- /dev/null
+++ b/documentation/sections/why_coffeescript.md
@@ -0,0 +1,5 @@
+### Why CoffeeScript When There’s ES6?
+
+CoffeeScript introduced many new features to the JavaScript world, such as [`=>`](#fat-arrow) and [destructuring](#destructuring) and [classes](#classes). We are happy that ECMA has seen their utility and adopted them into ECMAScript.
+
+CoffeeScript’s intent, however, was never to be a superset of JavaScript. One of the guiding principles of CoffeeScript has been _simplicity:_ not just removing JavaScript’s “bad parts,” but providing an elegant, concise syntax that eschews unnecessary punctuation whenever possible, to make code easier to read and reason about. This benefit of CoffeeScript remains, even in an ES2015+ world.
diff --git a/documentation/v2/body.html b/documentation/v2/body.html
index 39dc4ab5..802c844f 100644
--- a/documentation/v2/body.html
+++ b/documentation/v2/body.html
@@ -17,9 +17,15 @@