Migrate documentation sites from docz
Tags: react, testing, gatsby
Published: 2020-09-09 20:25:50

[docz](https://www.docz.site) is an easy to use, zero-config documentation system using [Gatsby](https://www.gatsbyjs.org/).

[component-controls](https://component-controls.com) provides migration compatibility for many of the documentation features in [docz](https://www.docz.site). And component-control can also use [gatsby](https://component-controls.com/tutorial/getting-started/gatsby) as a static site generator.

A migration example can be found here: 

[source code](https://github.com/ccontrols/component-controls/tree/master/examples/docz-migration)

[live site](https://docz-migration.netlify.app)

The sample project was bootstraped from [gatsby-starter-docz-netlifycms](https://github.com/colbyfayock/gatsby-starter-docz-netlifycms)

## Add gatsby theme

First we will add [gatsby](https://www.gatsbyjs.com) and the component-controls [gatsby-theme-stories](https://github.com/ccontrols/component-controls/tree/master/integrations/gatsby-theme-stories) to the project

```bash
yarn add gatsby @component-controls/gatsby-theme-stories
```

## Configuration file path

By default, the [docz](https://www.docz.site) configuration file is kept in the project main folder, while component-controls uses a `.config` sub-folder. We will configure the gatsby stories theme in `gatsby-config.js`.

```js:title=gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: '@component-controls/gatsby-theme-stories',
      options: {
        //doczrc.js file located in project main folder
        configPath: '.',
      },
    },
  ],
};
```

## Launch scripts

Next, you should add the gatsby develop and gatsby build scripts to the project's `package.json`

```json:title=package.json
  "scripts": {
    //component-controls scripts
    "build-docs": "gatsby clean && gatsby build",
    "start": "gatsby develop -p 9022",
    //docz original scripts
    "develop": "docz dev",
    "build": "docz build --dest public",
    "serve": "docz serve"
  },
```

## Configuration fields

[component-controls](https://component-controls.com) can read directly the [docz](https://www.docz.site) configuration file, the following is an example `doczrc.js`:

> the component-controls build-time and run-time configurations are merged, and we can use a single [configuration](https://component-controls.com/configuration/overview) file (`doczrc.js`) for both build-time and run-time configurations.

```json:title=doczrc.js
export default {
  files: 'docs/**/*.mdx',
  title: 'Docz & Netlify CMS',
  menu: [
    {
      name: 'Quick Start',
      menu: [''],
    },
    {
      name: 'Getting Started',
      menu: ['Manual Installation'],
    },
    {
      name: 'Configuration',
    },
  ],
};
```

* [**files**](https://www.docz.site/docs/project-configuration) field is mapped to the **stories** configuration field.

* [**title**](https://www.docz.site/docs/project-configuration) field is mapped to the **siteTitle** configuration field.

* [**description**](https://www.docz.site/docs/project-configuration) field is mapped to the **siteDescription** configuration field.

* [**menu**](https://www.docz.site/docs/project-configuration) field is used in component-controls in a similar way to docz. You will need to fill the menu field in a document to attach it to a menu item.

## Components

### Playground

[component-controls](https://component-controls.com) provides a similar component to docz's [Playground](https://www.docz.site/docs/built-in-components#playground-component). The [Playground](https://component-controls.com/api/blocks-playground--overview) component can be imported from `@component-controls/blocks`.

```js:title=playground.mdx
---
name: Playground
menu: Components
---

import { Playground } from '@component-controls/blocks';
import { Button } from '../src/components/Button'

# Button

<Playground>
  <Button kind="secondary">Click me</Button>
</Playground>
```
You can also wrap the component code in a [Story](https://component-controls.com/api/blocks-story--overview) component to display the source code.

```js:title=playground.mdx
---
name: Playground
menu: Components
---

import { Playground, Story } from '@component-controls/blocks';
import { Button } from '../src/components/Button'

# Button

<Playground>
  <Story name='example'>
    <Button kind="secondary">Click me</Button>
  </Story>  
</Playground>
```


### Props

component-controls provides a similar component to docz's [Props](https://www.docz.site/docs/built-in-components#component-props). The [Props/PropsTable](https://component-controls.com/api/blocks-propstable--overview) component can be imported from `@component-controls/blocks`.

```js:title=props.mdx
---
name: Props
menu: Components
---

import { Props } from '@component-controls/blocks';
import { Button } from '../src/components/Button'

# Button

<Props of={Button} />
```