Writing documentation with Docz
Writing good documentation is important for your project maintainers (and for your future self!). A very nice documentation generator is Docz. It allows you to easily write interactive docs for your React components.
Docz leverages 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 the starter mentioned in Other Resources below.
Alternatively, the following guide should help you to get Docz working within an existing Gatsby project.
Setting up your environment
First, if you do not have a Gatsby project set up yet, use the Gatsby CLI to create a new site:
npx gatsby new my-gatsby-site-with-docz
To set up Docz you need to install dependencies and do some custom configuration. Make sure you are in the root directory of your Gatsby project:
cd my-gatsby-site-with-docz
gatsby develop
and test that your Gatsby site is running by going to http://localhost:8000.
Going back to your terminal, install the necessary dev dependencies to get a Docz site up and running.
# run this from my-gatsby-site-with-docz/
npm install --save-dev docz docz-theme-default docz-plugin-css @babel/plugin-syntax-dynamic-import webpack-merge
Add the following scripts to your package.json
file:
{
...
"scripts": {
...
"docz:dev": "docz dev",
"docz:build": "docz build",
...
}
...
}
Create these two files:
doczrc.js
to configure Docz,docz/wrapper.js
to inject some JavaScript in Docz pages, to ensure compatibility with Gatsby.
Create a new folder docz
, and inside that folder, a new file wrapper.js
. Add the following code to wrapper.js
:
import * as React from "react"
// Gatsby's Link overrides:
// Gatsby internal mocking to prevent unnecessary error in docz: __PATH_PREFIX__ is not defined
global.__PATH_PREFIX__ = ""
export default ({ children }) => children
You are essentially creating a dummy wrapper that does nothing else than making sure that
global.__PATH_PREFIX__
is defined on every page.
Create a new file called doczrc.js
in the root directory of your Gatsby project, and add the following content:
import merge from "webpack-merge"
import { css } from "docz-plugin-css"
export default {
title: "Docz with Gatsby",
// Add CSS support in case you use them in your Gatsby project
plugins: [css()],
// Wrapper used to inject some global variable mocks wrapper: "docz/wrapper.js",
modifyBundlerConfig: config => {
const gatsbyNecessaryConfig = {
module: {
rules: [
{
// Transpile Gatsby module because Gatsby includes un-transpiled ES6 code.
// Ignore .json files because they fail to be parsed
exclude: [/node_modules\/(?!(gatsby)\/)/, /\.json$/],
use: [
{
// use installed babel-loader which is v8.0-beta (which is meant to work with @babel/core@7)
loader: "babel-loader",
options: {
// use @babel/preset-react for JSX and env (instead of staged presets)
presets: ["@babel/preset-react", "@babel/preset-env"],
plugins: [
// use @babel/plugin-proposal-class-properties for class arrow functions
"@babel/plugin-proposal-class-properties",
// use @babel/plugin-syntax-dynamic-import for dynamic import support
"@babel/plugin-syntax-dynamic-import",
],
},
},
],
},
],
},
}
return merge(gatsbyNecessaryConfig, config)
},
}
Once you have this configured you should run Docz to ensure it can start up properly. You should see by default a Page Not Found page, this is fine as you havenāt created any mdx
files yet. To run Docz:
npm run docz:dev
If Docz builds successfully you should be able to navigate to http://localhost:3000
and see the default Page Not Found page.
Writing documentation
Docz searches your directory for mdx
files and renders them. Letās add your first documentation page by creating a file index.mdx
in the root directory of your Gatsby project.
---
name: Getting started
route: /
---
# Getting Started
This is the start of an amazing Docz site
This is a very simple documentation page without much going on, but letās spice things up by adding and rendering a Gatsby component. Assuming you have a header component in your components folder which does not rely on StaticQuery
or graphql
, you can add:
---
name: Getting started
route: /
---
//highlight-next-line
import Header from './src/components/header'
# Getting Started
This is the start of an amazing Docz site
//highlight-next-line
<Header siteTitle="Hello from Gatsby" />
Restart the Docz server and voilĆ !
Note: If your component relies on
StaticQuery
orgraphql
, 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
mdx
files and your data layer component could use it to render the data it fetched thanks toStaticQuery
andgraphql
.
Other resources
- For more information on Docz visit the Docz site
- Get started with a Docz starter
edit this page on GitHub