Search code examples
docusaurus

Docusaurus: How can I have multiple versions of different docs in the docs directory?

I'm working with Docusaurus to create a documentation site for 3 different education courses - all within the docs folder.

So I'm looking for a way to have the version be different across folders in there, or figure out what the best strategy for this is.

Right now, in my docusaurus.config.js I have:

module.exports = {
  presets: [
    '@docusaurus/preset-classic',
    docs: {
      lastVersion: 'current',
      versions: {
        current: {
          label: '1.0.0',
          path: '1.0.0',
        },
      },
    },
  ],
};

But I'm not sure how to keep track of 3 different versions across 3 different docs all within the same site.

Solution

    1. Swizzle the navbar via wrapping yarn run swizzle @docusaurus/theme-classic NavbarItem/DocsVersionDropdownNavbarItem -- --wrap

    2. Modify the swizzled component like so:

    src/theme/NavbarItem/DocsVersionDropdownNavbarItem.js:

    import React from "react";
import DocsVersionDropdownNavbarItem from '@theme-original/NavbarItem/DocsVersionDropdownNavbarItem';
import { useLocation }  from '@docusaurus/router';

export default function DocsVersionDropdownNavbarItemWrapper(props) {
  const { docsPluginId, className, type } = props
  const { pathname } = useLocation()
  
  /* (Custom) check if docsPluginId contains pathname
  Given that the docsPluginId is 'charge-controller' and the routeBasePath is 'charge-controller', we can check against the current URI (pathname).
  If the pathname contains the docsPluginId, we want to show the version dropdown. Otherwise, we don't want to show it.
  This gives us one, global, context-aware version dropdown that works with multi-instance setups.
  You want to declare a version dropdown for each plugin in your navbarItems config property for this to work well.
  const doesPathnameContainDocsPluginId = pathname.includes(docsPluginId)
  if (!doesPathnameContainDocsPluginId) {
    return null
  }
  return <DocsVersionDropdownNavbarItem {...props} />;
}

    For this to work, you need to have your documentation (based on products) split up using multi-instances: (https://docusaurus.io/docs/docs-multi-instance#docs-navbar-items)

    Note that the preset docsPlugin ID always is "default".

    You can try to use

    import {
  useActivePluginAndVersion,
} from '@docusaurus/plugin-content-docs/client';

const version = activePluginAndVersion.activeVersion.name; // use label instead of name if issues arise.

    instead to get the current docsPluginId, name or label.

    This would be the more "robust" solution I think. That said, we do use the solution I provided above as-is and it works fine for now.