Introduction

The Gatsby Documentation Starter is a powerful tool designed to automatically generate documentation for React components. It leverages MDX, react-docgen, and GatsbyJS to create a comprehensive and interactive documentation system. This starter kit is ideal for developers who want to streamline their documentation process and create a user-friendly interface for their component libraries.

Main Features

1. MDX Integration: Write documentation in Markdown and seamlessly include React components using JSX.
2. Automatic Component Parsing: Uses react-docgen to analyze React components for JS Docblocks and Prop Types.
3. GatsbyJS Framework: Creates a local GraphQL server for building static documentation sites.
4. Props Table Component: Displays component props in an organized table format.
5. Modular Design: Easy to install and integrate into existing projects.
6. Lightweight: Includes only essential dependencies.
7. Customizable Sidebar Navigation: Automatically generated from component MDX files and configurable static pages.
8. Flexible Source Configuration: Easily change the location of your components and MDX files.
9. Multiple Component Source Support: Add multiple file sources as needed.
10. Automatic Page Generation: Creates pages based on MDX files or react-docgen data.

Installation Steps

1. Clone the repository:

   git clone https://github.com/whoisryosuke/gatsby-documentation-starter.git
   

2. Navigate to the project directory:

   cd gatsby-documentation-starter
   

3. Install dependencies:

   npm install
   

4. Update gatsby-config.js with the location of your components and MDX files.

5. Start the development server:

   npm run develop
   

6. View your documentation at http://localhost:8000

Usage Instructions

1. Creating Documentation:

   • Write JS Docblocks and Prop Types in your React component files.
   • Create corresponding MDX files for additional documentation and examples.

2. Customizing Sidebar Navigation:

   • Edit the sidebar object in gatsby-config.js for static pages.
   • Component pages are automatically generated from MDX files.

3. Changing Source Folder:

   • Modify the gatsby-source-filesystem configuration in gatsby-config.js.

4. Adding to Existing Projects:

   • Clone the repo into a docs subfolder of your project.
   • Adjust the source folder configuration if needed.

5. Creating Pages from react-docgen:

   • Modify gatsby-node.js to generate pages based on react-docgen data instead of MDX files.

6. Customizing Page Templates:

   • Edit the template in src/templates/posts.js to change the layout of documentation pages.

Important Notes

1. Ensure your component names in JS Docblocks match the names in MDX files for proper documentation generation.

2. The sidebar navigation combines static pages from config and dynamically generated component pages.

3. You can add multiple file sources in gatsby-config.js to document components from different locations.

4. The starter is designed to be embedded in existing projects, making it versatile for various use cases.

5. Custom page generation can be achieved by modifying gatsby-node.js to use react-docgen data instead of MDX files.

6. The project uses GraphQL to query component metadata and MDX content, allowing for flexible data retrieval.

7. Regularly update dependencies to ensure compatibility with the latest versions of Gatsby, MDX, and react-docgen.

8. The starter is open-source and licensed under MIT, allowing for modification and commercial use.

9. For advanced customizations, familiarize yourself with Gatsby's plugin system and GraphQL queries.

10. Consider contributing to the project or reporting issues on the GitHub repository to help improve the starter kit.