Gatsby Starter Docz is a GatsbyJS boilerplate that combines the default Gatsby starter with Docz, giving you a static site plus a separate documentation site for your React components.
What is Gatsby Starter Docz?
Gatsby Starter Docz is a starter project forked from gatsby-starter-default and maintained by Robin Cussol (GitHub: @RobinCsl). It layers Docz, a documentation generator, onto a standard Gatsby site so that MDX files (Markdown with JSX) become live component documentation. The starter outputs two deployable sites: the regular Gatsby site and the Docz documentation site, each with its own live Netlify demo linked in the README.
Key Features
- MDX documentation — Write component documentation in MDX files, which combine Markdown with JSX so you can embed React components directly in prose.
- Live component rendering — Docz renders the actual React component inside the documentation, making it a mini design system viewer.
- Prop table generation — Docz can auto-generate prop tables from component definitions, as the README mentions.
- Coding playground — The documentation includes an interactive playground where readers can edit and test component code in the browser.
- Dual development servers — Run
npm run developto start Gatsby at http://localhost:8000 andnpm run docz:devto start Docz at http://localhost:3000. - Separate build output —
npm run docz:buildoutputs the documentation to.docz/dist, keeping documentation builds independent from the Gatsby site build. - Commit message template — The repo includes a
commit-template.txtfile and a local git config command to enforce conventional commit prefixes (Fix, Feat, Refactor, Docs, Test, Chore, BREAKING). - MIT License — The project is released under the MIT License, with copyright held by gatsbyjs (2015) and RobinCsl (2019).
Who is it for?
- Gatsby component authors — Developers building reusable React components inside Gatsby who want to document them alongside the site instead of maintaining a separate docs tool.
- Open-source maintainers — Project owners who want to publish a component style guide or API reference generated automatically from MDX files.
- Teams building design systems — Groups that need a lightweight documentation layer for their Gatsby-based UI kit, including prop tables and live examples.
What can you do with Gatsby Starter Docz?
- Document Gatsby components — Write MDX files that import your React components and show them with live props, generating a browsable style guide.
- Create a coding playground — Let users interact with component code in the browser, as Docz provides an editor for samples written in MDX.
- Deploy documentation separately — Run
npm run docz:buildand host the static output from.docz/diston any static host, keeping docs decoupled from the main site.
How does Gatsby Starter Docz work?
Scaffold a new project with npx gatsby-cli new your-project-name https://github.com/RobinCsl/gatsby-starter-docz. After installation, npm run develop serves the Gatsby site at port 8000 and npm run docz:dev serves the documentation at port 3000. For production, npm run docz:build compiles the docs into .docz/dist.
FAQ
Does Gatsby Starter Docz work with components that use GraphQL?
No. The README lists a known limitation: it only works with React components that do not render any StaticQuery components from Gatsby. Any component containing GraphQL logic cannot be rendered in documentation files because Docz does not have Gatsby's data layer context.
What versions of npm are required?
The quick-start assumes npx is installed, which is the case for npm version 5.2.0 or greater. You can run the scaffold command with npx gatsby-cli to create a new project.
How do I build and deploy the documentation?
Run npm run docz:build, and the static documentation will be placed in .docz/dist by default. You can then host that folder on any static hosting service.
Is Gatsby Starter Docz free to use?
Yes, it is released under the MIT License. The copyright notices cover gatsbyjs (2015) and RobinCsl (2019), and the license permits free use, modification, and distribution.
