Blocks: reorganize docs to be easier to parse (#15239)

* Blocks: reorganize docs to be easier to parse

* Clarify where view files are loaded

Fixes #15428

See `load_styles_as_required` and `load_scripts_as_required` methods.

extensions/README.md

@@ -20,8 +20,8 @@ Extensions in the `extensions/blocks` folder loosely follow this structure:
 	├── block-or-plugin-name.php ← PHP file where the block and its assets are registered.
 	├── editor.js                ← script loaded only in the editor
 	├── editor.scss              ← styles loaded only in the editor
-	├── view.js                  ← script loaded in the editor and theme
-	└── view.scss                ← styles loaded in the editor and theme
+	├── view.js                  ← script loaded on the frontend
+	└── view.scss                ← styles loaded on the frontend
 ```
 
 If your block depends on another block, place them all in extensions folder:
@@ -67,29 +67,23 @@ We also offer an "experimental" state for extensions. Those extensions will be m
 
 Experimental extensions are usually considered ready for production, but are served only to sites requesting them.
 
-### Testing
-
-Run `yarn test-extensions [--watch]` to run tests written in [Jest](https://jestjs.io/en/).
-
-Note that adding [Jest snapshot tests](https://jestjs.io/docs/en/snapshot-testing) for block's `save` methods is problematic because many core packages relying on `window` that is not present when testing with Jest. See [prior exploration](https://github.com/Automattic/wp-calypso/pull/30727).
-
-## Scaffolding blocks with WP-CLI
+### Scaffolding blocks with WP-CLI
 
 We have a command in WP-CLI that allows to scaffold Jetpack blocks. Its syntax is as follows:
 
 `wp jetpack scaffold <type> <title> [--slug] [--description] [--keywords] [--variation]`
 
 **Currently the only `type` is `block`.**
 
-### Options
+#### Options
 
 - **title**: Block name, also used to create the slug. This parameter is required. If it's something like _Logo gallery_, the slug will be `logo-gallery`. It's also used to generate the class name when an external edit component is requested. Following this example, it would be `LogoGalleryEdit`.
 - **--slug**: Specific slug to identify the block that overrides the one generated base don the title.
 - **--description**: Allows to provide a text description of the block.
 - **--keywords**: Provide up to three keywords separated by a comma so users when they search for a block in the editor.
 - **--variation**: Allows to decide whether the block should be a production block, experimental, or beta. Defaults to Beta when arg not provided.
 
-### Files
+#### Files
 
 All files will be created in a directory under `extensions/blocks/` named after the block title or a specific given slug. For a hypothetical **Jukebox** block, it will create the following files
 
@@ -103,7 +97,7 @@ All files will be created in a directory under `extensions/blocks/` named after
 Additionally, the slug of the new block will be added to the `beta` array in the file `extensions/index.json`.
 Since it's added to the beta array, you need to load the beta blocks as explained above to be able to test this block.
 
-### Examples
+#### Examples
 
 `wp jetpack scaffold block "Cool Block"`
 
@@ -113,12 +107,20 @@ Since it's added to the beta array, you need to load the beta blocks as explaine
 
 `wp jetpack scaffold block "Jukebox" --variation="experimental"`
 
-### Can I use Jurassic Ninja to test blocks?
+### Testing
+
+Run `yarn test-extensions [--watch]` to run tests written in [Jest](https://jestjs.io/en/).
+
+Note that adding [Jest snapshot tests](https://jestjs.io/docs/en/snapshot-testing) for block's `save` methods is problematic because many core packages relying on `window` that is not present when testing with Jest. See [prior exploration](https://github.com/Automattic/wp-calypso/pull/30727).
+
+#### Can I use Jurassic Ninja to test blocks?
 
 Yes! Just like any other changes in Jetpack, also blocks work in Jurassic Ninja.
 
 Simply add branch name to the URL: jurassic.ninja/create/?jetpack-beta&branch=master or use other ninjastic features.
 
+## Deploying extensions
+
 ### How do I merge extensions to Jetpack
 
 - Jetpack is released once a month, so be sure your team is aware of [upcoming code freezes](https://github.com/Automattic/Jetpack/milestones).
@@ -154,7 +156,7 @@ To test extensions for a Simple site in Calypso, sandbox the simple site URL (`e
 
 ## Good to know when developing Gutenberg extensions
 
-## The Build
+### The Build
 
 - Compiled extensions are output to `_inc/blocks`
 - You can view the various build commands in `package.json`
@@ -164,7 +166,7 @@ If you need to modify the build process, bear in mind that config files are also
 synced to WordPress.com via Fusion. Consult with a Jetpack crew member to ensure
 you test the new build in both environments.
 
-## Debugging
+### Debugging
 
 Setting these might be useful for debugging with block editor: