diff --git a/.gitignore b/.gitignore
index b4aff53859..b60b3f5527 100644
--- a/.gitignore
+++ b/.gitignore
@@ -122,4 +122,5 @@ src/frontend/sass
 go-vendor-*.tgz
 
 website/build
-website/site-dist
\ No newline at end of file
+website/site-dist
+website/.docusaurus
diff --git a/docs/issue_template.md b/docs/issue_template.md
index 0cebba37fc..c8b8913393 100644
--- a/docs/issue_template.md
+++ b/docs/issue_template.md
@@ -26,11 +26,11 @@
 
 ### Actual behaviour
 
-### Steps to reproduce the behaviour
+### Steps to reproduce the behavior
 
 ### Log output covering before error and any error statements
 ```
-Insert your log here
+Insert log hereCopy
 ```
 
 
diff --git a/docs/pull_request_template.md b/docs/pull_request_template.md
index e651b7af6d..11568562b2 100644
--- a/docs/pull_request_template.md
+++ b/docs/pull_request_template.md
@@ -1,3 +1,9 @@
+---
+id: pull_request_template
+title: Pull request template for contributions to Stratos
+sidebar_label: PR template 
+---
+
 <!--- Provide a general summary of your changes in the Title above -->
 
 ## Description
diff --git a/src/frontend/packages/example-theme/_index.scss b/src/frontend/packages/example-theme/_index.scss
index a8d3f300e1..b837542374 100644
--- a/src/frontend/packages/example-theme/_index.scss
+++ b/src/frontend/packages/example-theme/_index.scss
@@ -2,8 +2,60 @@
 
 // Custom Theme
 @import './sass/custom';
+@import './sass/custom/acme-colors';
+
+// Style overrides
+@import './sass/custom/acme';
 
 @function stratos-theme() {
   $theme: stratos-theme-helper($stratos-theme);
-  @return $theme
-}
\ No newline at end of file
+  @return (
+    default: create-custom-theme($stratos-theme),
+    dark: create-dark-theme()
+  );
+}
+
+@function create-custom-theme($base-theme) {
+  $theme: stratos-theme-helper($base-theme);
+
+  // Modify some of the colors
+  $app-theme: map-get($theme, app-theme);
+  $app-theme: map-merge($app-theme, (
+    header-background-color: $acme-text,
+    header-foreground-color: $acme-dark-gray,
+    header-background-span: false,
+    stratos-title-show-text: true,
+    user-avatar-background-color: $acme-text,
+    user-avatar-foreground-color: $acme-primary-color,
+    user-avatar-header-invert-colors: false,
+    side-nav: (
+      background: $acme-dark-gray,
+      text: $acme-text-gray,
+      active: $acme-side-nav-active,
+      active-text: $acme-text-gray,
+      hover: $acme-side-nav-active,
+      hover-text: $acme-text-gray
+    )
+  ));
+
+  $theme: map-merge($theme, (
+    app-theme: $app-theme
+  ));
+
+  @return $theme;
+}
+
+@function create-dark-theme() {
+  $theme: create-custom-theme($stratos-dark-theme);
+
+  $app-theme: map-get($theme, app-theme);
+  $app-theme: map-merge($app-theme, (
+    header-background-color: $acme-dark-gray,
+    header-foreground-color: $acme-text,
+  ));
+
+  $theme: map-merge($theme, (
+    app-theme: $app-theme
+  ));
+  @return $theme;
+}
diff --git a/src/frontend/packages/example-theme/assets/core/nav-logo.png b/src/frontend/packages/example-theme/assets/core/nav-logo.png
new file mode 100644
index 0000000000..397545f790
Binary files /dev/null and b/src/frontend/packages/example-theme/assets/core/nav-logo.png differ
diff --git a/src/frontend/packages/example-theme/package.json b/src/frontend/packages/example-theme/package.json
index 704b682b04..f2006d3cc3 100644
--- a/src/frontend/packages/example-theme/package.json
+++ b/src/frontend/packages/example-theme/package.json
@@ -6,7 +6,7 @@
       "assets/core": "core/assets",
       "assets/favicon.ico": "favicon.ico"
     },
-    "theme":{
+    "theme": {
       "loadingCss": "loader/loading.css",
       "loadingHtml": "loader/loading.html"
     }
diff --git a/src/frontend/packages/example-theme/sass/custom.scss b/src/frontend/packages/example-theme/sass/custom.scss
index e3eb84c38a..68fa1ded70 100644
--- a/src/frontend/packages/example-theme/sass/custom.scss
+++ b/src/frontend/packages/example-theme/sass/custom.scss
@@ -14,5 +14,3 @@ $stratos-dark-theme: mat-dark-theme($acme-theme-primary, $acme-theme-primary, $a
 
 // Default Theme
 $stratos-theme: mat-light-theme($acme-theme-primary, $acme-theme-primary, $acme-theme-warn);
-
-@import 'custom/acme';
diff --git a/src/frontend/packages/example-theme/sass/custom/acme-colors.scss b/src/frontend/packages/example-theme/sass/custom/acme-colors.scss
index 878c2cda32..6da6321206 100644
--- a/src/frontend/packages/example-theme/sass/custom/acme-colors.scss
+++ b/src/frontend/packages/example-theme/sass/custom/acme-colors.scss
@@ -1,3 +1,5 @@
+// These colors need tidying, some aren't used
+
 $acme-primary: #00c081;
 $acme-secondary: #00243e;
 $acme-text: #fff;
@@ -5,3 +7,17 @@ $acme-text-gray: #ccc;
 $acme-button-gray: #888;
 $acme-dark-blue: #06253a;
 $acme-blue: #073155;
+
+// Acme Brand primary colour
+$acme-primary-color: #035a97;
+
+// Secondary blue colour
+$acme-secondary: #035a97;
+$acme-text: #fff;
+$acme-text-gray: #ccc;
+$acme-dark-blue: #06253a;
+$acme-blue: #073155;
+$acme-side-nav: $acme-secondary;
+$acme-side-nav-active: #003358;
+
+$acme-dark-gray: #333
diff --git a/src/frontend/packages/example-theme/sass/custom/acme.scss b/src/frontend/packages/example-theme/sass/custom/acme.scss
index 75794ebb6e..e4c53f3cbf 100644
--- a/src/frontend/packages/example-theme/sass/custom/acme.scss
+++ b/src/frontend/packages/example-theme/sass/custom/acme.scss
@@ -1,71 +1,11 @@
-// Style overrides
-// Acme Brand primary colour
-$acme-primary-color: #035a97;
+@import './acme-colors';
 
-// Secondary blue colour
-$acme-secondary: #035a97;
-$acme-text: #fff;
-$acme-text-gray: #ccc;
-$acme-dark-blue: #06253a;
-$acme-blue: #073155;
-$acme-side-nav: $acme-secondary;
-$acme-side-nav-active: #003358;
+// Style overrides
 
 body.stratos {
-  app-page-subheader {
-    .page-subheader {
-      background-color: #fff;
-      color: #333;
-    }
-  }
-
-  .page-header__divider {
-    color: #333;
-  }
-
-  .page-header__menu-button-icon {
-    background-color: $acme-primary-color;
-    color: $acme-text;
-  }
-
-  .mat-tab-nav-bar.mat-primary.mat-background-primary {
-    .mat-tab-links {
-      background-color: #fff;
-      color: #333;
-    }
-    .mat-tab-link {
-      color: #333;
-    }
-    .mat-ink-bar {
-      background-color: $acme-primary-color;
+  .favorite-list {
+    .app-no-content-container {
+      color: $acme-dark-blue;
     }
   }
-
-  .stratos-title__logo {
-    width: 160px;
-  }
-
-  .page-header .mat-toolbar.mat-primary {
-    background-color: #fff;
-    color: #333;
-  }
-
-  // Use Acme Blue Side Navigation
-  .side-nav,
-  .side-nav__top,
-  .side-nav__item--active:hover {
-    background-color: $acme-side-nav;
-  }
-  .side-nav__item--active,
-  .side-nav__item:hover {
-    background-color: $acme-side-nav-active;
-  }
-  .side-nav__bottom {
-    color: $acme-text-gray;
-  }
-
-  // Show the text Stratos beneath the Acme logo
-  .stratos-title > .stratos-title__header {
-    display: inline-block;
-  }
 }
diff --git a/website/docs/extensions/backend.md b/website/docs/extensions/backend.md
index 904880c895..59e54cef44 100644
--- a/website/docs/extensions/backend.md
+++ b/website/docs/extensions/backend.md
@@ -18,9 +18,9 @@ Currently, to create an extension to the backend:
 
 1. Build Jetstream
 
-> Note: There are a few plugins in the `src/jetstream/plugins` folder that should help serve as examples of how to write a plugin.
+> There are a few plugins in the `src/jetstream/plugins` folder that should help serve as examples of how to write a plugin.
 
-> Note: Jetstream uses the [Echo web server](https://echo.labstack.com/) from Labstack - some familiarity with this is required when developing backend plugins.
+> Jetstream uses the [Echo web server](https://echo.labstack.com/) from Labstack - some familiarity with this is required when developing backend plugins.
 ## Plugin Interface
 
 All plugins must implement the interface `interfaces.StratosPlugin` - this is defined in `src/jetstream/repository/interfaces/plugin.go`.
diff --git a/website/docs/extensions/customizing.md b/website/docs/extensions/customizing.md
deleted file mode 100644
index b85b0dde1c..0000000000
--- a/website/docs/extensions/customizing.md
+++ /dev/null
@@ -1,154 +0,0 @@
----
-id: customizing
-title: Customizing Stratos 
-sidebar_label: Customizing Stratos 
----
-
-
-> This document is out of date and is in the process of being refreshed.
-
-## Approach
-
-In order to customize Stratos, you will need to fork the Stratos GitHub repository and apply customizations in your fork. Our aim is to minimize any merge conflicts that might occur when re-basing your fork with the upstream Stratos repository.
-
-<!-- All customizations are placed within a top-level folder named `custom-src`. This folder should only exist in forks and will not exist in the main Stratos repository, so any changes made within this folder should be free from merge conflicts. -->
-Customizations are placed in angular packages in the folder named `src/frontend/packages`. In the future you will be able to host these packages in npm and bring them into Stratos in the usual npm dependency way.
-
-Each package should contain custom Stratos configuration in it's package.json pointing to the modules it will be required to import. 
-
-stratos.yaml
-custom theme
-custom styles
-custom assets
-
-
-The Stratos approach to customization uses symbolic links. We maintain a default set of resources in the folder `src/misc/custom`. When you run `npm install` or when you explicitly run `npm run customize`, a gulp task (in the file `build/fe-build.js`) runs and creates symbolic links, linking the required files to their expected locations withing the `src` folder.
-
-If a required file exists in the `custom-src` folder location, the build script will link this file, otherwise, it will link the default resource from `src/misc/custom`.
-
-Normally, you do not need to run any scripts to apply customizations - they will be applied as part of a `postinstall` script that runs automatically when you do an `npm install`. You can manually run the following scripts if you update or change the customizations:
-
-- `npm run customize` - creates symbolic links for the required files, looking at the provided customizations and then falling back to default files
-
-- `npm run customize-default` - creates symbolic links for the required files, ignoring any provided customizations and using the default files
-
-- `npm run customize-reset` - remove all symbolic links. If you build after running this command you will see errors, as required files are not present.
-
-### Customizing Images
-
-The following image resources can be changed by creating the specified file in the folder shown:
-
-|File name|Folder|Description|
-|---|---|---|
-|favicon.ico|custom-src/frontend|Favorite icon to use|
-|logo.png|custom-src/frontend/assets|Logo to use on login screen and about page|
-|nav-logo.png|custom-src/frontend/assets|Logo to use in the top-left side navigation for the application logo|
-|login-bg.jpg|custom-src/frontend/assets|Image to use for the login page background|
-
-> NOTE: The `nav-logo.png` logo should have a height of 36px and a maximum width of 180 pixels.
-
-### Customizing the Theme
-
-Stratos uses Material Design and the [angular-material](https://material.angular.io/) library. It uses the same approach to theming.
-
-To create your own theme, create the file `custom.scss` in the folder `custom-src/frontend/sass`.
-
-In this file you can set any or all of the following variables:
-
-|Variable|Purpose|
-|---|---|
-|$stratos-theme|The main theme to use for Stratos|
-|$stratos-nav-theme|Theme to use for the side navigation panel|
-|$stratos-status-theme|Theme to use for displaying status in Stratos|
-
-Note that you do not have to specify all of these - defaults will be used if they are not set.
-
-In most cases you will probably want to generate a palette for the primary color for your version of Stratos - an example `custom.scss` this for this is shown below:
-
-```
-$suse-green: ( 50: #E0F7F0, 100: #B3ECD9, 200: #80E0C0, 300: #4DD3A7, 400: #26C994, 500: #00C081, 600: #00BA79, 700: #00B26E, 800: #00AA64, 900: #009C51, A100: #C7FFE0, A200: #94FFC4, A400: #61FFA8, A700: #47FF9A, contrast: (50: #000000, 100: #000000, 200: #000000, 300: #000000, 400: #ffffff, 500: #ffffff, 600: #ffffff, 700: #ffffff, 800: #ffffff, 900: #ffffff, A100: #000000, A200: #000000, A400: #000000, A700: #000000 ));
-
-$suse-red: ( 50: #ffebee, 100: #ffcdd2, 200: #ef9a9a, 300: #e57373, 400: #ef5350, 500: #f44336, 600: #e53935, 700: #d32f2f, 800: #c62828, 900: #b71c1c, A100: #ff8a80, A200: #ff5252, A400: #ff1744, A700: #d50000, contrast: ( 50: $black-87-opacity, 100: $black-87-opacity, 200: $black-87-opacity, 300: $black-87-opacity, 400: $black-87-opacity, 500: white, 600: white, 700: white, 800: $white-87-opacity, 900: $white-87-opacity, A100: $black-87-opacity, A200: white, A400: white, A700: white, ));
-
-// Create palettes
-$suse-app-primary: mat-palette($suse-green);
-$suse-theme-warn: mat-palette($suse-red);
-
-// Create a theme from the palette (secondary theme is the same as the primary in this example)
-$suse-app-theme: mat-light-theme($suse-app-primary, $suse-app-primary, $suse-theme-warn);
-
-// Set this theme as the one to use
-$stratos-theme: $suse-app-theme;
-```
-
-#### Creating or disabling the Dark theme
-
-You can also change the Dark theme, if you wish, by defining the following variables:
-
-|Variable|Purpose|
-|---|---|
-|$stratos-dark-theme|The dark theme to use for Stratos|
-|$stratos-dark-nav-theme|Dark theme to use for the side navigation panel|
-|$stratos-dark-status-theme|Dark theme to use for displaying status in Stratos|
-
-Note that minimally you must supply `stratos-dark-theme` to create a dark theme.
-
-By default a dark theme is assumed to be available and the default will be used if not overridden. You can disable dark theme support in the UI by setting the following variable in your `custom.scss`:
-
-```
-$stratos-dark-theme-supported: false;
-```
-
-### Changing Styles
-
-We don't generally recommend modifying styles, since from version to version of Stratos, we may change the styles used slightly which can mean any modifications you made will need updating. Should you wish to do so, you can modify these in the same `custom.scss` file that is used for theming.
-
-As an example, to disable the login background image, add the following to `custom.scss`:
-
-```
-.stratos .intro {
-  background-image: none;
-}
-```
-
-Note that the class `stratos` has been placed on the `BODY` tag of the Stratos application to assist with css selector specificity.
-
-### Adding new Features
-
-Code for new features should be placed within the `custom-src/frontend/app/custom` folder. You can create any sub-folder structure within this folder.
-
-When you perform an `npm install` or explicitly run `npm run customize`, the customize script is run and will symlink the folder `custom-src/frontend/app/custom` to `src/frontend/app/custom`. It will also create a module to import your custom code - this is placed in the file `src/frontend/app/custom/custom-import.module.ts`. You should _not_ edit this file.
-
-Within the `custom-src/frontend/app/custom` folder you must create a module in the file `custom.module.ts` named `CustomModule` - this will be imported into the Stratos application and is the mechanism by which you can add custom code to the front-end.
-
-We currently expose the following extension points in Stratos:
-
-- Changing the component to use for the login screen
-- Adding new items to the side navigation menu
-- Adding new tabs to the Application, Cloud Foundry, Organization and Space views
-- Adding new action buttons to the Application Wall, Application, Cloud Foundry, Organization and Space and Endpoint views
-
-We use Decorators to annotate components to indicate that they are Stratos extensions.
-
-See [Extensions](../extensions/frontend) for more detail and examples of front-end extensions.
-
-
-### Changing the Initial Loading Indicator
-
-On slower connections, it can take a few seconds to load the main Javascript resources for Stratos.
-
-In order to give the user some initial feedback that Stratos is loading, a loading indicator is included in the `index.html` file. This gets shown as early as possible, as soon as this main html file has loaded. Once the main code has been fetched, the view refreshes to show the application.
-
-A default loading indicator is provided that can be changed. To do so, create the following two files:
-
-- `custom-src/frontend/loading.css` - CSS styles to be included in a style block in the head of the index page
-- `custom-src/frontend/loading.html` - HTML markup to be included the the index page to render the loading indicator
-
-The files for the default indicator can be found in the `src/frontend/packages/core/misc/custom` folder.
-
-An example of a different loading indicator is included with the ACME sample in `examples/custom-src/frontend`.
-
-The customization task will insert the appropriate CSS and HTML files into the main index.html file when it runs.
-
-Take a look at the template for the `index.html` file in `src/frontend/packages/core/misc/custom/index.html`. The CSS file is inserted where the marker `/** @@LOADING_CSS@@ **/` is and the HTML file where `<!-- @@LOADING_HTML@@ -->` is.
-
diff --git a/website/docs/extensions/introduction.md b/website/docs/extensions/introduction.md
index 7dddc6e520..b36474090c 100644
--- a/website/docs/extensions/introduction.md
+++ b/website/docs/extensions/introduction.md
@@ -2,4 +2,60 @@
 title: Extending Stratos
 sidebar_label: Introduction
 ---
-This document is in progress
\ No newline at end of file
+
+Stratos can be customized in a number of ways. Colors and fonts can be updated to add unique branding, additional menu items can be added in a number of places, custom EULAs can be used, new Stratos Jetstream (backend) endpoints, and much more.
+
+> For those with existing customization migrating to 4.0 please see our [upgrade guide](/docs/extensions/v4-migration).
+
+## Approach
+
+In order to customize Stratos, you will need to fork the Stratos GitHub repository and apply customizations in your fork. Our aim is to minimize any merge conflicts that might occur when re-basing your fork with the upstream Stratos repository.
+
+### Frontend
+
+Frontend customizations are placed in angular packages in the folder named `src/frontend/packages`. In the future you will be able to host these packages in npm and bring them into Stratos in the usual npm dependency way. There are no additional processes or build steps required for Stratos to then integrate these packages. All steps will be automatically applied under the hood during `npm install` and when `ng build`/`ng serve` runs.
+
+Information on custom theming can be found in the [theming page](/docs/extensions/theming).
+
+Information on additional functionality can be found in the [extensions page](/docs/extensions/frontend).
+
+### Backend (Jetstream)
+
+Jetstream customizations are written in go and can be added in `src/jetstream/plugins`. In the future we hope to combine this work with the frontend changes, such that all functionality for
+a feature can be applied to Stratos in a similar way.
+
+More information can be found in the [custom plugins page](/docs/extensions/backend).
+
+## Examples
+
+### ACME
+The ACME example contains a number of [theming](https://github.com/cloudfoundry/stratos/tree/master/src/frontend/packages/example-theme) and [functionality](https://github.com/cloudfoundry/stratos/tree/master/src/frontend/packages/example-extensions) customization.
+
+To run Stratos with these customizations
+
+1. Include the example packages (by default these are excluded). Do this by...
+   1. Creating the file `stratos.yaml` in the root of the repo
+   2. Adding the following content to `stratos.yaml`
+      ```
+      packages:
+        include:
+          - '@stratosui/core'
+          - '@stratosui/shared'
+          - '@stratosui/store'
+          - '@stratosui/cloud-foundry'
+          - '@stratosui/cf-autoscaler'
+          - '@stratosui/theme'
+          - '@example/extensions'
+          - '@example/theme'
+      ```
+1. Run Stratos the usual way, for more information see the [Developer Guide](/docs/developer/introduction).
+
+### SUSE
+
+More advanced, real world examples can be found the in SUSE Stratos repository, again containing [theming](https://github.com/SUSE/stratos/tree/master/src/frontend/packages/suse-theme) and [functionality](https://github.com/SUSE/stratos/tree/master/src/frontend/packages/suse-extensions) customizations.
+
+To run Stratos with these customizations simply start the console the usual way from that repo, for more information see the [Developer Guide](/docs/developer/introduction).
+
+## Further Reading
+
+Detailed instructions on how to customize the [theme](/docs/extensions/theming), [frontend functionality](/docs/extensions/frontend) and [backend](/docs/extensions/backend) can be found in this section.
diff --git a/website/docs/extensions/theming.md b/website/docs/extensions/theming.md
index 2f9e72c21f..50d26d74da 100644
--- a/website/docs/extensions/theming.md
+++ b/website/docs/extensions/theming.md
@@ -2,13 +2,257 @@
 title: Theming Stratos
 sidebar_label: Theming Stratos
 ---
-This document is in progress
 
 Stratos provides a mechanism for customizing the theme, including:
 
-- Changing the theme colors
+- Changing colors
 - Changing image assets (favorite icon, login background and logo)
-- Overriding styles
-- Changing the initial loading indicator
+- Using additional fonts
+- Adding/Overriding styles
+- Applying theme colors to components
 
-The easiest way to create a theme is to create a folder in the `src/frontend/packages` folder.
\ No newline at end of file
+Theme's are best encapsulated in a new npm package. It should contain the usual `package.json` file with a `stratos` section which will contain some of the theme customizations.
+
+An example of the type of package that can be created can be found in the [ACME example](https://github.com/cloudfoundry/stratos/tree/master/src/frontend/packages/example-theme). To run Stratos with these customizations see [here](/docs/extensions/introduction#acme).
+
+## Colors
+Stratos uses Material Design and the [angular-material](https://material.angular.io/) library and uses the same approach to theming.
+
+To create your own theme you will need to create a color pallet and provide it to Stratos as a material theme. This theme can also contain
+additional colors that customize core parts of the page (header, side navigator menu, avatar, etc).
+
+To do this create the file `_index.scss` in the root of your theme package. This should contain a Stratos scss function that will return a `theme`
+object via the Stratos helper function `stratos-theme-helper`, for [example](https://github.com/cloudfoundry/stratos/blob/master/src/frontend/packages/example-theme/_index.scss). 
+
+### Core Pallet
+In most cases you will probably want to generate a palette for the primary color for your version of Stratos - an example `custom.scss` for this is shown below:
+
+```
+$acme-primary: (50: #e8eaf6, 100: #c5cbe9, 200: #9fa8da, 300: #7985cb, 400: #5c6bc0, 500: #3f51b5, 600: #394aae, 700: #3140a5, 800: #29379d, 900: #1b278d, A100: #c6cbff, A200: #939dff, A400: #606eff, A700: #4757ff, contrast: (  50: #000000,  100: #000000,  200: #000000,  300: #000000,  400: #ffffff,  500: #ffffff,  600: #ffffff,  700: #ffffff,  800: #ffffff,  900: #ffffff,  A100: #000000,  A200: #000000,  A400: #ffffff,  A700: #ffffff, ));
+$mat-red: ( 50: #ffebee, 100: #ffcdd2, 200: #ef9a9a, 300: #e57373, 400: #ef5350, 500: #f44336, 600: #e53935, 700: #d32f2f, 800: #c62828, 900: #b71c1c, A100: #ff8a80, A200: #ff5252, A400: #ff1744, A700: #d50000, contrast: ( 50: $black-87-opacity, 100: $black-87-opacity, 200: $black-87-opacity, 300: $black-87-opacity, 400: $black-87-opacity, 500: white, 600: white, 700: white, 800: $white-87-opacity, 900: $white-87-opacity, A100: $black-87-opacity, A200: white, A400: white, A700: white, ));
+
+// Create palettes
+$acme-theme-primary: mat-palette($acme-primary);
+$acme-theme-warn: mat-palette($mat-red);
+
+// Create a theme from the palette (secondary theme is the same as the primary in this example)
+$stratos-theme: mat-light-theme($acme-theme-primary, $acme-theme-primary, $acme-theme-warn);
+
+// Create a similar theme but make it for dark mode
+$stratos-dark-theme: mat-dark-theme($acme-theme-primary, $acme-theme-primary, $acme-theme-warn);
+
+```
+
+### Stratos Colors
+
+Additional Stratos colors can be customized by supplying more colors to the `theme` object. Defining these colors helps reduce the amount of custom css the theme has to use.
+
+> You do not have to specify all of these - defaults will be used if they are not set.
+
+|Property|Description|
+|---|---|
+|app-background-color| Base color to show in the background of the application |
+|app-background-text-color| Color of text when placed on the basic background |
+|side-nav| See [below](/docs/extensions/theming#side-nav-colors) |
+|status| See [below](/docs/extensions/theming#status-colors)|
+|subdued-color| Lighter color meant to be a subdued version of the primary color |
+|ansi-colors| See [below](/docs/extensions/theming#ansi-colors)|
+|header-background-color| Background color for the main stratos header|
+|header-foreground-color| Foreground color for the main stratos |
+|stratos-title-show-text| Boolean - Show `Stratos` or provided title with the large logo in the about page, default log in page, etc |
+|header-background-span|Does the header background color span across the top, or is the sidenav background color used for the top-left portion|
+|underflow-background-color|Background colors to use for things like the about page header (underflow)|
+|underflow-foreground-color|Background colors to use for things like the about page header (underflow)|
+|link-color| Color for hyperlinks|
+|link-active-color| Color of visited hyperlinks|
+|user-avatar-background-color| Background color of the default avatar in the main header|
+|user-avatar-foreground-color| Foreground color of the default avatar in the main header|
+|user-avatar-underflow-invert-colors| Boolean - Invert the user-avatar colors|
+|user-avatar-header-invert-colors| Boolean - Invert the user-avatar colors in the main header|
+|intro-screen-background-color| Color of the background to introduction style screens (log in, log out, etc)|
+
+
+#### Side Nav Colors
+Colors that define how the top level navigation menu on the left of Stratos appears.
+
+|Property|Description|
+|---|---|
+|background| Background color of the side nav|
+|text| Color of text when menu item is not selected|
+|active| Color of background of a selected item|
+|active-text| Color of text of a selected item|
+|hover| Color of background of an item when hovered on|
+|hover-text| Color of text of an item when hovered on|
+
+#### Status Colors
+Colors that are associated with the standard levels of statuses.
+
+|Property|Description|
+|---|---|
+|success||
+|info||
+|warning||
+|danger||
+|tentative||
+|busy||
+|text||
+
+#### Ansi Colors
+Terminal style set of colors to show for logging output.
+
+|Property|Description|
+|---|---|
+|default-foreground||
+|default-background||
+|black||
+|red||
+|green||
+|yellow||
+|blue||
+|magenta||
+|cyan||
+|white||
+
+
+### Dark theme
+
+By default the theme will not contain a dark mode and the UX for enabled/disabling it will be hidden.
+
+In order to add a dark mode to your theme an additional `dark` color theme should be provided by the `stratos-theme` theme function in your
+theme's `_index.scss`, for example 
+in [_index.scss](https://github.com/cloudfoundry/stratos/blob/master/src/frontend/packages/example-theme/_index.scss).
+
+```
+@function stratos-theme() {
+  $theme: stratos-theme-helper($stratos-theme);
+  @return (
+    default: create-custom-theme($stratos-theme),
+    dark: create-dark-theme()
+  );
+}
+```
+
+Within the dark theme the default theme's additional Stratos colors can be overwritten.
+
+
+## Images
+
+### Replace Stratos Images
+
+
+
+
+Images that Stratos uses can be overwritten by a theme, for example the logo and favicon. To do so the new images should be added to the
+package and then referenced in the theme's `package.json` including the path of the image they overwrite. Below are some prominent examples.
+
+
+|File name|Path|Description|
+|---|---|---|
+|`favicon.ico`|`favicon.ico`|Favorite icon to use|
+|`logo.png`|`core/assets/logo.png`|Logo to use on login screen and about page|
+|`nav-logo.png`|`core/assets/nav-logo.png`|Logo to use in the top-left side navigation for the application logo|
+
+
+> The `nav-logo.png` logo should have a height of 36px and a maximum width of 180 pixels.
+
+> Files written to `core/assets` should be done in one line. In the example below both logo.png and nav-logo.png and done via the one
+> line
+
+Example `package.json`
+
+```
+  "stratos": {
+    ...
+    "assets": {
+      "assets/core": "core/assets",
+      "assets/favicon.ico": "favicon.ico",
+    },
+    ...
+  },
+```
+
+### New Images
+
+When images are used by custom components they should also be referenced in the theme's `package.json`. Whole folders can be included and should
+be written to `core/assets`. When references by the components they use that path `src="/core/assets/custom_image.png"`
+
+```
+  "stratos": {
+    ...
+    "assets": {
+      "local/assets": "core/assets",
+    },
+    ...
+  },
+```
+
+## Fonts
+Any custom fonts used by the theme or extensions can be provided in a similar way to images, the files should be added to the theme's package
+and then referenced in the theme's `package.json`.
+
+```
+  "stratos": {
+    "assets": {
+      ...
+      "assets/fonts": "suse/fonts"
+      ...
+  },
+```
+
+## Styles
+
+We don't generally recommend modifying styles, since from version to version of Stratos, we may change the styles used slightly which can mean any modifications you made will need updating. Should you wish to do so, you can modify these in the same `_index_.scss`. For example the Acme[_index.scss](https://github.com/cloudfoundry/stratos/blob/master/src/frontend/packages/example-theme/_index.scss) imports a file that adds a text color 
+
+```
+body.stratos {
+  .favorite-list {
+    .app-no-content-container {
+      color: $acme-dark-blue;
+    }
+  }
+}
+```
+
+Note that the class `stratos` has been placed on the `BODY` tag of the Stratos application to assist with css selector specificity.
+
+## Components
+
+Angular components in your packages can be themed, which provides them access to the theme's colors. To do this, in your extensions package that contains the components (this may be different to your theme package), add a `_all-theme.scss` file containing a scss function. This function
+should be referenced in the package's package.json and is called by the Stratos extension mechanism.
+
+The `_all-theme.scss` and `package.json` content may look like below
+
+```
+@mixin apply-theme-suse-extensions($stratos-theme) {
+
+  $theme: map-get($stratos-theme, theme);
+  $app-theme: map-get($stratos-theme, app-theme);
+
+}
+```
+
+```
+  "stratos": {
+    ...
+    "theming": "sass/_all-theme#apply-theme-suse-extensions",
+    ...
+  }
+```
+
+Component theme files can then be defined and their own scss functions being called from `_all-theme.scss`
+
+```
+@mixin apply-theme-suse-extensions($stratos-theme) {
+  ...
+  @include kube-analysis-report-theme($theme, $app-theme);
+  ...
+}
+```
+
+```
+@mixin kube-analysis-report-theme($theme, $app-theme) {
+  $backgrounds: map-get($theme, background);
+  $background: mat-color($backgrounds, card);
+  $background-color:  map-get($app-theme, app-background-color);
+}
+```
diff --git a/website/docs/extensions/v4-migration.md b/website/docs/extensions/v4-migration.md
index 24aeb83da7..9ec035b6b6 100644
--- a/website/docs/extensions/v4-migration.md
+++ b/website/docs/extensions/v4-migration.md
@@ -3,28 +3,44 @@ title: Migrating to V4
 sidebar_label:  Migrating to V4
 ---
 
-In version 4 of Stratos there are breaking customization changes from previous versions.
+In version 4 of Stratos there are breaking customization changes from previous versions. These changes allow a much improved approach to
+extensions by opening the door to npm style plugins. 
 
-These changes allow a much improved approach to extensions by opening the door to npm style plugins.
+Prominent changes include
+- `custom-src` has been removed along with the symlink approach of including files. Custom code is now added as npm packages in `src/frontend/packages`.
+Modules and routes are now exposed in a more standard package way. More info [here](/docs/extensions/frontend#including-modules-and-routes).
+Some existing components will not be included in some production style builds without also declaring them to the extension service, see 
+usages of `ExtensionService.declare`.
+- Material Design theming approach has been expanded to include many common colors, this removes the need to apply custom styles in a lot of cases. More info [here](/docs/extensions/theming#colors).
+- Dark theme is applied in a different way. More info [here](/docs/extensions/theming#dark-theme).
+- Image assets are replaced in a different way. More info [here](/docs/extensions/theming#images).
+- Custom component can now be themed, so theme colors can be accessed from within and applied. More info [here](/docs/extensions/theming#components).
+- A new 'loading' indicator has been added that you may wish to customize, more info [here](/docs/extensions/frontend#loading-indicator).
 
+## Basic Migration Steps
 To aid in migrating we've provided these instructions.
 
 1. Before updating to the latest code...
     - Run `npm run customize-reset` to remove all previously created sym links.
     - Read through the customization documentation below to get a better understanding of the new process.
 1. Update your codebase with the desired v4 code.
-1. Run `npm install` (only required first time, this will ensure you have the required version of Angular).
+1. Run `npm install` (only required first time, this will ensure you have the required version of Angular and the new devkit is built).
 1. Change directory to `./build/tools/v4-migration` and run the migration script `./migrate.sh`.
     - This will copy your customizations from `custom-src` to a new Angular package `src/frontend/packages/custom_extensions`.
 1. Check that the new package exports your custom module and if applicable your custom-routing module.
     - The migrate script should do this in `src/frontend/packages/custom_extensions/src/public-api.ts`.
 1. Check that your ts config file defines the public api file.
     - `src/tsconfig.json` file's `compilerOptions/paths` section should contain something like `"@custom/extensions": ["frontend/packages/custom_extensions/src/public-api.ts"]`.
-1. Check that your new package's package.json defines your custom module and if application custom-routing module.
-    - See `src/frontend/packages/suse_extensions/package.json` file's `stratos` section.
+1. Check that your new package's `package.json` defines your custom module and if applicable custom-routing module.
+    - See `src/frontend/packages/suse-extensions/package.json` file's `stratos` section.
     - Note your `routingModule` entry label should not have a preceding `_`.
 1. Build Stratos in your usual way, for instance `npm run build`.
     - It could be that this fails due to TypeScript import issues, if so go through these and fix.
     - During build time the custom packages will be discovered and output, see section starting `Building with these extensions`. These should contain the modules your require.
 1. Run Stratos your usual way. Ensure you can navigate to all your custom parts.
 1. Once you are happy everything works as intended remove the old `./custom-src` directory and commit you changes.
+
+## Further Guidance
+Our ACME demo (`src/frontend/packages/example-extensions` and `src/frontend/packages/example-theme`) and SUSE repo ([theme](https://github.com/SUSE/stratos/tree/master/src/frontend/packages/suse-theme) and [extensions](https://github.com/SUSE/stratos/tree/master/src/frontend/packages/suse-extensions)) have both been updated and are fully compatible with the 4.0 changes. Both are a good source for examples.
+
+If there any questions or issues please reach out to us either on out Github [repo](https://github.com/cloudfoundry/stratos) or Slack room [#stratos](https://cloudfoundry.slack.com/?redir=%2Fmessages%2Fstratos).
diff --git a/docs/status_updates.md b/website/docs/status_updates.md
similarity index 100%
rename from docs/status_updates.md
rename to website/docs/status_updates.md
diff --git a/website/package.json b/website/package.json
index 93910f5342..d024da876c 100644
--- a/website/package.json
+++ b/website/package.json
@@ -4,6 +4,7 @@
   "private": true,
   "scripts": {
     "start": "docusaurus start",
+    "start-no-watch": "docusaurus start --no-open --poll",
     "build": "docusaurus build",
     "swizzle": "docusaurus swizzle",
     "deploy": "./deploy.sh"
diff --git a/website/sidebars.js b/website/sidebars.js
index 1afbc1327a..e286c79021 100644
--- a/website/sidebars.js
+++ b/website/sidebars.js
@@ -1,55 +1,54 @@
 module.exports = {
   docs: {
-	Documentation: ['introduction', 'overview', 'license'],
+    Documentation: ['introduction', 'overview', 'license'],
     'Deploying Stratos': [
-			'deploy/overview',
-    	{
-    		"Cloud Foundry": [
-    			'deploy/cloud-foundry/cloud-foundry',
-    			'deploy/cloud-foundry/db-migration',
-    			'deploy/cloud-foundry/cf-troubleshooting'
-    		],
-    	},
-    	{
-    		Kubernetes: [
-    			'deploy/kubernetes',
-    			'deploy/kubernetes/helm-installation' 
-    		],
-    	},
-    	'deploy/all-in-one',
-			'deploy/access',
-			'deploy/troubleshooting',
+      'deploy/overview',
+      {
+        "Cloud Foundry": [
+          'deploy/cloud-foundry/cloud-foundry',
+          'deploy/cloud-foundry/db-migration',
+          'deploy/cloud-foundry/cf-troubleshooting'
+        ],
+      },
+      {
+        Kubernetes: [
+          'deploy/kubernetes',
+          'deploy/kubernetes/helm-installation'
+        ],
+      },
+      'deploy/all-in-one',
+      'deploy/access',
+      'deploy/troubleshooting',
     ],
     'Advanced Topics': [
-			'advanced/invite-user-guide',
-			'advanced/sso',
-			'advanced/bosh-metrics'
-		],
-		'Development': [
-			'developer/contributing',
-			'developer/introduction',
-			{
-    			Frontend: [
-    				'developer/frontend',
-    				'developer/frontend-tests'
-    			]
-			},
-			{
-				Backend: [
-					'developer/backend',
-				]
-			},
-			'developer/developers-guide-env-tech',
-			'developer/developers-guide-e2e-tests'
-	],
-		'Extending Stratos': [
-			'extensions/introduction',
-			'extensions/theming',
-			'extensions/customizing',
-			'extensions/v4-migration',
-			'extensions/frontend',
-			'extensions/backend',
-		],
-		
+      'advanced/invite-user-guide',
+      'advanced/sso',
+      'advanced/bosh-metrics'
+    ],
+    'Development': [
+      'developer/contributing',
+      'developer/introduction',
+      {
+        Frontend: [
+          'developer/frontend',
+          'developer/frontend-tests'
+        ]
+      },
+      {
+        Backend: [
+          'developer/backend',
+        ]
+      },
+      'developer/developers-guide-env-tech',
+      'developer/developers-guide-e2e-tests'
+    ],
+    'Extending Stratos': [
+      'extensions/introduction',
+      'extensions/v4-migration',
+      'extensions/theming',
+      'extensions/frontend',
+      'extensions/backend',
+    ],
+
   },
 };
diff --git a/website/static/images/extensions/tab-example.png b/website/static/images/extensions/tab-example.png
deleted file mode 100644
index 38afc322b7..0000000000
Binary files a/website/static/images/extensions/tab-example.png and /dev/null differ