Gatsby Gitbook Starter

Gatsby Gitbook Starter is a Gatsby + MDX boilerplate for building GitBook-style documentation and tutorial websites, created by Hasura to power the GraphQL tutorial series at learn.hasura.io. It turns Markdown and MDX files into a static site with a sidebar, search, dark mode, and offline support.

What is Gatsby Gitbook Starter?

Gatsby Gitbook Starter is a starter template built on Gatsby, a React-based static site generator, that compiles Markdown and MDX files from a content folder into a documentation website. It produces a static site that can be deployed as Docker containers or to platforms like Netlify and Now.sh, and it is maintained by Hasura. The template includes a GitBook-inspired theme, automatic sidebar navigation, and built-in SEO features.

Key Features

• Markdown and MDX support — Write content in plain Markdown or extend it with JSX via MDX, enabling rich embeds and interactive components.
• GitBook-style theme — A clean, consistent look similar to the GitBook documentation tool, ready to use out of the box.
• Syntax highlighting with Prism — Code blocks are highlighted, and diff highlighting is available as a bonus for showing changes.
• Algolia search integration — Enable full-text search by configuring the search object in config.js with your Algolia app ID, search key, and admin key; the index is built during the Gatsby build.
• Progressive Web App (PWA) — The site works offline when the pwa configuration is enabled in config.js, with a manifest for installability.
• Google Analytics integration — Set your tracking ID in the gatsby config section to get site analytics.
• Automatic sidebar and navigation — The sidebar is generated from your file structure, with optional forced navigation order, sub-nesting via folders, and next/previous links.
• Dark mode toggle — Users can switch between light and dark themes.
• Edit on GitHub — Each page can link to its source file for easy community contributions.
• Live code editor — Add react-live=true to any code block to render an editable React component.

Who should use Gatsby Gitbook Starter?

Documentation teams and open-source projects that want a fast, static docs site without building from scratch can use this starter. Tutorial creators who write multi-part content in Markdown and want a consistent theme with search and navigation benefit from the automatic sidebar and previous/next links. Developers already familiar with Gatsby or React can quickly customize the theme and layout to match their brand.

Use cases

• Tutorial series authors: Write a multi-language tutorial series in Markdown or MDX, publish it under a subpath (e.g., learn.hasura.io), and get a site with sidebar navigation, searching, and code highlighting.
• Open-source project maintainers: Host project documentation with an "Edit on GitHub" link so readers can contribute fixes directly.
• Technical writers: Use MDX to embed live code examples, interactive diagrams, or custom React components inside documentation pages.
• Teams needing offline docs: Enable the PWA option so users can access the documentation even without a network connection.

How does Gatsby Gitbook Starter work?

After cloning the repository and running npm install and npm start, a development server runs at localhost:8000. Content lives in the content folder as Markdown files; config.js controls global settings for the header, sidebar, site metadata, search, and PWA. The build command (npm run build) produces a static site and, if enabled, indexes content into Algolia. Deployment targets include Netlify, Now.sh, and Docker containers.

FAQ

How do I add Algolia search to my docs?

To enable search, open config.js and set the search.enabled flag to true, then provide your Algolia index name, app ID, search key, and admin key (the keys can be stored as environment variables). Run npm run build to generate the index, and search will work on the deployed site.

Does the site work offline?

Yes, when the pwa.enabled option is set to true in config.js, a service worker is registered and the site gains offline functionality. Disabling this option removes the existing service worker.

Can I use the live code editor?

Yes. Add the string react-live=true to any code block's language tag (for example, three backticks followed by javascript react-live=true) to render an editable React component that readers can modify in the browser.

How do I customize the sidebar navigation?

Set the forcedNavOrder array in the sidebar section of config.js to specify the order of top-level pages, using paths like "/filename". To create sub-navigation, place a folder with the same name as a top-level Markdown file; its contents will appear nested and sorted alphabetically. The ignoreIndex flag hides the index.md from the sidebar.

Is this starter free to use?

Yes, this is an open-source starter template. You can clone the repository from GitHub and use it for any project, including commercial documentation sites.