docs: update migration guide

Author: rakannimer

src/docs/documentation/references/migration-guide.mdx

@@ -1,17 +1,14 @@
----
-name: Migration Guide
-route: /docs/migration-guide
-parent: Documentation
-menu: References
----
-
 # Migration Guide
-The [v2 release](https://github.com/pedronauck/docz/pull/950) is our biggest release in terms of changes on our core scripts. Our bundler system was entirely modified in order to use Gatsby as default bundler and you will need to update your code if you’re coming from a previous version. It’s not a big deal, but you need to follow this guide in order to get Docz running properly on your project after the upgrade.
+
+The [v2 release](https://github.com/pedronauck/docz/pull/950) is our biggest release in terms of changes to our core scripts. Our bundler system was entirely modified in order to use Gatsby as default bundler and you will need to update your code if you’re coming from a previous version. 
+
+It’s not a big deal, but you will need to follow this guide in order to get Docz running properly on your project after the upgrade.
 
 ## Gatsby as default bundler
-The biggest change in the new v2 is that now our core is entirely build using Gatsby behind the scenes. This is a huge win for Docz, since now we can focus on build new features instead of handling with a lot of bundlers issues (our biggest bottleneck) and enjoy all Gatsby ecosystem.
 
-So, in order to refactoring our core, we need to change a lot of things and remove others that no longer make sense. The most expressive changes here is about the configuration for `doczrc.js` and the plugin system.
+The biggest change in the new v2 is that our core is now entirely built using Gatsby behind the scenes. This is a huge win for Docz, since now we can focus on building new features instead of handling a lot of bundlers issues (our biggest bottleneck) and leverage the entire Gatsby ecosystem.
+
+So, in order to refactor our core, we need to change a lot of things and remove others that no longer make sense. The most expressive changes here is about the configuration for `doczrc.js` and the plugin system.
 
 ### List of removed properties from `doczrc.js`
 * **`websocketHost`** ▶︎ _no longer need_
@@ -37,29 +34,42 @@ The `createPlugin` method also changed in order to fit with Gatsby now.
 * **`onPreRender`** ▶︎ _removed_
 * **`onPostRender`** ▶︎ _removed_
 
-> All methods that changed now are using the same API of Gatsby hooks.
+> All methods that changed now are using the same API as Gatsby hooks.
 > You can have more details about then [here](https://www.gatsbyjs.org/docs/node-apis).
 
 ## `docz-theme-default` removed
-The main reason that made us change our core to use Gatsby is that now it have a feature called themes. In the last major version we launched our own `gatsby-theme-docz` and this was impressive since we could use Docz inside a Gatsby project and brings a lot of new possibilites when creating a documentation.
 
-So, indeed we were using Gatsby theme at all, but in the wrong way. One of the best benefits of Gatsby theme are the feature called Component Shadowing, that’s the ability to replace theme files just by creating your own file following a file naming convention. This is awesome and is something that people always ask for me, like: “I want just to change the head in the Docz theme”.
+Make sure to remove `docz-theme-default` from your dependencies when migrating : 
+
+```sh
+yarn remove docz-theme-default # npm uninstall docz-theme-default
+```
+
+The main reason that made us change our core to use Gatsby is that they have added a feature called themes. 
+
+In the last major version we launched our own Gatsby theme `gatsby-theme-docz` and this was a huge step forward because we can now use Docz inside a Gatsby project and bring a lot of new possibilities when creating documentation.
 
-In order to get Docz running with component shadowing we removed `docz-theme-default` and now you don’t need to install it anymore. You can just add `docz` and your project is done.
+One of the best benefits of Gatsby themes is a feature called Component Shadowing, that’s the ability to replace theme files just by creating your own file following a file naming convention. This is awesome and is something that people very often ask, for example: “I want just to change the head in the Docz theme”.
 
-Check [here](h) readme for more information.
+In order to get Docz running with component shadowing we removed `docz-theme-default` and now you don’t need to install it anymore. You can just add `docz` to your project.
+
+Check [here](https://github.com/doczjs/docz/tree/master/core/gatsby-theme-docz#customizing-components) for more information about customizing the Gatsby theme.
 
 ### Code highlight with PrismJS
-In the last version of Docz we’re using Codemirror to highlight code inside `<Playground>` and code blocks. Now we are using [prism-react-renderer](https://github.com/FormidableLabs/prism-react-renderer) together with Theme UI.
 
-Check [here](h) for more information.
+In the last version of Docz we used Codemirror to highlight code inside `<Playground>` and code blocks. Starting from v2 docz uses [prism-react-renderer](https://github.com/FormidableLabs/prism-react-renderer) together with Theme UI.
+
+Check [here](https://github.com/FormidableLabs/prism-react-renderer) for more information.
 
 ### New `themeConfig` properties
-Another great thing launched in the newest version is the integration with the [Theme UI](https://theme-ui.com). Theme UI it’s a library for build consistent, themeable React apps based on constraint-based design principles. So, in order to integration it with our new theme, a lot of changes are made inside the `themeConfig` object.
 
-Check [here](h) for more information.
+Another great thing launched in the newest version is the integration with [Theme UI](https://theme-ui.com). Theme UI is a library for building consistent, themeable React apps based on constraint-based design principles. 
+
+So, in order to integrate it with our new theme, a lot of changes have been made inside the `themeConfig` object.
+
 
 ## `theme` property removed
+
 The property used to define your Docz theme inside the `doczrc.js` was removed. But you can still create and use your own theme from scratch if you want.
 
 If you want to use your own theme, just create a file called `src/gatsby-theme-docz/index.js` in order to use component shadowing and replace it with your new theme.
@@ -93,7 +103,7 @@ export default ({ children }) => (
 
 CSS preprocessors and modules were handled by [`docz-plugin-css`](https://github.com/doczjs/docz-plugin-css) which hooked into the bundler config to add different loader support via webpack.
 
-With the change to gatsby preprocessors like `sass` can be handled by gatby via [Plugins](https://www.gatsbyjs.org/plugins/)
+With the change to gatsby, css preprocessors like `sass` can be handled by gatsby via [Plugins](https://www.gatsbyjs.org/plugins/)
 
 These plugins are added by adding a `gatsby-config.js` in your project root or modifying an existing one. For example if you want to add support for `sass` you would do the following:
 
@@ -113,3 +123,7 @@ module.exports = {
   plugins: ['gatsby-plugin-sass']
 }
 ```
+
+## Examples 
+
+Make sure to check out [docz's `examples` directory](https://github.com/doczjs/docz/tree/master/examples) for the full list of supported examples.