Document your React components using docz

How we build our UI documentation at Trabe

“person holding magnifying glass” by João Silas on Unsplash

In Trabe we like to use docz to document our React UI components.

Docz is a zero-config tool to write your documentation using just markdown and javascript.

It’s based on MDX, which lets you import and export code from your project and use JSX on markdown documents. It also provides ready to use components that make building your docs a breeze.

Why we like it

It gives you total freedom to create your docs, and you can see changes live while you write them.

It combines the readability of markdown and the power of React components.

Since MDX uses the remark/rehype ecosystem, you can use its vast collection of plugins while writing your files.

Initial setup

Install it using yarn add docz --dev and start writing .mdx files. They can go anywhere inside the project.

Now just run docz dev and navigate to http://localhost:3000 to watch the results. If no .mdx files are present it will be just an empty page.

This dev server is the one you’ll use while writing the documentation, and probably the only one you’ll need. If you need to publish your docs the command docz build will generate a static version of them.

Adding these two scripts on package.json is a handy way of executing both commands:

{
  "name": "your-proyect",
  "scripts": {
    "docz:dev": "docz dev",
    "docz:build": "docz build"
  },
  "devDependencies": {
    "docz": "latest"
  }
}

Writing documentation

Documentation files can go anywhere, but we like to organize our components in folders, so we put them side by side its corresponding code.

/components/
├── button
│   ├── button.css
│   ├── button.jsx
│   ├── button.mdx
│   ├── button.test.jsx
│   └── index.js
├── ...

A typical docz .mdx file has a front-matter a-la Jekyll, some imports and markdown mixed with components, like this:

---
name: Button
menu: Components
route: /components/button
---
import Button from './Button'
# The button
Behold the awesome Button Component
<Button>Click</Button>

The settings provided on the front-matter will be used to customize how the documentation‘s web is structured. By default the basic properties every document may have are: name, menu, and route.

• The component’s page title is defined using name.
• If provided, route sets an URL other than the default-dashed-representation of the component’s filepath.
• If you assign the same menu string to multiple files they will be grouped on the sidebar.

If your dev server is still up (note that when adding new files you may have to restart it) navigating to /components/button will show you a nice looking web with a sidebar menu using the default theme.

Your first documentation page. That was easy, right?

Notice how the Button section is grouped under the Components menu, as we defined in our settings.

It’s possible to add more document properties and use them inside your custom themes too.

Built-in components

Docz provides two basic components that help you write your docs. You have to import them on your files to be able to use them.

import { Playground, PropsTable } from "docz";

<PropsTable />

It helps you explain how to use your component using its PropTypes. If you specified them in your component like this:

Using <PropsTable of={Button} /> will render a nice table of the component’s props: name, type, the default value and description .

The button’s PropsTable

Note that, if present, the comment before each property is used as its description.

<Playground />

You already explained your component, maybe rendered it as an example with different props, and showed how to use it. What now?.

The Playground component lets you create an example the reader can modify and play with. It also shows the component’s rendered HTML, but only of the original, non-edited version as of docz version v0.12.9.

## Play with the button

<Playground>
  <h2> The button </h2>
  <Button> Default </Button>
</Playground>

Will render this:

If you want to achieve more complex things than rendering an imported component, you can use render props on its children like this:

You can even define a custom component for your example like this:

A more complex example using a React Component

Observe that in this example we aren’t using class properties since inside docz we don’t have access to that feature.

You can check the full example component and its documentation here. Note that, even being zero-config in this example we use a doczrc.js to modify the bundler config so we can use CSSModules.

Using only docz’s default settings you can write documentation of any complexity, and structure it the way you like. If you still need more customization you can always fine-tune the project’s configuration, create your custom themes and plugins or just use the ones made by the community.

This simplicity and customization possibilities are the main reasons we use docz in all our new projects.