Writing Documentation with Docz
Writing good documentation is important for your project maintainers (and for your future self). Docz is a very nice documentation generator. It enables you to write interactive documentation for your React components with very little effort.
mdx files – short for Markdown with JSX – which brings React components to Markdown files. From your PropTypes, or Flow types or TypeScript types, it can generate property tables to document properly how to use your components. In addition, you can provide a coding playground for your components, so that anyone can see them in action, modify the code and see the changes live, or copy the snippet to use it somewhere else.
If you’re starting your Gatsby project from scratch and would like to have great documentation, with Docz support out of the box, you can use
gatsby-starter-docz. You can also find more information at the end of this guide in the Other resources section.
Alternatively, the following guide should help you to get Docz working within an existing Gatsby project.
First, if you do not have a Gatsby project set up yet, use the Gatsby CLI to create a new site:
To set up Docz you need to install the Docz Gatsby theme and add some custom configuration. Make sure you are in the root directory of your Gatsby project:
And install required packages:
Docz searches your directories for
mdx files and renders them. Create a
docs folder at the root of your project. Place an
index.mdx file inside this directory with the following content:
Run the development server with
gatsby develop and you should be greeted with the default Docz layout and a “Getting Started” heading. Stop the development server after verifying that everything works.
Let’s spice things up by adding and rendering a React component. For the sake of simplicity you can create the following button component in the same
The button will display its text by default with a
18px however you can also pass in
big as a size. These properties will later be displayed by Docz.
Note: If your component relies on
graphql, consider splitting it into two smaller components:
- one React component dealing only with the UI layer, and
- another dealing with the data layer.
You could showcase the UI layer React component in your
mdxfiles and your data layer component could use it to render the data it fetched thanks to
Create a new file in the
docs directory to document your newly created button component. Call the file
Docz offers some internal components you can use to display the component and its properties. Import both these and your component itself into the document and use them:
Start the development server again and you should see the properties (children and scale), one playground displaying the normal button, and one playground showing the button in its three sizes.
You can usually set your config using a
doczrc.js file (see all available options) or if you want to set some default options for your theme, you can set
options in the theme definition.
We highly recommend that you set your configuration using
doczrc.js! Live reloading will only work with the configuration file, not the settings inside the theme definition.
- For more information on Docz visit the Docz site and in particular the Gatsby theme documentation
- Check out the official Docz starter