Docusaurus Versioning

Vanna — Fri, 03 Mar 2023 22:30:05 +0000

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!

From Docsify to Docusaurus

Vanna — Fri, 17 Feb 2023 17:08:31 +0000

For the past two weeks I’ve been working on transferring GraphGrid’s documentation site from Docsify to Docusaurus. Both of these open source documentation site generation tools are great but for our needs, switching to Docusaurus is a total upgrade.

With that total upgrade came a lot of excitement and ambitions to make our docs look and feel incredible.✨

Docsify, get your site up fast.. with some limitations

I did the initial work of creating our docs site with Docsify. At the time, our goal was to get our first docs site up quickly. Docsify is perfect for that. No build, no nonsense, just good ol’ markdown and HTML. Docsify has a lot of nice community-made plugins. However, because Docsify uses Vue, scalability and styling can be limited.

However, theres was one glaring detriment, Docsify is not SEO friendly. This is the main reason for switching to Docusaurus.

Docsify limited-to-none SEO support

Docsify does not generate static HTML files and uses hash routing (Google crawlers don’t really like that). As a single-page-application (SPA), that does not pre-render HTML, the search engine crawlers have to interpret javascript. This process slows the crawlers down because it uses a lot of its (the crawler’s) allocated budget.

Below is a helpful infographic posted on a GitHub forum about Docsify SEO by user SidVal. The infographic is from a writeup of an experiment by Bartosz Góralewicz, called "Can Google Properly Crawl and Index JavaScript Frameworks? A JS SEO Experiment."

Docsify is planning to add SEO support

There are plans for server-side rendering in Docsify version 5. I did reach out to Docsify’s community and there are ways around this until then, but unfortunately none of them work with the way we deploy our site. It would just be too much code and some hack-ish strategies to make it work. After accepting this fact, we decided to switch to another beloved, green-mascot having documentation site generator, Docusaurus.

Docusaurus has SEO AND style 😎

Docusaurus is more complex in that it has a build process, but worth it if you’re trying to create a customized, feature-rich site for your documentation.

Docusaurus uses MDX and React.. if that scares you, it’s okay! It’s still just as simple to initialize. Docusarus has excellent guides on styling and configuration. Even if you’re not very familiar with React, you can still set up a good-looking site without getting too much in the weeds. In addition, there are tons of plugins for low-code styling and quality of life features (Hi custom sidebars and live code snippets!).

Most importantly though, Docusaurus is SEO friendly! <3

HTML files are statically generated (unlike Docsify) for every URL so search engines can find and index your content. There is also a sitemap plugin called @docusaurus/plugin-sitemap that ships with the preset-classic version of Docusaurus by default. The sitemap.xml is autogenerated and will help crawlers crawl more accurately.

Conclusion

With all of this being said, both communities for Docsify and Docusaurus are quite active and helpful. If you’re planning on choosing a documentation site generator, take into account the tool’s SEO compliance and how easy it would be to configure. Also look into the available plugins. Will your docs site need charts, live code snippets, or other special features? There’s probably a plugin out there to use instead of having to build it out yourself! Be sure that your doc site generator supports your needs so that you can spend more time focused on content rather than building a documentation site.

DEV Community: Vanna