Docs: Move DevEnv to own section for docs (#23593)

* Move devenv to own section

* Update links to new devenv section

* Add devenv to docs TOC

* Apply suggestions from code review

Co-authored-by: Greg Ziółkowski <[email protected]>

* Update devenv with review feedback

* Switch to image tag

* Add link in JS tutorial to new dev env section

Adds an additional link in JS tutorial to the new development
environment section, with regards to installing using nvm.

Plus includes a bit of markdown linting.

* Update with review comments, typos

* Clarify wp-env start is from plugin directory

* Apply suggestions from code review

Co-authored-by: Greg Ziółkowski <[email protected]>

* Move pre-requisites above quick start

* Update links to use full path

Co-authored-by: Greg Ziółkowski <[email protected]>

docs/designers-developers/developers/tutorials/create-block/author-experience.md

@@ -138,4 +138,4 @@ export default function Edit( { attributes, className, setAttributes } ) {
 }
 ```
 
-Next Section: [Finishing Touches](finishing.md)
+Next Section: [Finishing Touches](/docs/designers-developers/developers/tutorials/create-block/finishing.md)

docs/designers-developers/developers/tutorials/create-block/block-anatomy.md

@@ -57,4 +57,4 @@ __( 'Gutenpride', 'create_block' );
 
 This is an internationalization wrapper that allows for the string "Gutenpride" to be translated. The second parameter, "create_block" is called the text domain and gives context for where the string is from. The JavaScript internationalization, often abbreviated i18n, matches the core WordPress internationalization process. See the [I18n for WordPress documentation](https://codex.wordpress.org/I18n_for_WordPress_Developers) for more details.
 
-Next Section: [Block Attributes](block-attributes.md)
+Next Section: [Block Attributes](/docs/designers-developers/developers/tutorials/create-block/block-attributes.md)

docs/designers-developers/developers/tutorials/create-block/block-attributes.md

@@ -71,4 +71,4 @@ export default function Save( { attributes, className } ) {
 
 Rebuild the block using `npm run build`, reload the editor and add the block. Type a message in the editor, save, and view it in the post.
 
-Next Section: [Code Implementation](block-code.md)
+Next Section: [Code Implementation](/docs/designers-developers/developers/tutorials/create-block/block-code.md)

docs/designers-developers/developers/tutorials/create-block/block-code.md

@@ -64,4 +64,4 @@ Update **gutenpride.php** to enqueue from generated file location:
 $editor_css = "build/index.css";
 ```
 
-Next Section: [Authoring Experience](author-experience.md)
+Next Section: [Authoring Experience](/docs/designers-developers/developers/tutorials/create-block/author-experience.md)

docs/designers-developers/developers/tutorials/create-block/readme.md

@@ -4,6 +4,10 @@ Let's get you started creating your first block for the WordPress Block Editor.
 
 The tutorial includes setting up your development environment, tools, and getting comfortable with the new development model. If you are already comfortable, try the quick start below, otherwise step through whatever part of the tutorial you need.
 
+## Prerequisities
+
+The first thing you need is a development enviornment and tools. This includes setting up your WordPress environment, Node, NPM, and your code editor. If you need help, see the [setting up your development environment documentation](/docs/designers-developers/developers/tutorials/devenv/readme.md).
+
 ## Quick Start
 
 The `@wordpress/create-block` package exists to create the necessary block scaffolding to get you started. See [create-block package documentation](https://www.npmjs.com/package/@wordpress/create-block) for additional features. This quick start assumes you have a development environment with node installed, and a WordPress site.
@@ -22,10 +26,12 @@ After activated, go to the block editor and use the inserter to search and add y
 
 ## Table of Contents
 
-1. [Development Environment](devenv.md)
-2. [WordPress Plugin](wp-plugin.md)
-3. [Anatomy of a Block](block-anatomy.md)
-4. [Block Attributes](block-attributes.md)
-5. [Code Implementation](block-code.md)
-6. [Authoring Experience](author-experience.md)
-7. [Finishing Touches](finishing.md)
+The create a block tutorials breaks down to the following sections.
+
+1. [WordPress Plugin](/docs/designers-developers/developers/tutorials/create-block/wp-plugin.md)
+2. [ESNext Syntax](/docs/designers-developers/developers/tutorials/create-block/esnext-js.md)
+3. [Anatomy of a Gutenberg Block ](/docs/designers-developers/developers/tutorials/create-block/block-anatomy.md)
+4. [Block Attributes](/docs/designers-developers/developers/tutorials/create-block/block-attributes.md)
+5. [Code Implementation](/docs/designers-developers/developers/tutorials/create-block/block-code.md)
+6. [Authoring Experience](/docs/designers-developers/developers/tutorials/create-block/author-experience.md)
+7. [Finishing Touches](/docs/designers-developers/developers/tutorials/create-block/finishing.md)

docs/designers-developers/developers/tutorials/create-block/wp-plugin.md

@@ -49,7 +49,7 @@ Let's confirm the plugin is loaded and working.
 
 -or-
 
-(3B) If you are using `wp-env`, see [Development Environment setup](devenv.md), then you should now run this command from inside the `gutenpride` directory:
+(3B) If you are using `wp-env`, see [Development Environment setup](/docs/designers-developers/developers/tutorials/devenv/readme.md), then you should now run from inside the `gutenpride` directory:
 
 ```sh
 wp-env start
@@ -156,4 +156,4 @@ For more info, see the build section of the [Getting Started with JavaScript tut
 
 Hopefully, at this point, you have your plugin created and activated. We have the package.json with the `@wordpress/scripts` dependency, that defines the build and start scripts. The basic block is in place and can be added to the editor.
 
-Next Section: [Anatomy of a Block](block-anatomy.md)
+Next Section: [Anatomy of a Block](/docs/designers-developers/developers/tutorials/create-block/block-anatomy.md)

docs/designers-developers/developers/tutorials/create-block/devenv.md → docs/designers-developers/developers/tutorials/devenv/readme.md

@@ -1,14 +1,16 @@
 # Development Environment
 
-We will need a place to work and tools for creating a block, this is often referred to as the development environment. The three main pieces needed for our development environment are:
+The development environment setup guide is for setting up your local development environment for JavaScript development; creating plugins and tools for extending WordPress and the block editor.
+
+A development environment is a catch-all term for the setup on your computer to work. The three main pieces needed for our development environment are:
 
 1. Node/NPM Development Tools
 2. WordPress Development Site
 3. Code Editor
 
 ## Development Tools
 
-The tools needed for development are **Node** and **NPM**. **Nodejs** is a runtime environment that allows running JavaScript outside of the browser. NPM is the Node Package Manager, it is used for installing dependencies and running scripts. The script `npx` is installed with `npm` and is used to run packages not yet installed, we will use this to bootstrap a block.
+The tools needed for development are **Node** and **NPM**. **Nodejs** is a runtime environment that allows running JavaScript outside of the browser. NPM is the Node Package Manager, it is used for installing dependencies and running scripts. The script `npx` is also installed with Nodejs—this script is used to run packages not yet installed—we will use `npx` to bootstrap a block.
 
 The tools are used to convert the JavaScript we are going to write into a format that browsers can run. This is called transpiling or the build step.
 
@@ -18,15 +20,36 @@ For Windows, or alternative installs, you can [download a Nodejs installer](http
 
 Here are the quick instructions to install using nvm, see the [full installation instructions](https://github.com/nvm-sh/nvm#installing-and-updating) for additional details.
 
-A tip for macOS Catalina, the default profile file may not be created, you can create the required file typing `touch ~/.zshrc` on the command-line. It is fine to run if the file already exists. Note, `~/` is a shortcut to your home directory.
-
 Run the following on the command-line to install nvm:
 
 ```sh
 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.3/install.sh | bash
 ```
 
-After installing nvm, you need to use it to install node, to install the latest version of node, run:
+Note: On macOS, the required developer tools are not installed by default, if not already installed you may be prompted to download the install.
+
+<img src="https://developer.wordpress.org/files/2020/07/git-install-prompt.png" alt="Mac git command requies command line developer tools" width="400" height="195"/>
+
+After installing nvm, you need to use it to install node, to install the LTS version of node, run:
+
+```sh
+nvm install --lts
+```
+
+If there is an error running the above command, for example a common error that occurs is:
+
+```sh
+$ nvm install --lts
+zsh: command not found: nvm
+```
+
+First, try quitting and restarting your terminal to pick up the installed config.
+
+If restarting did not resolve the problem, you might need to create the default profile file.
+
+On macOS Catalina, the default shell is zsh, to create the profile file type `touch ~/.zshrc` on the command-line. It is fine to run if the file already exists. Note, `~/` is a shortcut to your home directory. For Ubuntu, including WSL, the default profile is bash, use `touch ~/.bashrc` to create.
+
+After creating the profile file, re-run the install command:
 
 ```sh
 nvm install --lts
@@ -52,20 +75,32 @@ The WordPress [wp-env package](https://www.npmjs.com/package/@wordpress/env) let
 
 The `wp-env` package requires Docker to be installed. There are instructions available for installing Docker on [Windows 10 Pro](https://docs.docker.com/docker-for-windows/install/), [all other versions of Windows](https://docs.docker.com/toolbox/toolbox_install_windows/), [macOS](https://docs.docker.com/docker-for-mac/install/), and [Linux](https://docs.docker.com/v17.12/install/linux/docker-ce/ubuntu/#install-using-the-convenience-script).
 
-After confirming that the prerequisites are installed, install `wp-env` globally from the command-line using:
+After you have installed Docker, go ahead and install `wp-env` globally from the command-line using:
 
 ```sh
 npm -g install @wordpress/env
 ```
 
-This will be used in the next [Plugin step](wp-plugin.ms). To confirm it is installed and available, run:
+To confirm it is installed and available, run:
 
 ```sh
 wp-env --version
-> 1.4.0
+> 1.6.0
+```
+
+The `wp-env` script is used to create a Docker WordPress environment, to use start from your plugin directory—if you are following the create block tutorial, this would be in the generated directory.
+
+```sh
+wp-env start
 ```
 
-### Alternatives
+You can access your environment in your browser at: [http://localhost:8888/](http://localhost:8888/), the default username is `admin` and default password is `password`. For more information controlling the Docker environment see the [@wordpress/env package readme](/packages/env/README.md).
+
+If you are developing a single plugin, you should run `wp-env start` from that plugin working directory—it will mount and activate the plugin automatically. Note: This also works for themes, run from the directory you are developing the theme.
+
+If you want a single environment for all your plugins/themes, you need to create a `.wp-env.json` in a working directory and add the plugins/themes to it. You then run `wp-env start` from the same directory as that config file. See the [@wordpress/env package for additional details](/packages/env/README.md#wp-envjson).
+
+### Alternative to Docker
 
 A block is just a plugin, so any WordPress environment can be used for development. A couple of alternatives that might be easier, since they do not require Docker install and setup.
 
@@ -84,5 +119,3 @@ The important part is having a WordPress site installed, and know where and how
 Alternative editors include [Sublime Text](https://www.sublimetext.com/) that is also available across platforms, though is a commercial product; or other free alternatives include [Vim](https://www.vim.org/), [Atom](https://atom.io/), and [Notepad++](https://notepad-plus-plus.org/) all support standard JavaScript style development.
 
 You can use any editor you're comfortable with, it is more a personal preference. The development setup for WordPress block editor is a common JavaScript environment and most editors have plugins and suppport. The key is having a way to open, edit, and save text files.
-
-Next Section: [WordPress Plugin](wp-plugin.md)

docs/designers-developers/developers/tutorials/javascript/js-build-setup.md

@@ -34,13 +34,13 @@ First, you need to set up Node.js for your development environment. The steps re
 -   macOS: `brew install node`
 -   Windows: `choco install node`
 
-If you are not using a package manager, see the [Node.js download page](https://nodejs.org/en/download/) for installers and binaries.
+If you are not using a package manager, see the [developer environment setup documentation](/docs/designers-developers/developers/tutorials/devenv/readme.md) for setting up Node using nvm, or see the official [Node.js download page](https://nodejs.org/en/download/) for installers and binaries.
 
 **Note:** The build tools and process occur on the command-line, so basic familiarity using a terminal application is required. Some text editors have a terminal built-in that is fine to use; Visual Studio Code and PhpStorm are two popular options.
 
 ### Node Package Manager (npm)
 
-The Node Package Manager (npm) is a tool included with node. npm allows you to install and manage JavaScript packages. npm can also generate and process a special file called `package.json`, which contains some information about your project and the packages your project uses.
+The Node Package Manager (npm) is a tool included with node. npm allows you to install and manage JavaScript packages. npm can also generate and process a special file called `package.json`, that contains information about your project and the packages your project uses.
 
 To start a new node project, first create a directory to work in:
 
@@ -127,9 +127,7 @@ You can then run the build using: `npm run build`.
 
 After the build finishes, you will see the built file created at `build/index.js`. Enqueue this file in the admin screen as you would any JavaScript in WordPress, see [loading JavaScript step in this tutorial](/docs/designers-developers/developers/tutorials/javascript/loading-javascript.md), and the block will load in the editor.
 
-## Finishing Touches
-
-### Development Mode
+## Development Mode
 
 The **build** command in `@wordpress/scripts` runs in "production" mode. This shrinks the code down so it downloads faster, but makes it difficult to read in the process. You can use the **start** command which runs in development mode that does not shrink the code, and additionally continues a running process to watch the source file for more changes and rebuilds as you develop.
 
@@ -146,13 +144,13 @@ Now, when you run `npm start` a watcher will run in the terminal. You can then e
 
 **Note:** keep an eye on your terminal for any errors. If you make a typo or syntax error, the build will fail and the error will be in the terminal.
 
-### Source Control
+## Source Control
 
 Because a typical `node_modules` folder will contain thousands of files that change with every software update, you should exclude `node_modules/` from your source control. If you ever start from a fresh clone, simply run `npm install` in the same folder your `package.json` is located to pull your required packages.
 
 Likewise, you do not need to include `node_modules` or any of the above configuration files in your plugin because they will be bundled inside the file that webpack builds. **Be sure to enqueue the `build/index.js` file** in your plugin PHP. This is the main JavaScript file needed for your block to run.
 
-### Dependency Management
+## Dependency Management
 
 Using `wp-scripts` ver 5.0.0+ build step will also produce an `index.asset.php` file that contains an array of dependencies and a version number for your block. For our simple example above, it is something like:
 `array('dependencies' => array('wp-element', 'wp-polyfill'), 'version' => 'fc93c4a9675c108725227db345898bcc');`

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

@@ -1,15 +1,17 @@
 # Tutorials
 
-* See the [Getting Started with JavaScript Tutorial](/docs/designers-developers/developers/tutorials/javascript/readme.md) to learn about how to use JavaScript within WordPress.
+-   First things first, see [setting up your development environment](/docs/designers-developers/developers/tutorials/devenv/readme.md) for the tools and setup you need to extend the block editor.
 
-* The [Blocks Tutorial](/docs/designers-developers/developers/tutorials/block-tutorial/readme.md) is the best place to start to learn more about block creation.
+-   See the [Getting Started with JavaScript Tutorial](/docs/designers-developers/developers/tutorials/javascript/readme.md) to learn about how to use JavaScript within WordPress.
 
-* See the [Meta Boxes Tutorial](/docs/designers-developers/developers/tutorials/metabox/readme.md) for new ways of extending the editor storing and using post meta data.
+-   The [Blocks Tutorial](/docs/designers-developers/developers/tutorials/block-tutorial/readme.md) is the best place to start to learn more about block creation.
 
-* Check out the [Notices Tutorial](/docs/designers-developers/developers/tutorials/notices/README.md) to learn how to display informational UI at the top of the editor.
+-   See the [Meta Boxes Tutorial](/docs/designers-developers/developers/tutorials/metabox/readme.md) for new ways of extending the editor storing and using post meta data.
 
-* The [Sidebar Tutorial](/docs/designers-developers/developers/tutorials/sidebar-tutorial/plugin-sidebar-0.md) will walk you through the steps of creating a sidebar to update data from the `post_meta` table.
+-   Check out the [Notices Tutorial](/docs/designers-developers/developers/tutorials/notices/README.md) to learn how to display informational UI at the top of the editor.
 
-* Learn how to add customized buttons to the toolbar with the [Format API tutorial](/docs/designers-developers/developers/tutorials/format-api/).
+-   The [Sidebar Tutorial](/docs/designers-developers/developers/tutorials/sidebar-tutorial/plugin-sidebar-0.md) will walk you through the steps of creating a sidebar to update data from the `post_meta` table.
 
-* Build your own [custom block editor instance](/docs/designers-developers/developers/platform/custom-block-editor/) - this will walk you through building a standalone instance of the block editor within WP Admin.
+-   Learn how to add customized buttons to the toolbar with the [Format API tutorial](/docs/designers-developers/developers/tutorials/format-api/).
+
+-   Build your own [custom block editor instance](/docs/designers-developers/developers/platform/custom-block-editor/) - this will walk you through building a standalone instance of the block editor within WP Admin.

docs/manifest.json

@@ -461,6 +461,12 @@
 		"markdown_source": "../docs/designers-developers/developers/tutorials/readme.md",
 		"parent": null
 	},
+	{
+		"title": "Development Environment",
+		"slug": "devenv",
+		"markdown_source": "../docs/designers-developers/developers/tutorials/devenv/readme.md",
+		"parent": "tutorials"
+	},
 	{
 		"title": "Getting Started with JavaScript",
 		"slug": "javascript",

docs/toc.json

@@ -92,6 +92,7 @@
 		{ "docs/contributors/repository-management.md": [] }
 	] },
 	{ "docs/designers-developers/developers/tutorials/readme.md": [
+		{ "docs/designers-developers/developers/tutorials/devenv/readme.md": [] },
 		{ "docs/designers-developers/developers/tutorials/javascript/readme.md": [
 			{ "docs/designers-developers/developers/tutorials/javascript/plugins-background.md": [] },
 			{ "docs/designers-developers/developers/tutorials/javascript/loading-javascript.md": [] },