chore: update v2 documentation on multiple points (#80)

chore: update v2 documentation on multiple points

Author: Jesper Orb

src/docs/documentation/customizing/add-favicon-and-metadata.mdx

@@ -5,33 +5,33 @@ parent: Documentation
 menu: Customizing
 ---
 
-To add a favicon and metadata to your generated gatsby site, follow this quick guide
+# Add favicon and metadata
 
-Add [`react-helmet`](https://github.com/nfl/react-helmet) along with [`gatsby-plugin-react-helmet`](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-react-helmet)
+Adding metadata to your site is done by configuring Gatsby in combination with [`react-helmet`](https://github.com/nfl/react-helmet) [**source @ gatsby**](https://www.gatsbyjs.org/docs/add-page-metadata/).
 
-[How do I add react-helmet to my docz app ?](https://www.gatsbyjs.org/docs/add-page-metadata/)
 
-Once you've added react-helmet you can shadow the `src/wrapper.js` theme component to add metadata
+### Shadowing the Wrapper-component
 
-so you would create a file : `src/gatsby-theme-docz/wrapper.js` (path is important) and inside it : 
+The metadata is set up in a file called `wrapper.js` which lives in docz theme package: `gatsby-theme-docz`. To override it we need to [Shadow the component](https://www.gatsbyjs.org/blog/2019-04-29-component-shadowing/), which means that we need to create a copy of the file with the "same" file path and name in our own `src`-directory.
 
+1. Create a file called `wrapper.js` in `src/gatsby-theme-docz`. Then path is important.
+2. Paste the following content and edit it to your liking
 ```js
 import * as React from 'react'
 import { Helmet } from 'react-helmet'
 
 const Wrapper = ({ children }) => <React.Fragment>
 	<Helmet>
 		<meta charSet="utf-8" />
-		<title>My Title</title>
-		<link rel="icon" 
-      		type="image/png" 
-		    href="http://example.com/myicon.png"
-		>
+		<title>My Shadow!</title>
+		<link rel="icon"
+      		type="image/png"
+		      href="http://example.com/myicon.png"
+		/>
 	</Helmet>
 	{children}
 </React.Fragment>
 export default Wrapper
-
 ```
 
-And that should do it 👍.
+If you rebuild your site now it should use this component as a wrapper instead of the themes component.

src/docs/documentation/customizing/component-shadowing.mdx

@@ -0,0 +1,23 @@
+---
+name: Component Shadowing
+route: /docs/component-shadowing
+parent: Documentation
+menu: Customizing
+---
+
+# Component Shadowing
+
+All components that comes with the standard theme `gatsby-theme-docz` can be [**shadowed**](https://www.gatsbyjs.org/blog/2019-04-29-component-shadowing/). This means that you can supply your own component that will shadow/override the themes component. This is done by placing a component with the same name as the themes component in the "same filepath" as the original component.
+
+For example if you want to shadow the `Logo`-component you would have to have the following structure in your folder:
+
+```
+your-site
+└── src
+    └── gatsby-theme-docz
+        └── components
+            └── Logo
+                  └──index.js
+```
+
+If it has the matching folder structure and name the theme component will be shadowed and you can freely edit.

src/docs/documentation/customizing/powered-by-gatsby.mdx

@@ -30,9 +30,9 @@ and properties you can use with Docz.
 
 > Check [all Gatsby API references](https://www.gatsbyjs.org/docs/api-reference/) here
 
-So, if you want to use any of those Gatsby configurations file inside your Docz project, just create it in the root and we'll lead with them for you.
+So, if you want to use any of those Gatsby configurations file inside your Docz project, create it in the root and we'll handle them for you.
 
-Like, if you want to make some change in the webpack configuration, you can use
+If you want to make some change in the webpack configuration, you can use
 the `onCreateWebpackConfig` hook inside the `gatsby-node.js` file:
 
 ```js

src/docs/documentation/general/built-in-components.mdx

@@ -35,7 +35,7 @@ import { Button } from './Button'
 ![](https://cdn-std.dprcdn.net/files/acc_649651/hrRpoR)
 
 As you see, `<Playground>` rendered your component in a blank state, and right below, displayed the code used to.
-This can be very useful to test and develop your components in a good environment while you document it.
+This can be very useful to test and develop your components in a good environment while you document it. The code below the component is also editable and the changes you make to that code will reflect live in the component above!
 
 ## Component Props
 
@@ -67,8 +67,44 @@ import { Button } from './'
 </Playground>
 ```
 
-And now you have a list of properties:
+The button that will display the props must have some annotation on the props. For non flow or typescript users this can be achieved with [`prop-types`](https://www.npmjs.com/package/prop-types)
+
+```jsx
+import React from 'react'
+import t from 'prop-types'
+
+const Button = ({ children, kind }) => {
+  // Do something nice with the kind prop, like add a class with it
+  return <button>{children}</button>
+}
+
+Button.propTypes = {
+  /**
+   * This is a pretty good description for this prop.
+   */
+  kind: t.oneOf(['primary', 'secondary', 'cancel', 'dark', 'gray']),
+}
+Button.defaultProps = {
+  kind: 'primary',
+}
+export Button
+```
+
+If you have used `prop-types` you should now have a list of properties in a nicely formatted table:
 
 ![](https://cdn-std.dprcdn.net/files/acc_649651/KEm5mH)
 
-You can see more about our built-in components on [Components API](/docs/components-api).
+The same can be achieved in typescript by adding comments to the props interface of your component:
+
+```jsx
+import React from 'react'
+
+interface ButtonProps {
+  /**
+   * This is a pretty good description for this prop.
+   */
+  kind: 'primary' | 'secondary' | 'cancel' | 'dark' | 'gray'
+}
+```
+
+You can read more in depth about our built-in components on [**Components API**](/docs/components-api). If you are more interested in learning more about the MDX-pages you could head on to [**Document Settings**](/docs/document-settings)

src/docs/documentation/general/deploying-your-docs.mdx

@@ -11,7 +11,7 @@ Now that you know about writing your docs, let's talk about how you can build an
 The first thing that you need to do is run the build script created in your `package.json`:
 
 ```bash
-$ yarn build
+$ yarn docz:build
 ```
 
 If everything goes well, this command will generate all static files for you in the `.docz/dist` folder and you will see something like this in your terminal:
@@ -31,6 +31,17 @@ export default {
 }
 ```
 
+## Changing base folder
+
+If you are using something like [GitHub Pages](https://pages.github.com/) chances are that you are not deploying your site directly under the root of your user. For example if you have a `docz`-repository on your GitHub the URL for deploying that repository will be `https://your-username.github.io/docz`. You can specify in which subdirectory your files will be deployed with the `base`-property of `doczrc.js`.
+
+```js
+// doczrc.js
+export default {
+  base: '/docz',
+}
+```
+
 ## Using Netlify
 
 If you understand nothing about deploys, we highly recommend that you use the service we're using to host this website that you're seeing, called [Netlify](http://netlify.com/). Netlify is a really fantastic and easy tool that allows you to deploy your application in an automatic way by running the deploy on every push from a branch in seconds.

src/docs/documentation/general/document-settings.mdx

@@ -10,7 +10,7 @@ menu: General
 Document settings can be something simple, but powerful. They should be defined in the top of the `.mdx`
 using yaml and can be used to change whatever you want by passing this config to your theme.
 
-By default the document has just three properties that can't be overrided:
+By default the document has **three** properties that can't be overriden:
 
 ```markdown
 ---
@@ -20,9 +20,7 @@ menu: Documents
 ---
 ```
 
-These properties are self-explanatory, but here is their definition:
-
-- `name` Define the name of your component.
+- `name` Define the name of your component, the title of the page
 - `route *(optional)*` Define the route of your component.
 
 >If you don't pass any here, we'll create a slug getting the filepath of your file as route.
@@ -31,18 +29,14 @@ These properties are self-explanatory, but here is their definition:
 
 ## Custom properties
 
-With just this properties perhaps you couldn't do many customizations.
-But, all documents can have arbitrary properties and you can use them to built your theme.
-
-Example: you can define a property called `fullpage` to define whether your document is a page with `100%` width or not:
+The built in properties are for docz but docz is exstensible and you can create your own themes where you could have different needs and need different properties. Custom properties can be set in the document settings and they will automatically be parsed.
 
+For example you can define a property called `fullpage` to define whether your document is a page with `100%` width or not:
 ```
 ---
 name: My Document
 fullpage: true
 ---
 ```
 
-Now when you're creating your theme you can use this property to define inside your page component if shows a container of not.
-
-This is very powerful and gives you flexibility when developing your own themes.
+When you later on are creating a theme these settings are passed to your theme components which you can read more about under [**Creating your themes: Using documents settings**](/docz/creating-your-themes#using-documents-settings)

src/docs/documentation/general/getting-started.mdx

@@ -11,15 +11,20 @@ menu: General
 
 ## Migration Guide
 
-This documentation it's about v2. If you need to migrate your Docz project, please read our [Migration Guide](/docs/migration-guide)
+This documentation it's about **v2**. If you need to migrate your Docz project, please read our [**Migration Guide**](/docs/migration-guide).
+If you are looking for documentation for v1 it's [**here**](https://docz-v1.surge.sh/)
 
 ## Installation
 
 Getting started with **Docz** is something really easy and quick.
-First of all, you will need to install **Docz**  using your favorite package manager (we'll assume yarn for this example):
+First of all, you will need to install **Docz** using your favorite package manager:
 
 ```bash
-$ yarn add docz@next react react-dom --dev
+$ yarn add docz@next react react-dom
+```
+or
+```bash
+$ npm add docz@next react react-dom
 ```
 
 > ### Warnings and tips
@@ -29,26 +34,32 @@ $ yarn add docz@next react react-dom --dev
 
 ```json
 {
-  "name": "mycoolproject",
+  "name": "next-gen-documentation",
   "scripts": {
     "docz:dev": "docz dev",
     "docz:build": "docz build"
   },
-  "devDependencies": {
-    "docz": "latest"
+  "dependencies": {
+    "docz": "latest",
+    "react": "16.8.0",
+    "react-dom": "16.8.0"
   }
 }
 ```
 
-Now you can spin up your dev server just by running:
+Now you can spin up your dev server by running:
 
-```
+```bash
 $ yarn docz:dev
 ```
+or
+```bash
+$ npm run docz:dev
+```
 
 ## Using
 
-With your dev server up, you can start writing your documentation. Docz uses [MDX](https://mdxjs.com/) as a standard
+With your dev server up, you can start writing your documentation. Docz uses [**MDX**](https://mdxjs.com/) as a standard
 format because of the flexibility of writing JSX inside markdown files.
 
 > Note that you **don't need to follow any strict file architecture**. You can just create your `.mdx` files **anywhere in your project**.
@@ -69,3 +80,5 @@ Hello, I'm a mdx file!
 With your first `.mdx` created, you can open your browser and visit `localhost:3000` and you should see something like this:
 
 ![](https://cdn-std.dprcdn.net/files/acc_649651/Y825GV)
+
+_MDX_ is markdown with extra everything. We cover more on what you can do with _MDX_ under [**Writing MDX**](/docs/writing-mdx)

src/docs/documentation/general/usage-with-css-preprocessors.mdx

@@ -0,0 +1,30 @@
+---
+name: Usage with CSS Preprocessors
+route: /docs/usage-with-css-preprocessors
+parent: Documentation
+menu: General
+---
+
+# Using docz with CSS Preprocessors
+
+Most configuration is from version 2 handled by Gatsby, and CSS preprocessing is no exception. Gatsby uses a range of [**Plugins**](https://www.gatsbyjs.org/plugins/) to handle things like `sass`, `less` and `postcss`. Gatsby supports CSS Modules out of the box.
+
+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:
+
+1. Install [`node-sass`](https://github.com/sass/node-sass) and [`gatsby-plugin-sass`](https://www.gatsbyjs.org/packages/gatsby-plugin-sass/)
+```bash
+# npm
+npm install --save node-sass gatsby-plugin-sass
+
+# yarn
+yarn add node-sass gatsby-plugin-sass
+```
+
+2. Add the plugin to your `gatsby-config.js`
+```js
+//gatsby-config.js
+module.exports = {
+  plugins: ['gatsby-plugin-sass']
+}
+```
+You should now be able to use `sass` in your components!

src/docs/documentation/general/usage-with-typescript.mdx

@@ -7,7 +7,7 @@ menu: General
 
 # Using docz with Typescript
 
-To use docz with TypeScript codebase you need to add `typescript: true` to your doczrc.js
+To use docz with TypeScript codebase you need to add `typescript: true` to your `doczrc.js`, the rest will be setup by _docz_.
 
 ```js
 export default {
@@ -17,11 +17,20 @@ export default {
 
 # Documenting Props in TypeScript
 
-`docz` exports a Props component that takes in a component and generates a table of its props types, descriptions and default values.
+As mentioned in [**Built-in components**](/docs/built-in-components) the `<Props/>`-component is used to automatically document your components props assuming you have the correct comments on your components like below.
 
-Make sure to reference the full path to the module you're documenting in your MDX file
+```js
+interface ButtonProps {
+  /**
+   * A description of the prop that you seem fit :)
+   */
+  kind: 'primary' | 'secondary' | 'cancel' | 'dark' | 'gray'
+}
+```
 
-```mdx
+The typescript parser can be a bit fussy sometimes (and we are working on it) so if your typescript-files are not being found you may have to write out the full path with the file ending. If this doesn't do the trick you can try checking if using `default` exports or `named` exports are the problem.
+
+```js
 import { Props } from 'docz'
 import Button from './Button.tsx'
 
@@ -30,3 +39,14 @@ import Button from './Button.tsx'
 
 ```
 
+# Advanced configuration
+
+If you have particular needs or need to control exactly which files are being picked up or if you want to tap into the parser that creates the documentation there are two properties on the `doczrc.js` that you can use: `filterComponents` and `docgenConfig` (some use cases explained [here](https://github.com/doczjs/docz/issues/827))
+
+```js
+export default {
+  filterComponents: (files) =>
+    //This overrides the default filtering of components
+    files.filter(filepath => /[w-]*.(js|jsx|ts|tsx)$/.test(filepath)),
+}
+```

src/docs/documentation/general/writing-mdx.mdx

@@ -15,7 +15,7 @@ More details about MDX in the [Official website.](https://mdxjs.com/)
 ## Working with components
 
 For now, you only need to know that with MDX you can use your components inside markdown.
-But how? Let's take a look at how we can improve our `.mdx` created before by importing and using a component inside it:
+But how? Let's take a look at how we can improve our `.mdx` created before by importing and using a component inside it. The example below assumes we have a exported component named `Button` in a file named `Button.jsx`/`Button.tsx` located in the same folder as the `.mdx`-file we are editing.
 
 ```markdown
 ---
@@ -35,6 +35,8 @@ And, if you really have a `Button` component to import, you'll see something lik
 
 ![](https://cdn-std.dprcdn.net/files/acc_649651/Fgbg4F)
 
+With MDX you can mix _React Components_ or _html-elements_ with regular markdown allowing you to either document your own components _or_ creating helper components that makes documentation easier. **Docz** comes with some prebuilt helper components which will help you document components faster, these are covered in [**Built-in components**](/docs/built-ins-components).
+
 > ### Note
 >
 > So far Docz only works with React components. But stay calm, we are working to bring Preact, Vue and some others libraries to Docz!