A next-generation tool to create blazing-fast documentation sites
API
created:9/8/2020
,
updated:11/13/2020

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 | (string & {}) | (string & ReactElement<any, string | ((props: any) => ReactElement<any, any> | null) | (new (props: any) => Component<any, any, any>)>) | (string & ReactNodeArray) | (string & ReactPortal)
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