The availability and quality of documentation are perhaps the most valuable assets for helping developers do their job. Likewise, good documentation will make the difference for users in choosing one product instead of another. However, finding the right tooling for managing and hosting documentation it’s a whole task on its own. It is even harder for open-source projects, whose developers might not have the resources for setting up and maintaining a documentation website that can live up to their product. In this last regard, Docusaurus is an open-source project that aims to make it easy for developers to build, deploy, and maintain documentation websites. In this article, we’ll take a closer look at Docusaurus’ features and how it tackles the main concerns of complex documentation projects.
Edited transcription
Docusaurus is a static site generator designed to quickly build and get online documentation and blog websites. “We market Docusaurus as a content-centric website generator, but it’s also very flexible and you can create any kind of website,” says Sébastien Lorber, Docusaurus’ lead developer and maintainer.
As Sébastien explains, Docusaurus emerged from the necessity of a method for documenting open-source projects with higher levels of customization. Creating a custom documentation site requires investing time and money, an investment that grows exponentially when working with different documentation projects. The industry’s cheap and straightforward alternative is using Jekyll templates. Yet, this approach has flaws of its own. ”Every time you make an update to add new features to the template, you have to backport these new updates to all the documentation projects one by one,” Sébastien says.
How Docusaurus works
Just like Jekyll, Docusaurus is a single-page static site generator. Single-page websites show content on a single page instead of being broken up into different ones like most websites. Single-page websites are simpler to browse and reduce load times from the user end.
“The idea of Docusaurus was to create a tool where you can just write Markdown files and then have some configuration,” says Sébastien. Docusaurus simplifies the website configuration process by making it as simple as writing a Markdown file as you would document a GitHub repository. On the server side, Docusaurus uses React, employing an extended version of markdown known as MDX, which integrates JavaScript’s syntax extension JSX. In this way, Docusaurus is able to render Markdown files as React components and provide extra capabilities like embedded components and support for testing.
What’s more, Docusaurus can be deployed in a glimpse. For hosting a Docusaurus static website,Sébastien recommends using Jamstack providers such as Vercel or Netlify. These services offer a deployed preview in a way that “if you edit docs in your pull request, you can have a deployment preview being posted in the pull request with a link where the reviewer can just click on the link and see the updated doc live.” Docusaurus makes validating changes as straightforward as taking a look at the preview without having to check it out locally.
Following, we will mention the main features of Docusaurus that Sébastien shared with us.
Content search
Search and indexation is one of the main assets users have when using a knowledge base. For helping users find the exact piece of information they are looking for, Docosaurus uses DocSeach, a tool from the product search and discovery engine software Algolia.
This search plugin, explains Sébastien, “crawls the HTML files that we generate and creates some kind of JSON file with all the search tokens that the search engine will use.” Additionally, Docusaurus has integration to add required UI elements such as search boxes and search results display. Moreover, community plugins are also available for local searches.
User authentication
User authentication is necessary to show documentation to certain users exclusively, as in the case of a team developing a product privately. Previously-mentioned hosts for Docusaurus like Netlify and Vercel offer options such as defining a user and password credentials for accessing the static files.
Another alternative is using edge functions. An edge function is an endpoint or application that runs on the edge of a network. Edge functions are often used to perform tasks in the server closer to the user that would normally be performed by a centralized server. This includes tasks like processing data, providing cloud services, and, in this case, authenticating the user. Edge functions can be run before serving the static files on the host, in a way that allows, as Sébastien puts it, “to add an authentication workflow on top of a static site.” The edge function can check if a user has the right cookie and decide if redirects him to a given logging page or static website or not.
Translation-ready
Documentation needs to be available in the language the user decides to use the product. Docusaurus supports localization through an internationalization file system convention known as i18n. “If you have documentation, you can just copy this documentation to a new folder and then you will be able to add the new locale that you want to have on your site to the config, and then you run the Docusaurus key, and you will build your site for the two locals,” explains Sébastien.
In Docusaurus, each locale is sandboxed in a separate single-page application located in a specific folder. “You will build, for example, a single-page application for the English locale, and then you will build one for the French locale,” says Sébastien.
Documentation versioning
When different versions of the same software product are available, documentation has to split up. While new versions need to be documented, legacy versions’ documentation has to remain available for those still using them. Historically, points out Sébastien, the most popular approach for this task is a “versioning strategy based on Git branches”: the main branch has the documentation of the currently developed version, while an archived branch holds the documentation of previous versions. However, Sébastien understands that “the problem with this model is that, sometimes, you have a lot of small versions that are quite consecutive, and when you do some edits in one branch, then you have to backport the changes to the previous versions because it’s still relevant.”
In turn, to backport changes, Docusaurus has the documentation of all the versions in the main branch by default. Instead of branches, Docusaurus uses a folder system to version the documentation. In this way, “if you have to edit some docs, instead of backporting the change to all the older versions, you can directly edit all the versions that went in the same branch and submit in the single pull request with all the changes,” says Sébastien. Lastly, in case of very old versions that won’t be updated nor have to be backported, these can be archived and uploaded to a standalone branch.
The bottom line
Sébastien is currently working on Docusaurus’ 3.0 version. By upgrading the support for React components into Markdown files, this future version will focus on improving documentation interactivity even further.
Follow Sébastien on Twitter. Sébastien also writes a React newsletter with more than 10,000 subscribers known as This Week in React in French and English.
To learn more about Docusaurus, visit docusaurus.io or try a live demo.
