Migrating the ScalarDB and ScalarDL Docs Sites from Jekyll to Docusaurus
In mid-2023, we launched documentation sites for ScalarDB and ScalarDL. In fact, you may even remember that we previously wrote a post about launching those docs sites. Making our documentation available in a way that was searchable and navigable was a big step forward in helping users learn how to use our products.
However, as the sites and the internal processes related to maintaining them grew in complexity, we needed to migrate to a more scalable and feature-rich static site generator. After researching other solutions, we chose Docusaurus.
In this blog post, I’ll describe our reasons behind migrating from Jekyll to Docusaurus, the steps we took, and the benefits we’ve observed after migrating.
Why did we migrate from Jekyll to Docusaurus?
We initially chose to build our docs sites on Jekyll since we saw it as the most mature static site generator at the time. Although Jekyll and the theme we were using served us well initially, we eventually realized several limitations:
- Complexity in customization: Customizing the Jekyll theme to meet our evolving needs became increasingly complex and time-consuming. In particular, we needed to implement collapsible sidebar navigation, but this required significant customizations in the Jekyll theme that we were using.
- Plugin ecosystem: While Jekyll has a range of plugins, the ecosystem isn’t as extensive or as modern as we would’ve liked, especially for integrating JavaScript frameworks and interactive components. In addition, since we host our docs sites through GitHub Pages, we were limited in which Jekyll plugins we could use.
- Docs experience: We wanted a more interactive and user-friendly docs experience, with features like versioning, powerful search capabilities, and an overall modern look and feel.
Docusaurus, developed by Facebook, emerged as the ideal solution to address these challenges. The open-source static site generator is specifically designed for docs sites, offering a rich set of features out of the box.
Migration process
Migrating from Jekyll to Docusaurus involved several critical steps, which I’ll explain below.
Planning and preparing
We began with a thorough audit of our existing docs. This included identifying all versions of docs, understanding how the structure of the docs needed to fit in Docusaurus, and noting any custom features or plugins that we were using in Jekyll.
The bulk of the work involved changing parts like admonitions and tabs from a mix of HTML and Liquid syntax that we used in Jekyll to React components and the built-in features in Docusaurus. And, since we wanted to take advantage of React components in our docs, we also needed to change all Markdown file extensions from .md to .mdx. To ensure the best experience on our docs site, we needed to apply these changes across all versions of our docs for both ScalarDB and ScalarDL.
Setting up and customizing
To set up Docusaurus, we initialized a new project by using the Docusaurus CLI. This provided us with a robust starting point with essential doc site features pre-configured.
From there, we took advantage of the highly customizable theme in Docusaurus. We adjusted the theme to align with our branding and incorporated necessary components and customizations, like support for versions, tabs on pages, and Algolia DocSearch, to enhance the user experience. Many of the customizations that we made were common among other organizations’ docs sites, so we were able to implement these customizations without building those features from the ground up.
Testing and deploying
After migrating from Jekyll to Docusaurus but before deploying the new docs sites, we performed extensive testing to ensure that links, tabs, admonitions, version navigation, and other aspects were functioning correctly. The Docusaurus CLI includes a handy tool for ensuring that the site builds correctly and for checking for broken links, which is especially useful because docs site owners may not know when internal or external links or anchors are no longer navigable.
After resolving show-stopping errors, we deployed the new docs sites by using GitHub Pages, benefiting from the seamless CI/CD workflow that Docusaurus provides as part of its setup guide. In addition, as part of each pull request to the docs site, a test is done to check that the sites will be deployed as expected and without errors.
After thorough testing, we released the updated docs sites, which you can find at:
In addition, our docs sites are open source, so feel free to browse the following repositories to see how we’ve set up Docusaurus:
Benefits realized
Switching to Docusaurus has brought us several immediate benefits, including:
- Improved navigation experience: With built-in hierarchical navigation, users can now find information more efficiently by expanding and collapsing categories in the sidebar.
- Enhanced search experience: Since Docusaurus officially supports Algolia DocSearch, we’re able to offer users with an enhanced search experience that provides improved search results that get better over time.
- Better versioning experience: With a purpose-built versioning structure, we can now better manage and present multiple versions of docs, catering to users who might be using different versions of ScalarDB or ScalarDL.
- Easy-to-implement components and customizations: Since Docusaurus is based on React, a wealth of modern components and themes exist. Having access to components and themes reduces the need for us to tackle major customization projects, enabling us to focus more on the content and less on customizing and coding features from the ground up.
- Passionate community support: The active Docusaurus community provides a wealth of components, themes, and support, so finding answers to questions and understanding how we can improve our docs sites requires less effort and guesswork.
Wrap-up
The migration from Jekyll to Docusaurus has been a transformative step for the ScalarDB and ScalarDL docs sites. Our newly implemented static site generator not only enhances the user experience but also empowers us to efficiently manage and update docs as we continue to enhance ScalarDB and ScalarDL. We’re excited about the possibilities this migration opens up, especially in how it will help our users and contributors.
I hope the experience I’ve shared provides insight and inspiration if you’re considering transitioning to a different static site generator.
If you’d like to learn more about our solutions, visit the following product pages:
