Improving the developer experience for appbase.io docs
We’re excited to share a major update for appbase.io’s developer docs site— with enhancements such as support for a dark theme mode, improved documentation search experience, code highlighting / copying support as well as core performance improvements to SEO and page load times.
Background and Gatsby
Our docs are built using Gatsby — a popular and open-source React framework for building websites and apps. However in the last couple of years, Docusaurus has emerged as a popular and focused alternative for an all batteries included approach to building a documentation site.
Given that we were already using Gatsby with hundreds of routed pages and using many features such as a custom navigation layout with picker for frontend libraries, a 0ms latency search box based on an offline index, our preference was to stay with Gatsby instead of migrating to a new tool like Docusaurus.
Besides, Gatsby being a framework and not being opionated would allow us to have more flexibility to make future enhancements, such as make use of server-side rendering.
It turns out that tuning performance as well as making several of the enhancements is indeed easy with Gatsby! The rest of the post walks through the enhancements. If you would like to incorporate any of these for your own documentation, our docs are built in the open on Github and licensed under MIT. Feel free to star or fork them.
Introducing dark mode
The docs now fully support viewing in dark mode.
Our docs primarily utilize the appbase.io design kit for several components like the TimelineOption component above. Cards, navbar, footer are all components that come from this. We introduced a dark theme option in these components first. The docs are built using Gatsby, the next changes to support theming were done in the core repository itself.
On mobile screens, we show the theme switcher with the menu navigation’s footer.
The default theme is also auto-set based on a user’s OS display preferences.
Searchbox enhancements
We’ve improved the documentation search experience with a wider screen space, a first-class keyboard accessibility support, showing and a quick suggestion view of recently viewed pages.
Code highlighting and copy snippet options
All the code snippets in the docs now support syntax highlighting using prismjs as well as support a copy snippet button.
Performance enhancements
appbase.io docs are a fully progressive web app that can be installed as an app when viewing from mobile and are also heavily SEO optimized.
We also focused on other performance enhancements such as using Loadable components, upgrading to Gatsby v4 (current major version) as well as utilizing several Gatsby plugins to reduce the Javascript needed for the docs to be interactive.
Open Source | Star it or fork it
If you are interested in incorporating any of these changes to your own documentation site, our docs are hosted in the open on Github and licensed under an MIT license. Go star it or fork it.
