Gatsby Documentation Starter is a GatsbyJS template that automatically generates static documentation sites for React component libraries by combining MDX content with props and JSDoc metadata extracted by react-docgen.
What is Gatsby Documentation Starter?
It is an open-source documentation starter created by whoisryosuke that pairs GatsbyJS, MDX, and react-docgen to turn React component source code into a static documentation site. It takes component JavaScript files and MDX files as input, parses PropTypes and JSDoc docblocks with react-docgen, and outputs a deployable static site with per-component pages. The starter is designed to be embedded inside existing projects and works by default with the /src/components/ folder.
Key Features
- MDX-based documentation — Write documentation in Markdown and embed React components with JSX; MDX frontmatter supports a page name and menu category that determine the generated URL.
- react-docgen integration — Automatically parses functional, stateful, and stateless React components for JSDoc docblocks and PropTypes; data is exposed through Gatsby's GraphQL layer as
allComponentMetadata. - GatsbyJS static output — Uses Gatsby's local GraphQL server to build a static version of the documentation, deployable to Netlify, GitHub Pages, or any CDN.
- Props Table component — A built-in React component (
PropsTable) that renders component props in a table format using the parsed prop metadata. - Modular and embeddable — Can be cloned into an existing project as a
docssubfolder; the component source folder is configurable ingatsby-config.js. - Customizable sidebar navigation — Static pages are defined in
gatsby-config.jsundersiteMetadata.sidebar, while component pages are auto-generated from MDX files; all navigation logic can be overridden incomponents/sidebar.js.
Who is it for?
- React component library maintainers — Need to keep API docs in sync with source code by auto-generating pages from PropTypes and docblocks.
- Open-source project owners — Want a lightweight docs site that deploys without a database or CMS.
- Teams already using Gatsby — Can drop this starter into a monorepo and document components in-place with MDX.
What can you do with it?
- Component authors: write a
Button.mdxnext toButton.jsto produce a documentation page at/categoryname/buttonnamewith an auto-generated props table. - Project maintainers: deploy the generated static site to Netlify with the one-click install button or via the Gatsby CLI
gatsby new docs <repo>. - Documentation engineers: customize page generation in
gatsby-node.jsto create pages from react-docgen data instead of MDX files, or use both together.
How does it work?
The starter expects a folder structure where each component has a JavaScript file and a matching MDX file. React-docgen reads JSDoc docblocks and PropTypes from the JS files, and MDX provides additional prose and the page slug (via frontmatter). Gatsby's transformer plugins create GraphQL endpoints (allMdx and allComponentMetadata), and Gatsby builds static pages at /categoryname/pagename.
Pros and cons
Pros:
- No database or CMS required; output is pure static files.
- Automatically extracts props tables, so docs stay in sync with code.
- Lightweight: only what you need, no extra dependencies.
Cons:
- By default, a component's data only appears if a matching MDX file exists; to generate pages purely from source code, you must modify
gatsby-node.jsas described in the README.
FAQ
Is Gatsby Documentation Starter free?
Yes, it is an open-source starter template, free to use and modify.
What are the prerequisites?
Node.js and the Gatsby CLI. You can install it with gatsby new docs https://github.com/whoisryosuke/gatsby-documentation-starter/.
How do I add a new component to the docs?
Add a JavaScript file and an MDX file with matching names under the configured source folder (default /src/components/). Set the page name in the JSDoc docblock and the name + menu in the MDX frontmatter.
Can I use it inside an existing project?
Yes, clone the repo into a docs subfolder, update the source folder in gatsby-config.js, run npm install and npm run develop.
