Migration from docz

docz is an easy to use, zero-config documentation system using Gatsby.

component-controls provides migration compatibility for many of the documentation features in docz. And component-controls can also use gatsby as a static site generator.

A migration example can be found here:

source code

live site

The sample project was bootstraped from gatsby-starter-docz-netlifycms

Add gatsby theme

we will add gatsby and the component-controls gatsby theme to the project

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

Configuration file path

By default, the docz 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.

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

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 can read directly the docz 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 file (doczrc.js) for both build-time and run-time configurations.

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 field is mapped to the stories configuration field.
menu 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 provides a similar component to docz's Playground. The Playground component can be imported from @component-controls/blocks.

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>

live example:

Props

component-controls provides a similar component to docz's Props. The Props/PropsTable component can be imported from @component-controls/blocks.

props.mdx

---
name: Props
menu: Components
---

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

# Button

<Props of={Button} />

live example:

Name	Description	Default
disabled	Boolean indicating whether the button should render as disabled boolean	false
children	button label (string & (boolean \| ReactChild \| ReactFragment \| ReactPortal \| null))	default
onClick	onClick handler (() => void)	() => {}
style	Custom styles object	{}
backgroundColor	Background color string	#fefefe
color	Text color, default black string	black
type	Button type buttonresetsubmit	button
padding	Numeric field type number	5

Data-driven testing with react

Gatsby vs Nextjs vs Storybook