Updates, and broken up into sections

docs/designers-developers/developers/tutorials/javascript/extending-the-block-editor.md

@@ -0,0 +1,41 @@
+
+## Extending the Block Editor
+
+This puts all the initial pieces in place for you to start extending the Block Editor.
+
+Let's look at using the [Block Style Variation example](../../../../../docs/designers-developers/developers/filters/block-filters/#block-style-variations).
+
+Replace the existing `console.log()` code in your `myguten.js` file with:
+
+```js
+wp.blocks.registerBlockStyle( 'core/quote', {
+    name: 'fancy-quote',
+    label: 'Fancy Quote'
+} );
+```
+
+After you add the `wp.blocks.registerBlockStyle` code, save the `myguten.js` file, and then create a new post in the Block Editor.
+
+Add a quote block, and in the right sidebar under Styles, you will see your new Fancy Quote style listed. You can go back to the JavaScript and change the label to "Fancy Pants" and reload, and you will see the new label.
+
+Previewing or Publishing the post, you will not see a visible change. However, if you look at the source, you will see `is-style-fancy-quote` class name attached to your quote.
+
+Go ahead and create a `style.css` file with:
+
+```css
+.is-style-fancy-quote {
+	font-size: 64px;
+}
+
+```
+
+and enqueue the CSS by adding the following to your `myguten-plugin.php`:
+
+```php
+function myguten_stylesheet() {
+	wp_enqueue_style( 'myguten-style', plugins_url( 'style.css', __FILE__ ) );
+}
+add_action( 'enqueue_block_assets', 'myguten_stylesheet' );
+```
+
+And then when you view the page, you will see it in a very large font.

docs/designers-developers/developers/tutorials/javascript/loading-javascript.md

@@ -0,0 +1,48 @@
+
+## Loading JavaScript
+
+With the plugin in place, you can add the code that loads the JavaScript. This methodology follows the standard WordPress procedure of enqueuing scripts, see [enqueuing section of the Plugin Handbook](https://developer.wordpress.org/plugins/javascript/enqueuing/).
+
+Add the following code to your `myguten-plugin.php` file:
+
+```php
+function myguten_enqueue() {
+	wp_enqueue_script( 'myguten-script',
+		plugins_url( 'myguten.js', __FILE__ ),
+		array( 'wp-blocks', 'wp-element' )
+	);
+}
+add_action( 'enqueue_block_editor_assets', 'myguten_enqueue' );
+```
+
+Create a file called `myguten.js` and add:
+
+```js
+console.log( "I'm loaded!" );
+```
+
+Now start a new post in the block editor, and check your browser Developer Tools. You should see the message in your console log. See [Mozilla's What are browser developer tools?](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/What_are_browser_developer_tools) if you need more information, the area to become most familiar with is [The JavaScript console](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/What_are_browser_developer_tools#The_JavaScript_console).
+
+The script enqueuing uses the `enqueue_block_editor_assets` hook which only loads the JavaScript when the block editor loads. So if you navigate to any front-end page or article on your site, you will not see the message.
+
+The last argument in the `wp_enqueue_script()` function is an array of dependencies. All of the Gutenberg packages are registered and can be loaded by specifying them in the array, the blocks and elements packages are shown above, as they are two common ones used.
+
+
+**Note for Theme Developers:**  The above method of enqueing is used for plugins, if you are extending Gutenberg for your theme there is a minor difference, you will use the `get_template_directory_uri()` function instead of `plugins_url()`. So for a theme, the enqueue example is:
+
+```php
+function myguten_enqueue() {
+	wp_enqueue_script( 'myguten-script',
+		get_template_directory_uri() . '/myguten.js',
+		array( 'wp-blocks', 'wp-element' )
+	);
+}
+add_action( 'enqueue_block_editor_assets', 'myguten_enqueue' );
+```
+
+### Recap
+
+At this point, you have a plugin in the directory `wp-content/plugins/myguten-plugin` with two files. The PHP server-side code in `myguten-plugin.php`, and the JavaScript which runs in the browser in `myguten.js`.
+
+
+

docs/designers-developers/developers/tutorials/javascript/plugins-background.md

@@ -0,0 +1,17 @@
+
+## Plugins Background
+
+The primary means of extending WordPress remains the plugin, see [Plugin Basics](https://developer.wordpress.org/plugins/the-basics/) for more. The quick start is to create a new directory in `wp-content/plugins/` to hold your plugin code, for our example you can call it `myguten-plugin`.
+
+Inside of this new directory, create a file called `myguten-plugin.php` which will be the server-side code the runs when your plugin is active. For now you can place the following in that file:
+
+```php
+<?php
+/*
+Plugin Name: My Guten Plugin
+*/
+```
+
+So you should have a directory `wp-content/plugins/myguten-plugin/` which has the single file `myguten-plugin.php`. Once that is in place, you can go to your plugins list in `wp-admin` and you should see your plugin listed.
+
+Click **Activate** and your plugin will load with WordPress.

docs/designers-developers/developers/tutorials/javascript/readme.md

@@ -1,106 +1,21 @@
 
 # Getting Started with JavaScript
 
-The purpose of this tutorial is to step through getting started with JavaScript and WordPress. The Gutenberg documentation contains information on the APIs available, but as a reference and not necessarily full working examples. The goal of this tutorial is get you comfortable on how to use these snippets of code.
+The purpose of this tutorial is to step through getting started with JavaScript and WordPress. The Gutenberg Handbook documentation contains information on the APIs available for working with the block editor.
 
+The goal of this tutorial is get you comfortable on how to use the API reference and snippets of code found within.
 
-## Plugins Background
+### What is JavaScript
 
-The primary means of extending WordPress remains the plugin, see [Plugin Basics](https://developer.wordpress.org/plugins/the-basics/) for more. The quick start is create a new directory in `wp-content/plugins/` to hold your plugin code, call it `myguten-plugin`.
+JavaScript is a programming language which is loaded and executated in your web browser; compared to PHP which is run by a web server with the results sent to the browser, typically as HTML.
 
-Inside of this new directory, create a file called `myguten-plugin.php` which will be the server-side code the runs when your plugin is active. For now you can place the following in that file:
+The Block Editor introduced in WordPress 5.0 is written entirely in JavaScript, with the code run in the browser, and not on the server, it allows for a richer and more dynamic user experience.
 
-```php
-<?php
-/*
-Plugin Name: My Guten Plugin
-*/
-```
 
-So you should have a directory `wp-content/plugins/myguten-plugin/` which has the single file `myguten-plugin.php`. Once that is in place, you can go to your plugins list in `wp-admin` and you should see your plugin listed.
-
-Click **Activate** and your plugin will load with WordPress.
-
-
-## Loading JavaScript
-
-Now with the plugin in place, we can add our code that loads the JavaScript we want to use. This follows the standard WordPress methodology of enqueuing your scripts, see [Including CSS & JavaScript](https://developer.wordpress.org/themes/basics/including-css-javascript/) for more details.
-
-Add the following code to your `myguten-plugin.php` file:
-
-```php
-function myguten_enqueue() {
-	wp_enqueue_script( 'myguten-script',
-		plugins_url( 'myguten.js', __FILE__ ),
-		array( 'wp-blocks', 'wp-element' )
-	);
-}
-add_action( 'enqueue_block_editor_assets', 'myguten_enqueue' );
-```
-
-Create a file called `myguten.js` and add:
-
-```js
-console.log( "I'm loaded!" );
-```
-
-Now start a new post in the block editor, and check your browser Developer Tools. You should see the message in your console log. See [Mozilla's What are browser developer tools?](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/What_are_browser_developer_tools) if you need more information, the area to become most familiar with is [The JavaScript console](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/What_are_browser_developer_tools#The_JavaScript_console).
-
-The script enqueuing uses the `enqueue_block_editor_assets` hook which only loads the JavaScript when the block editor loads. So if you navigate to any front-end page or article on your site, you will not see the message.
-
-**Note:** The last argument in the `wp_enqueue_script()` function is an array of dependencies, all of the Gutenberg packages are registered and can be loaded by specifying them in the array, blocks and elements are shown as two common examples.
-
-Recap at this point, we have a plugin which loads JavaScript, we're off to a good start.
-
-
-## JavaScript versions and building
-
-The Gutenberg Handbook shows examples in two syntaxes ES5 and ESNext, note ESNext is sometimes referred to as ES6. The ES5 code is compatible with almost all current browsers.
-
-The ESNext syntax is compatible with most modern browsers, but unfortunately not IE11. Additionally, the ESNext code examples include JSX syntax, which requires a build step using webpack to transform into code that can be run in your browser.
-
-For this tutorial, all examples are written as the ES5 variation of JavaScript that can be run straight in your browser and does not require an additional build step.
-
-
-## Extending the Block Editor
-
-This puts all the initial pieces in place for you to start extending the Block Editor.
-
-Let's look at using the [Block Style Variation example](../../../../../docs/designers-developers/developers/filters/block-filters/#block-style-variations).
-
-Replace the existing `console.log()` code in your `myguten.js` file with:
-
-```js
-wp.blocks.registerBlockStyle( 'core/quote', {
-    name: 'fancy-quote',
-    label: 'Fancy Quote'
-} );
-```
-
-After you add the `wp.blocks.registerBlockStyle` code, save the `myguten.js` file, and then create a new post in the Block Editor.
-
-Add a quote block, and in the right sidebar under Styles, you will see your new Fancy Quote style listed. You can go back to the JavaScript and change the label to "Fancy Pants" and reload, and you will see the new label.
-
-Previewing or Publishing the post, you will not see a visible change. However, if you look at the source, you will see `is-style-fancy-quote` class name attached to your quote.
-
-Go ahead and create a `style.css` file with:
-
-```css
-.is-style-fancy-quote {
-	font-size: 64px;
-}
-
-```
-
-and enqueue the CSS by adding the following to your `myguten-plugin.php`:
-
-```php
-function myguten_stylesheet() {
-	wp_enqueue_style( 'myguten-style', plugins_url( 'style.css', __FILE__ ) );
-}
-add_action( 'enqueue_block_assets', 'myguten_stylesheet' );
-```
-
-And then when you view the page, you will see it in a very large font.
+### Table of Contents
 
+1. [Plugins Background](../../../../../docs/designers-developers/developers/tutorials/javascript/plugins-background.md)
+2. [Loading JavaScript](../../../../../docs/designers-developers/developers/tutorials/javascript/loading-javasript.md)
+3. [JavaScript Versions and Building](../../../../../docs/designers-developers/developers/tutorials/javascript/versions-and-building.md)
+4. [Extending the Block Editor](../../../../../docs/designers-developers/developers/tutorials/javascript/extending-the-block-editor.md)
 

docs/designers-developers/developers/tutorials/javascript/versions-and-building.md

@@ -0,0 +1,14 @@
+
+## JavaScript versions and build step
+
+The Gutenberg Handbook shows JavaScript examples in two syntaxes ES5 and ESNext. These are version names for the JavaScript language standard definitions. You may also see elsewhere the versions ES6, or ECMAScript 2015 mentioned. Ses the [ECMAScript](https://en.wikipedia.org/wiki/ECMAScript) Wikipedia article for all the details.
+
+ES5 code is compatible with WordPress's minimum [target for browser compatibility](https://make.wordpress.org/core/2017/04/23/target-browser-coverage/).
+
+For this tutorial, all examples are written compatible to ES5 definition of JavaScript. This code can be run straight in your browser and does not require an additional build step.
+
+The ESNext version is dynamic and refers to the next language defintions, which will always be ahead of browser support. An extra build step is required to transform the code to a syntax that works in all browsers. Webpack is the tool that performs this transformation step.
+
+Additionally, the ESNext code examples in the Gutenberg handbook include JSX syntax, which is easier to read and write, but likewise requires the build step using webpack and babel to transform into compatible code.
+
+