Introduction

Gatsby-theme-apidocs is an opinionated Gatsby theme designed specifically for creating technical documentation. Developed by Carrot Search, this theme provides a comprehensive solution for developers and technical writers looking to create high-quality, responsive, and feature-rich documentation websites. It leverages the power of Gatsby, a modern static site generator, to deliver fast and optimized documentation sites.

Main Features

• HTML-based content authoring for easy writing and formatting
• Responsive and mobile-friendly layout for optimal viewing on all devices
• Dual color scheme with dark and light modes for user preference
• HighlightJS integration for code syntax highlighting
• Sublime-style client-side search functionality for quick content access
• Medium.com style image zooming for detailed visual examination
• Near-perfect Lighthouse score, ensuring excellent performance, accessibility, and SEO
• Out-of-the-box configuration requiring minimal setup

Installation Steps

1. Create a new Gatsby site using the APIDocs starter:

   gatsby new my-apidocs-site https://github.com/carrotsearch/gatsby-starter-apidocs
   

2. Navigate to your new project directory:

   cd my-apidocs-site
   

3. Install dependencies:

   yarn install
   

4. Start the development server:

   gatsby develop
   

5. Your documentation site should now be running at http://localhost:8000

Usage Instructions

1. Content Creation:

   • Add your documentation content as HTML files in the content directory
   • Use standard HTML tags and custom components provided by the theme

2. Configuration:

   • Modify gatsby-config.js to adjust site metadata and theme options
   • Customize the src/gatsby-theme-apidocs/components directory to override default components

3. Styling:

   • Utilize the built-in dark and light color schemes
   • Customize styles by modifying CSS files in the theme or creating your own

4. Search Functionality:

   • The Sublime-style search is automatically configured
   • Ensure your content is properly structured for optimal search results

5. Code Highlighting:

   • Use appropriate language tags in your code blocks for syntax highlighting

6. Image Handling:

   • Place images in the appropriate asset folders
   • Utilize the medium.com style zooming feature for detailed images

7. Building for Production:

   gatsby build
   

8. Preview the production build:

   gatsby serve
   

Important Notes

1. This theme is opinionated, meaning it comes with predefined structures and styles. While customizable, it's best suited for projects that align with its design philosophy.

2. Regularly update the theme and its dependencies to benefit from the latest features and security patches.

3. The theme aims for a near-100 Lighthouse score. Be cautious when adding custom features that might impact performance or accessibility.

4. While the theme provides HTML-based authoring, consider using Markdown if you prefer, though this may require additional configuration.

5. The search functionality is client-side, which works well for most documentation sites. For very large sites, consider implementing a server-side search solution.

6. Test your documentation site across various devices and browsers to ensure responsiveness and compatibility.

7. Leverage Gatsby's plugin ecosystem to extend functionality beyond what the theme offers out-of-the-box.

8. Familiarize yourself with Gatsby's documentation and development practices for optimal use of this theme.

9. Consider contributing to the theme's development or reporting issues on the GitHub repository to help improve it.

10. When deploying, choose a hosting solution that supports static sites for best performance and simplicity.