The day is finally here: We have launched a new version of our documentation site!
Why did we need a new site?
The Gatsby documentation has grown a lot in the last few years! Much of that growth happened organically, thanks to contributions from community members like you. (And we appreciate the help 💜!)
But recently we began hearing from Gatsby users that our docs were difficult to navigate, especially for newcomers. Our documentation had grown to a point where we needed to do some significant pruning.
What’s new?
New Structure 🏠
Inspired by Daniele Procida’s documentation system, Gatsby’s documentation is now broken down into four main types:
- Tutorial: A guided lesson that shows you how to create a Gatsby project from start to finish.
- Most useful for first-time Gatsby users trying to learn the basics.
- How-To Guides: Practical step-by-step guides to help you achieve a specific goal.
- Most useful when you’re trying to get something done.
- (Formerly “Reference Guides” and “Recipes”)
- Reference Guides: Nitty-gritty technical descriptions of how Gatsby works.
- Most useful when you need detailed information about Gatsby’s APIs.
- (Formerly “Gatsby API”, “Releases & Migrations”, and “Gatsby Internals”)
- Conceptual Guides: Big-picture explanations of high-level Gatsby concepts.
- Most useful for building understanding of a particular topic.
The How-To Guides and Reference Guides are broken down further into appropriate sections based on the specific topic. We hope that this logical structure will make it easier to find the information you need when you need it.
Looking for a specific doc from the old site? We tried to pull in all the essential docs into our new structure. But if you need a particular doc from the old site, the URLs to those docs haven’t changed. You can use the search bar, a search engine, or your browser history to find what you’re looking for.
New Design 💅
We also made some significant improvements to the user interface:
- The navigation menu at the top of the page shows the four types of documentation, to help you keep the overall structure of the docs in mind.
- The sidebar content now changes based on what type of documentation you’re currently looking at.
- New landing pages make it easier to see the big picture of what’s included about a topic.
What’s next? 🔮
Reorganizing our existing docs was just the first step toward improving our docs. There’s still a lot of work to do!
On our end, here are the tasks we’re planning to tackle next:
- Update the Contributing Guidelines to use the new docs structure, so that we can unfreeze community documentation contributions.
- Make deeper edits to individual docs, to make them more approachable for Gatsby newcomers.
- Polish the redesigned user interface to continue improving the reader experience.
In the meantime, we’d love to hear your feedback on the new docs site! What do you like about it? What suggestions do you have for further improvements? Let us know in the GitHub discussion for this project.
Gatsby’s documentation is always growing. We are grateful to all the contributors who helped us create our docs, and community feedback is essential for helping us continue optimizing their accessibility!