Docusaurus Versioning

For reasons, I’m switching GraphGrid’s docs site from Docsify to Docusaurus. During this process I’m taking the opportunity to improve the site architecture. After getting the v1.4 docs building with Docusaurus, I had to start thinking about how I was going to pull in v2.0. I was anxious to implement the Docusaurus versioning CLI, because it relieves pain-points on both the development and user side.

GG has two versions 1.4 and 2.0. With the old site (the Docsify one), I maintained two separate branches (1.4 and 2.0). You can imagine that these separate branches often got out of sync, and when they were finally merged, there’s a conflict list longer than a CVS receipt. From an architectural standpoint, the old site did not provide an intuitive way to switch between versions. For example, to switch from the 1.4 to the 2.0 docs, the user had to edit the version path in the URL. Users also didn’t have any clear indication of what version of the docs they were on.

With Docusaurus versioning, we’re not able to maintain the docs version under 1 branch by combining the two versions (1.4 and 2.0). Now each version is updated synchronously, no more getting behind or merge conflicts! Docusaurus allows you to configure the versioning behavior.

Getting around default current docs version directory

By default, Docusaurus creates a directory for your project’s current version. For my use case it didn’t make sense to use the current version because we don’t publish pre-release docs.

Because the current version is baked in, I had to figure out how to un-bake it (unbaking is a term I just made up that means deconstructing a feature in order to construct another). This has been the most custom config I’ve had to do thus far because of a Docusaurus feature. I’m not complaining but R.I.P. github issue #1243.

If you’re trying to use Docusaurus versioning without /doc /next/ (“current version” or pre-release docs), you’re going to have to do some configuring.

Docusaurus suggests two versioning behavior patterns. You should use the 1st pattern if you want to publish prerelease docs. I used pattern 2 which outlines the necessary plugin options to use to achieve unbakening.

Unbake 🍪

Within the docs-plugin preset config I used lastVersion and set it to current. This combines the current version and the major version (this includes all default routes). This is the recipe to follow for those looking to not include the default current docs versioning template. No more “Next” in the dropdown, and no more routing nightmares!

Presentation

Now that we baked the site how WE want it, it's time to make it pretty. In the same configuration, I defined the label for the now combined current and major release version. This value will be used in the UI components like the navBar items. I set the path as root because I want this version to (2.0) to be the main docs.

docs {
    lastVersion: 'current',
    versions: {
        current: {
            label: '2.0',
            path: '/',
            badge: true
        }
    }
}

I added a version number badge, which isn't necessary but I like having a clear version indicator to prevent confusion.

Version NavBar

Next I added navbar items to improve the user experience. I added an item called `docsVersionDropdown` which adds a version drop down.

{
    type: 'docsVersionDropdown',
    position: 'left',
    dropdownActiveClassDisabled: true,
}

For more info and configuration options check out Docusaurus’s versioning docs!

Checkout out my blog for a demo video!