Migrate documentation sites 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-control 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

First we will add gatsby and the component-controls gatsby-theme-stories 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.

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

  "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.

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.

• title field is mapped to the siteTitle configuration field.

• description field is mapped to the siteDescription 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.

---
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 component to display the source code.

---
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. The Props/PropsTable component can be imported from @component-controls/blocks.

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

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

# Button

<Props of={Button} />