Introduction

Gatsby Theme Documentation is a minimalist theme designed for creating documentation websites using Gatsby. It leverages MDX for content creation and Theme UI for styling, providing a powerful and flexible foundation for building documentation sites. This theme allows developers to quickly set up a professional-looking documentation website and focus on writing content rather than dealing with complex setup and design issues.

Main Features

1. MDX support for writing content with JSX in Markdown
2. Theme UI-based theming for consistent and customizable styling
3. Syntax highlighting for code blocks
4. MDX-based sidebar navigation
5. Automatic readme routing for GitHub-like directory structure
6. Shortcode support with React components
7. Collapsible menu for improved navigation
8. Mobile-friendly design
9. Custom docs schema for flexible content management
10. Easy customization of sidebar and header content
11. Component shadowing for extending functionality

Installation Steps

1. Install the theme in your Gatsby project:

   yarn add gatsby-theme-documentation
   

2. Add the theme to your gatsby-config.js:

   module.exports = {
     plugins: ['gatsby-theme-documentation']
   }
   

3. Alternatively, use one of the starter templates:

   • Base: gatsby new my-docs johno/gatsby-starter-documentation
   • Dark: gatsby new my-docs johno/gatsby-starter-documentation-dark
   • Tomato: gatsby new my-docs johno/gatsby-starter-documentation-tomato

Usage Instructions

1. Customizing the Sidebar:

   • Create a file at src/gatsby-theme-documentation/sidebar.mdx
   • Use MDX syntax to define your navigation structure

2. Customizing the Header:

   • Create a file at src/gatsby-theme-documentation/header.mdx
   • Use MDX to customize the header content

3. Adding Component Shortcodes:

   • Create src/gatsby-theme-documentation/components.js
   • Import base components and extend them with custom components

4. Writing Documentation:

   • Create MDX files in your project's docs directory
   • Use GitHub-style readme.md files for automatic routing

5. Querying Documentation:

   • Use GraphQL to query individual documents or collections
   • Utilize the custom Docs schema for flexible content management

6. Styling:

   • Leverage Theme UI for consistent theming across your site
   • Customize colors, typography, and other design elements

7. Deploying:

   • Build your site using Gatsby's build command
   • Deploy the resulting static files to your preferred hosting platform

Important Notes

1. The theme uses MDX, allowing you to use JSX and React components directly in your Markdown files.

2. Readme routing automatically converts file/path/readme.md to /file/path/index.html in the built site.

3. The sidebar and header can be easily customized using MDX files, allowing for flexible navigation and branding.

4. Component shadowing can be used to extend or override theme components and functionality.

5. The theme provides a custom Docs GraphQL schema, enabling powerful querying and manipulation of documentation content.

6. The collapsible menu feature improves navigation, especially on mobile devices.

7. Syntax highlighting is included out of the box for improved code readability.

8. The theme is designed to be minimal and performant, focusing on content presentation.

9. Theme UI integration allows for consistent and easily customizable styling across the entire site.

10. The theme is actively maintained and has a growing community, ensuring ongoing support and improvements.