Merge branch 'devdocs-develop' into MAGEDOC-3427-configuration

# Conflicts:
#	docs/reference/configurations.md

Author: davemacaulay

docs/create-custom-content-type/overview.md

@@ -16,7 +16,7 @@ And the same three Quote controls are shown rendered here on a mock testimonial
 
 ## Quote module
 
-As with most things in Magento, content types for Page Builder are housed in modules. The convention for naming modules that are solely dedicated to Page Builder, such as our Quote content type, is to prefix all the content type name with `PageBuilder`. This helps visually group content type modules within your vendor directory. Of course, this convention doesn't apply If you are adding a content type as part of an existing module.
+As with most things in Magento, content types for Page Builder are housed in modules. The convention for naming modules that are solely dedicated to Page Builder, such as our Quote content type, is to prefix all content type names with `PageBuilder`. This helps visually group content type modules within your vendor directory. Of course, this convention does not apply if you are adding a content type as part of an existing module.
 
 Applying this convention to the module for our Quote content type, we get the name `PageBuilderQuote`, and can set up our module as shown here:
 
@@ -28,7 +28,7 @@ After registering your module (`bin/magento setup:upgrade`) you will be ready to
 
 The steps for creating the Quote content type are illustrated and described below. The reality is not quite this linear, but these steps do represent the basic phases and flow for building new Page Builder content types.
 
-![Creating Custom Content Types](../images/content-type-overview.png)
+![Creating Custom Content Types](../images/content-type-overview.svg)
 
 1. **Add configuration**: Create an XML file to define your content type and reference the other files that control the appearance and behavior of your content type.  
 2. **Add templates**: Create HTML templates that define the appearance of your content types on the Admin stage (`preview.html`) and the storefront (`master.html`).

docs/extend-existing-content-type/overview.md

@@ -1,3 +1,51 @@
 # Overview
 
-This topic is currently under development. It will be completed by the GA release of Page Builder.
+One of quickest ways to customize Page Builder is by changing how _existing_ content types look and behave. End-users can already edit Page Builder's content types in several ways. But sometimes your end-users will want to change the structure or modify properties that do not exist on a given content type. In those cases, you can extend an existing content type by customizing its existing _appearance_ or adding a new _appearance_.
+
+## Appearances
+
+An **appearance** is an XML element in a content type's configuration file that lets you modify existing properties, templates, styles, and form fields, or create new ones. In other words, all Page Builder content types (existing or custom) are extended through appearances.
+
+Many of Page Builder's content types have only one `appearance` element. These include the Heading, Text, Image, Video, Tabs, and more. Other content types have several appearances. For example, the Banner content type has four appearances, as shown here:
+
+![banner-appearances](../images/banner-appearances.png)  
+
+Page Builder defines these appearances in the Banner's configuration file (`Magento/PageBuilder/view/adminhtml/pagebuilder/content_type/banner.xml`), as shown here:
+
+```
+<appearances>
+    <appearance name="collage-left"...>
+    <appearance name="collage-centered"...>
+    <appearance name="collage-right"...>
+    <appearance name="poster" default="true" ...>
+</appearances>
+```
+
+Within each `appearance` element, you can change content types in the following ways:
+
+- Add new style properties.
+- Add or change templates.
+- Add to or change existing forms.
+- Add new attributes.
+- Move data between elements.
+
+## Banner extension tutorial
+
+In this tutorial, you will extend the Banner content type by adding a new `max-height` style property to two of the Banner's existing appearances: `collage-left` and `collage-right`.
+
+![Page Builder Banner menu item](../images/extend-banner-menu.png){:width="815px" height="auto"}
+
+## Banner extension steps
+
+These steps show the basic pattern for adding style properties using existing appearances to extend a content type:
+
+![Creating Custom Content Types](../images/extension-steps-overview.svg)
+
+1. **Create an extension module**: Create a basic module for your Banner extensions.
+2. **Extend appearances**: Extend the existing content type's configuration file by customizing an existing appearance with new style properties.
+3. **Extend forms**: Extend the existing content type's UI component form by adding new form fields and changing defaults for existing fields.
+
+## Next
+
+[Step 1: Create an extension module](step-1-create-extension-module.md)
+

docs/extend-existing-content-type/step-1-create-extension-module.md

@@ -0,0 +1,49 @@
+# Step 1: Create an extension module
+
+Appearance extensions for Page Builder are implemented using modules. In this step, we will create an empty module so we can add our appearance and form extensions in steps 2 and 3, as shown here:
+
+![Completed extension file structure](../images/extension-file-structure-complete.png){:width="826px" height="auto"}
+
+## Add directory structure
+
+To create a module for the Banner extensions, name your vendor directory `Example` and name your module `PageBuilderExtensionBanner`, as shown here:
+
+![Minimum extension module structure](../images/banner-extension-file-structure.png){:width="530px" height="auto"}
+
+The convention for naming extension modules is to prefix your extension of an existing content type with `PageBuilderExtension`, followed by the name of the content type. This is not a required convention, but we find that it helps visually group extension modules within your vendor directory.
+
+## Add module file
+
+Your module file should look like this:
+
+```xml
+<?xml version="1.0"?>
+<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
+    <module name="Example_PageBuilderExtensionBanner" setup_version="1.0.0">
+        <sequence>
+            <module name="Magento_PageBuilder"/>
+        </sequence>
+    </module>
+</config>
+```
+
+## Add registration file
+
+Your registration file should look like this:
+
+```php
+<?php
+
+use \Magento\Framework\Component\ComponentRegistrar;
+
+ComponentRegistrar::register(ComponentRegistrar::MODULE, 'Example_PageBuilderExtensionBanner', __DIR__);
+```
+
+## Install your module
+
+From your Magento root directory, use `bin/magento setup:upgrade` to install and enable your module.
+
+## Next
+
+[Step 2: Extend appearances](step-2-extend-appearances.md) 
+

docs/extend-existing-content-type/step-2-extend-appearances.md

@@ -0,0 +1,6 @@
+# Step 2: Extend appearances
+
+In progress. To be officially published on 3/26
+
+
+

docs/extend-existing-content-type/step-3-extend-forms.md

@@ -0,0 +1,4 @@
+# Step 3: Extend forms
+
+In progress. To be officially published on 3/26
+

docs/getting-started/install-pagebuilder-examples.md

@@ -1,18 +1,50 @@
 # Install Page Builder Examples
 
-You can find the code examples used, and referred to, within this documentation on GitHub in the [pagebuilder-examples repo](https://github.com/magento-devdocs/pagebuilder-examples). This repo contains two types of examples:
+You can find the Page Builder examples used in this documentation on GitHub in the [pagebuilder-examples repo](https://github.com/magento-devdocs/pagebuilder-examples). This repo contains two types of examples:
 
 - Fully functional modules
 - Files for how-to topics
 
 ## Fully functional modules
 
-The following custom content type modules are here for you to download and install so you can learn by example:
+To learn by example, the [Example directory](https://github.com/magento-devdocs/pagebuilder-examples/tree/master/Example) on the repo provides the following custom content-type modules for you to download and install.
 
 - **[PageBuilderQuote](https://github.com/magento-devdocs/pagebuilder-examples/tree/master/Example/PageBuilderQuote)**—This module shows you how to use a simple content type to stylize quotations for things like customer testimonials. This is the completed module featured in the [content type tutorial](../create-custom-content-type/overview.md).
 - **[PageBuilderGrid](https://github.com/magento-devdocs/pagebuilder-examples/tree/master/Example/PageBuilderGrid)**—This module shows you how to create a content type to rebuild the Magento Luma home page using a grid structure with grid items.
 - **[PageBuilderFaq](https://github.com/magento-devdocs/pagebuilder-examples/tree/master/Example/PageBuilderFaq)**—This module shows you how to create a content type for an FAQ page that uses an accordion for the questions and answers.
 
+## Installation
+
+Assuming you have Page Builder 1.0.0 already installed, you can install the example modules as follows:
+
+1. Clone the pagebuilder-examples repo:
+
+    ```bash
+    git clone https://github.com/magento-devdocs/pagebuilder-examples
+    ```
+
+2. Navigate to your `<Magento2_installation>/app/code/` directory.
+
+3. Copy or symlink the `Example` directory from your local `pagebuilder-examples` clone into your `app/code/` directory.
+    
+    **To Symlink**:
+    ```bash
+    ln -s <Relative_route_to_cloned_Example_directory>
+    ```
+    
+    ![Examples installation directory](../images/examples-install-location.png)
+    
+4. Enable the modules using the `setup:upgrade` command:
+
+   ```bash
+   bin/magento setup:upgrade
+   ```
+   
+5. Navigate to a Page Builder instance to ensure the example content types appear in the Page Builder panel, as shown here:
+
+   ![Content type examples shown in panel](../images/example-content-types.png)
+    
+
 ## Files for how-to topics
 
 The how-to directories in the repo correspond to the how-to topics in this documentation. They provide the files and code changes required by the how-to topic in order to add the given feature to the `PageBuilderQuote` module.

docs/getting-started/install-pagebuilder.md

@@ -1,22 +1,14 @@
 # Install Page Builder
 
-How you install the pre-release version of Page Builder depends on whether you are a member of the Early Adopters Program (EAP):
+Page Builder is automatically installed with Magento Commerce 2.3.1. There is nothing else you need to do. However, If you want to contribute to the Page Builder code or documentation, you can use the GitHub installation as follows.
 
-- **All Partners** (not EAP members) must use the [GitHub installation](#githubInstructions).
-- **EAP Members** can install using the [Composer installation](#composerInstallation).
+## GitHub installation for Contributors
 
-## Prerequisite for both installations
+Before installing Page Builder for making contributions, make sure you have the following prerequisites:
 
-Magento Commerce 2.3+ -- Use the installation instructions from the [DevDocs installation guide](https://devdocs.magento.com/guides/v2.3/install-gde/bk-install-guide.html). 
-
-## **All Partners**: GitHub Installation {#githubInstructions}
-
-Partners who are not members of the Early Adopters Program (EAP) must install the pre-release version of Page Builder by cloning the Page Builder GitHub repository (https://github.com/magento/magento2-page-builder) into a development instance of Magento. 
-Before installing Page Builder, make sure you have:
-
-* A local development installation of Magento Commerce 2.3+
-* Access to the Page Builder repository
-* [npm package manager](https://www.npmjs.com/get-npm)
+- A local development installation of Magento Commerce 2.3.1 -- Use the installation instructions from the [DevDocs installation guide](https://devdocs.magento.com/guides/v2.3/install-gde/bk-install-guide.html). 
+- Access to the private Page Builder repository
+- [npm package manager](https://www.npmjs.com/get-npm)
 
 1. Clone the Page Builder repos into the root directory of your Magento Commerce 2.3+ installation:
 
@@ -31,9 +23,9 @@ Before installing Page Builder, make sure you have:
     php dev/tools/build-ee.php --command=link --ee-source="magento2-page-builder" --ce-source="."
     php dev/tools/build-ee.php --command=link --ee-source="magento2-page-builder-ee" --ce-source="."
     ```
-    
+
     The results should look like this:
-    
+
     ![Symlinks to Page Builder](../images/symlinked-pagebuilder.png)
 
 3. Enable the Page Builder module using the following command:
@@ -57,45 +49,3 @@ cd pagebuilder && npm install
 ```
 
 After installing the npm packages, you can run `npm run start`. This command watches for changes to your TypeScript files, compiles, and checks for errors.
-
-## **EAP Participants Only**: Composer Installation {#composerInstallation}
-
-To use the Composer installation described below, you must be an active member in the Page Builder EAP program and have submitted your MAGEID to get access to the Page Builder Composer packages through `repo.magento.com`. 
-If you are experiencing problems _as an EAP member_, please contact us at `pagebuilderEAP@adobe.com`.
-
-{: .bs-callout .bs-callout-info }
-If you already have Magento 2.3.0 or Page Builder installed, clear your composer cache (`composer clearcache`) before you install the latest packages.
-
-1. Ensure your composer has `minimum-stability` set to `beta`:
-
-    ```bash
-    composer config minimum-stability beta
-    ```
-
-2. Navigate to the root of the project and require the `magento/module-page-builder-commerce` package:
-
-    ```bash
-    composer require magento/page-builder-commerce:^1.0.0
-    ```
-    
-3. Enable the module within Magento:
-
-    ``` bash
-    bin/magento setup:upgrade
-    ```
-    
-4. Activate Page Builder from the Admin UI as described in [Activate Page Builder](../how-to/how-to-deactivate-pagebuilder.md).
-
-### Updating Composer installation
-
-You can install updates by completing a `composer update` within your project.
-
-### Composer installation issues
-
-If you run into the following issue:
-
-```shell
-Could not find a matching version of package magento/page-builder-commerce. Check the package spelling, your version constraint and that the package is available in a stability which matches your minimum-stability (stable).
-```
-
-Please ensure the credentials you're using to connect with `repo.magento.com` belong to the MAGEID you provided when you signed up to the EAP program.

docs/how-to/how-to-add-appearance.md

@@ -1,3 +1,9 @@
 # How to add an appearance
 
+This topic describes how to add a new appearance to a content type so that you can give end-users the custom features they require when creating content.
+
+![How to add an appearance](../images/how-to-add-appearance.svg)
+
+## Step 1: Add appearance to config file
+
 In progress...

docs/how-to/how-to-add-storefront-widget.md

@@ -1,9 +1,8 @@
 # How to add a storefront widget
 
-A storefront widget is a JavaScript component that handles the behavior of a content type after Page Builder renders it on the storefront. 
-For example, the Tabs and Sliders have their own storefront widgets to handle the end-user's tapping of tabs and swiping of slides on the storefront.
-However, Page Builder also executes storefront widgets on the Admin stage for block and dynamic block content types. 
-This allows end-users to preview how Page Builder will render the blocks and dynamic blocks on the storefront.
+A storefront widget is a JavaScript component that handles the behavior of a content type after Page Builder renders it on the storefront. For example, the Tabs and Sliders have their own storefront widgets to handle the end-user's tapping of tabs and swiping of slides on the storefront.
+
+However, Page Builder also executes storefront widgets on the Admin stage for block and dynamic block content types. This allows end-users to preview how Page Builder will render the blocks and dynamic blocks on the storefront. 
 
 Adding a storefront widget to your content type is a simple two-step process: