Introduction

Greenboard is a Gatsby theme designed for creating beautiful API documentation. It allows developers to generate static sites from markdown files, leveraging the power of Gatsby and React. Greenboard offers a fully customizable solution for API documentation with features like dark mode and a structure similar to Slate docs.

Main Features

1. Static site generation from markdown files
2. Utilizes Gatsby and React features
3. Fully customizable documentation
4. Dark mode support
5. Structure similar to Slate docs
6. Easy integration with existing Gatsby projects
7. Responsive design for various devices
8. Fast loading times due to static site generation
9. SEO-friendly documentation pages
10. Support for code syntax highlighting

Installation Steps

1. Set up a new directory for your documentation:

   mkdir my-docs
   cd my-docs
   yarn init
   

2. Install Gatsby and React dependencies:

   yarn add gatsby react react-dom
   

3. Install Greenboard:

   yarn add gatsby-greenboard
   

4. Add Greenboard to your gatsby-config.js:

   module.exports = {
     plugins: [
       {
         resolve: "gatsby-greenboard",
         options: {},
       },
     ],
   };
   

5. Create your API documentation in data/index.html.md.

6. Run your Gatsby site:

   yarn gatsby develop
   

7. Build production files:

   yarn gatsby build
   

Usage Instructions

1. Structure your documentation:

   • Use the data/index.html.md file to write your API documentation.
   • Follow the sample format provided in the Greenboard repository.

2. Customize the theme:

   • Fork the Greenboard repository for advanced customization.
   • Clone the forked repo and install dependencies.

3. Develop locally:

   yarn workspace example develop
   

4. Build the example:

   yarn workspace example build
   

5. Deploy to GitHub Pages:

   yarn workspace example deploy
   

6. For non-root path deployment:

   • Add pathPrefix to gatsby-config.js:

     module.exports = {
       pathPrefix: `/docs`,
     };
     

   • Build with the path prefix:

     yarn workspace example build --prefix-paths
     

7. Customize styling:

   • Modify CSS files in the Greenboard theme to adjust the appearance.

8. Add new pages:

   • Create additional markdown files in the data directory.

9. Implement dark mode:

   • Use the built-in dark mode feature in your documentation.

10. Optimize for SEO:

    • Utilize Gatsby's SEO features and plugins for better search engine visibility.

Important Notes

1. Ensure you have Node.js and Yarn installed on your system before starting.

2. Familiarize yourself with Gatsby and React documentation for advanced usage.

3. The project structure follows Slate docs, which may be helpful for those familiar with that format.

4. Regularly update Greenboard and its dependencies for new features and security patches.

5. Test your documentation on various devices and browsers to ensure compatibility.

6. Use version control (e.g., Git) to track changes in your documentation.

7. For complex customizations, consider forking the Greenboard repository.

8. Optimize images and assets for faster loading times.

9. Utilize Gatsby's plugin ecosystem to extend functionality if needed.

10. Reach out to the maintainer at shamin616@gmail.com for additional help or feature requests.