Merge a871104 into 53cfc0e

docs/en/userguide/edit_content.md

@@ -2,11 +2,11 @@
 
 To get started, create a new page in the CMS. See [Pages and content](https://userhelp.silverstripe.org/en/4/creating_pages_and_content/) to learn more.
 
-## Creating and editing content
+## Creating and editing content {#creating-blocks}
 
-Click the button ***Add block*** and select the type of block you want to create from the popover option set. You'll see that content block types are also searchable on open. To remove your search click the link ***Clear***.
+Click the button ***Add block*** and select the type of block you want to create from the block selector. You'll see that content block types are also searchable on open. To remove your search click the link ***Clear***.
 
-![Choose a block type to create](_images/creating_a_content_block.png)
+![Choose a block type to create](_images/adding_content_block.png)
 
 You'll see the content block type you selected appear in your main content area titled ***Untitled Content block***. If you forget the content block type you've added, hover on the block type icon to view a tooltip.
 
@@ -22,7 +22,7 @@ Enter your content as required, provide a title for the block and choose whether
 
 ![Expanded content block](_images/inline_editing.png)
 
-## Reordering content blocks
+## Reordering content blocks {#reordering-blocks}
 
 To change the order of content blocks in a page, simply click and hold anywhere on the block, then drag and release to reorder the item.
 
@@ -34,7 +34,24 @@ When you release the block will automatically save their new positions, however
 
 <div class="note" markdown="1">Similar to the reorganisation of pages, the state of a block is changed after it is relocated and a new version is created.</div>
 
-## More options
+## Adding blocks between existing blocks {#adding-between-blocks}
+
+An **Add block** button shown as a bar and plus icon can be activated by moving your cursor between blocks. You can select anywhere on the bar to open a block selector which will appear on the right hand side allowing you to add a block between existing blocks.
+
+![Adding in-page blocks](_images/adding_blocks_between_blocks.png)
+
+#### Block state indicators {#state-indicators}
+
+States are shown on the block type icon as coloured indicators. Each represents the current workflow status your content block is in.
+
+Blue - The block has unsaved changes.
+Orange full - The block state is **Draft** and not publicly visible.
+Orange outline - The block is **Modified** where it has been published but has some additional draft changes.
+No state - The block is published.
+
+![States of content blocks](_images/content_block_states.png)
+
+## More options {#more-options}
 
 The ***More options*** dropdown shown as an ellipses icon provides further editing functionality of individual blocks including access to editing content, custom settings, saving, publishing and archiving.
 
@@ -56,17 +73,6 @@ Pages with content blocks allow you to perform actions like publish at a page le
 
 To save or publish an individual content block select the ***More options*** dropdown. To save or publish the whole page select from the Action toolbar of the CMS. See [Saving changes and publishing](https://userhelp.silverstripe.org/en/4/creating_pages_and_content/creating_and_editing_content/saving_changes_and_publishing/) for more information.
 
-#### Block state indicators
-
-States are shown on the block type icon as coloured indicators. Each represents the current workflow status your content block is in.
-
-Blue - The block has unsaved changes.
-Orange full - The block state is **Draft** and not publicly visible.
-Orange outline - The block is **Modified** where it has been published but has some additional draft changes.
-No state - The block is published.
-
-![States of content blocks](_images/content_block_states.png)
-
 ### Archiving blocks
 
 To Archive a block select *Archive* in the ***More options*** dropdown. See [Archiving](https://userhelp.silverstripe.org/en/4/creating_pages_and_content/archive/) for more information.

docs/en/userguide/index.md

@@ -1,21 +1,34 @@
 title: Content blocks
-summary: Content blocks overview.
+summary: Break up a web page into blocks that allow content like banners, text and media to be independently managed within the CMS.
+
+## Features
+
+* [Creating content blocks](edit_content.md#creating-blocks)
+* [Reordering blocks](edit_content.md#reordering-blocks) 
+* [Adding blocks between existing blocks](edit_content.md#adding-between-blocks)
+* [Block state indicators](edit_content.md#state-indicators)
+* [More options](edit_content.md#more-options)
+* [Supported and community block modules](#supported-blocks)
+* [History and rolling back versions](history.md)
+* [Reports](reports.md)
 
 <div class="note" markdown="1">The Content blocks feature is new as of SilverStripe 4 and therefore will continue to develop with functionality.</div>
 
-# Content blocks overview
+## Content blocks overview
 
 The [Elemental module](https://addons.silverstripe.org/add-ons/dnadesign/silverstripe-elemental) provides the ability for SilverStripe users to break up a web page into smaller modular parts (or ‘blocks’) that allow content like banners, text and media to be independently managed within the CMS. This also allows for more targeted control over individual types of content, as well as individual versioning, more detailed reports and easy customisation for developers over how certain pieces of content are presented.
 
-## Before we begin
+### Before we begin
 
 Make sure that your SilverStripe CMS installation has the [Elemental module](https://addons.silverstripe.org/add-ons/dnadesign/silverstripe-elemental) installed.
 
 <div class="note" markdown="1">Developer knowledge is required to enable the functionality within the configuration before you begin.</div>
 
 ## Using content blocks in the CMS
 
-Normally in the CMS a page has an HTML editor which allows you to enter content directly. The block types shown in the popover action set will depend on your set up. By default the [Elemental module](https://github.com/dnadesign/silverstripe-elemental) only comes with the content block type, **Content**.
+Normally in the CMS a page has an HTML editor which allows you to enter content directly. The block types shown in the block selector will depend on your set up. By default the [Elemental module](https://github.com/dnadesign/silverstripe-elemental) only comes with the content block type, **Content**.
+
+### Supported content blocks {#supported-blocks}
 
 We’ve created the most functional and effective elements of content block modules that have been developed by the SilverStripe community and created four generic SilverStripe supported content block types:
 
@@ -26,11 +39,7 @@ We’ve created the most functional and effective elements of content block modu
 
 ![Supported content block types](_images/content_block_types.png)
 
+### Community content blocks
+
 For examples of community content blocks see,
 [Getting more elements](https://github.com/dnadesign/silverstripe-elemental#getting-more-elements).
-
-## Features
-
-* [Creating and editing blocks](edit_content.md)
-* [History and rollback to certain versions](history.md)
-* [Reports](reports.md)