Newsletter
Join the Community
Subscribe to our newsletter for the latest news and updates
A minimalist Gatsby Theme for documentation sites built with MDX and Theme UI.
gatsby-theme-documentation is a minimalist Gatsby Theme that turns MDX files into a complete documentation website with Theme UI-based styling, sidebar navigation, and syntax highlighting.
gatsby-theme-documentation is a Gatsby Theme — a prebuilt plugin that supplies the data layer, page templates, and styling for a docs site — so you can focus on writing Markdown/MDX content instead of configuring a site from scratch. It takes MDX files (Markdown with embedded JSX components) as its content source and outputs a static docs website with a collapsible sidebar, a custom header, and mobile-friendly layout. The theme runs on Gatsby, a React-based static site generator, and is distributed on npm and GitHub under the johno account.
The theme's core differentiator is its minimal setup: one plugin entry in gatsby-config.js gets a working docs site, with all content authored as plain .mdx files on the filesystem. It also includes a Docs schema that exposes individual documents or collections via GraphQL, and it automatically routes every readme.md file to an index.html URL, matching how GitHub renders directories. The theme ships with MDX support, built-in syntax highlighting, a Theme UI design system for theming, and straightforward component shadowing for adding custom shortcodes, headers, and sidebars.
Open-source maintainers who need a clean documentation site for their project's GitHub directory without building a custom site. Technical writers who want to author docs in MDX and take advantage of JSX components inside Markdown. Developers who want a Gatsby starter for a personal knowledge base or API documentation and prefer Theme UI for styling. Anyone already using Gatsby who wants to add a docs section to an existing site by installing the theme as a plugin.
readme.md files, with automatic routing from /readme.md to /index.html.header.mdx, sidebar.mdx, and components.js through the Theme UI layer, letting you match the docs to your brand colors and typography.Docs type using allDocs to build custom index pages, search functionality, or tables of contents.Install the theme with yarn add gatsby-theme-documentation, then add gatsby-theme-documentation to the plugins array in your gatsby-config.js file. Author your documentation as MDX files in the project's content directory, and optionally customize the sidebar by shadowing src/gatsby-theme-documentation/sidebar.mdx, the header via header.mdx, or global components via components.js.
Place a sidebar.mdx file at src/gatsby-theme-documentation/sidebar.mdx in your site. The theme will pick up this shadowed file and populate navigation with its list of links, which can point to internal pages or external URLs.
When you have readme.md files inside content directories, the theme converts each one to an index.html page in the built site, so /docs/readme.md becomes /docs/index.html. Links throughout the site are automatically rewritten to match the new URL scheme.
Yes, the theme includes built-in syntax highlighting for code blocks out of the box, so code in your MDX files is rendered with language-aware highlighting without extra configuration.
Yes. Create src/gatsby-theme-documentation/components.js that imports and spreads the theme's base components, then add your custom components to the exported object. They become available as shortcode tags in any MDX doc.
