Gatsby Starter Docz is an open-source Gatsby starter that pairs the Docz documentation tool with a blog, giving developers a single site for publishing both library documentation and MDX-powered blog posts. It uses gatsby-theme-docz to render documentation from MDX files, and includes the standard Gatsby file structure so you can extend everything with Gatsby's APIs.
What is Gatsby Starter Docz?
Gatsby Starter Docz is a project starter that builds a Gatsby site with two content sections: a documentation area powered by Docz and a blog. It takes MDX files from the blog/ and docs/ directories, plus Gatsby configuration, and outputs a static website generated by Gatsby. The starter was created by Pedro Nauck (pedronauck) and is hosted on GitHub, with a live demo available at gatsby-docz.netlify.com.
Key Features
- Gatsby + Docz integration — Uses
gatsby-theme-doczto generate documentation pages alongside the Gatsby blog, so a single build produces both. - MDX content — Blog posts live in
blog/and documentation lives indocs/, both written in MDX (Markdown that can embed JSX components). - Flexible documentation placement — Docz does not require a fixed documentation folder; the
doczrc.jsconfiguration ignores.mdxfiles inblog/, so you can put documentation anywhere else in the project. - Gatsby API hooks — Includes
gatsby-browser.js,gatsby-node.js, andgatsby-ssr.js, letting you customize browser behavior, build processes, and server-side rendering precisely as with any Gatsby project. - Quick start via Gatsby CLI — One command creates the project:
gatsby new coolest-library https://github.com/pedronauck/gatsby-starter-docz. - Live development environment — Running
gatsby developserves the main site athttp://localhost:8000, documentation athttp://localhost:8000/docs, and exposes GraphiQL athttp://localhost:8000/___graphqlfor querying your data. - Prettier formatting — A
.prettierrcfile is included to keep code style consistent across the project.
Who is this starter for?
Library authors — Write API documentation and usage guides for an open-source library, and keep a blog in the same repo for release notes and announcements.
Design system teams — Document component libraries with Docz's component-driven MDX format while publishing design updates on the included blog.
Developers launching a personal site — Combine a blog for articles with a docs section for tutorials or project documentation, all maintained in one Gatsby codebase.
What can you do with Gatsby Starter Docz?
- Library maintainers: Publish reference documentation and live examples in MDX, and manage a changelog blog without leaving the same repository.
- Design system teams: Create component documentation pages and share design guidelines through a single site, with MDX letting you embed interactive component demos.
- Bloggers: Use the built-in blog folder to write Markdown-based posts that support React components via MDX, alongside any documentation pages you add.
How does it work?
After creating a new site with the Gatsby CLI command, run gatsby develop to start the development server. The starter's blog/ directory is where you add MDX posts, while the docs/ directory contains example documentation that you can edit or replace. Saving changes triggers hot reloading, so your new posts and docs appear instantly in the browser.
Pricing
Gatsby Starter Docz is free and open source. The repository includes a LICENSE file stating the MIT license, and it can be used for personal or commercial projects without paying a fee.
FAQ
How do I create a new site with this starter?
Run gatsby new your-project-name https://github.com/pedronauck/gatsby-starter-docz. Gatsby CLI clones the starter and installs all dependencies, producing a ready-to-edit project structure.
Where is the documentation served during development?
When gatsby develop is running, the documentation lives at http://localhost:8000/docs. The main blog and site content is served at http://localhost:8000, and GraphiQL is available at http://localhost:8000/___graphql.
What file types does this starter support?
Blog posts and documentation files are written in MDX, which allows you to embed JSX components directly inside Markdown. This is useful for showing live component examples alongside written documentation.
Can I put documentation anywhere in the project?
Yes. Docz does not require a fixed folder for documentation. The starter's doczrc.js configuration explicitly ignores .mdx files inside the blog/ directory, so as long as your docs are outside that folder, they will be picked up automatically.
Is this starter free to use?
Yes, Gatsby Starter Docz is released under the MIT license, as indicated in the repository's LICENSE file. That gives you freedom to modify, distribute, and use it in both personal and commercial projects.
