Docusaurus - Basic Config

09/10/2022, Sat

Documentation-centric Changes

Docusaurus is a JavaScript framework documentation generator. This tool provides many useful conveniences such as documentation versioning and search integration. Docusaurus gives you the ability to quickly get a working documentation site running by using a config-based means of manipulating your settings for the site. Even though it is config-based, one can drop to a lower level by changing JavaScript and styles files in the src source to make custom changes to your site.

Docs Mode

By default, the basic generator will also create blog pages when you run the following command.

npx create-docusaurus@latest my-website classic

However, one can prioritize the viewing of the docs pages by removing the /doc prefixing URl scheme.

In additional to performing the steps needed to prioritize the docs pages, the _categories.json should also be updated by removing the link key.

{
  "label": "Tutorial - Basics",
  "position": 2
}

From

http://localhost:3000/docs/tutorial-extras/manage-docs-versions

http://localhost:3000/tutorial-extras/manage-docs-versions

Doing this will also remove the page for original category link.

http://localhost:3000/docs/category/tutorial---basics

Versioning

Keeping track of the versions of your documentation is also an essential part of maintaining your documentation when you have a major release of product that significantly changes your API. You still would want the old version of the documentation around for people who have not yet migrated to the new version.

Very few documentation generators out there I see possess the ability to perform versioning which is rather unfortunate. With versioning in Docusaurus, you can keep historical versions of your documentation around. One downside in using versioning is that it cause more complexity in maintenance of your documentation.

Creating a new version can be done be using this command

npm run docusaurus docs:version 1.1.0

Then add the version list dropdown in the navbar by updating docusaurus.config.js

module.exports = {
  //...
  themeConfig: {
    navbar: {
      //...
      items: [
        {
          type: 'docsVersionDropdown',
          position: 'left',
          dropdownItemsAfter: [{to: '/versions', label: 'All versions'}],
          dropdownActiveClassDisabled: true,
        },
      ],
      //...
    },
  },
  //...
};

More information for versioning.

WH