Skip to main content
Version: Canary 🚧

Docus Tips

Tagging a new version​

  1. First, make sure the current docs version (the ./docs directory) is ready to be frozen.
  2. Enter a new version number.
npm run docusaurus docs:version 1.1.0

When tagging a new version, the document versioning mechanism will:

  • Copy the full docs/ folder contents into a new versioned_docs/version-[versionName]/ folder.
  • Create a versioned sidebars file based from your current configuration (if it exists) - saved as versioned_sidebars/version-[versionName]-sidebars.json.
  • Append the new version number to versions.json.

Creating new docs​

  1. Place the new file into the corresponding version folder.
  2. Include the reference to the new file in the corresponding sidebar file according to the version number.
# The new file.
docs/new.md

# Edit the corresponding sidebar file.
sidebars.js

Configuring versioning behavior​

The "current" version is the version name for the ./docs folder. There are different ways to manage versioning, but two very common patterns are:

  • You release v1, and start immediately working on v2 (including its docs). In this case, the current version is v2, which is in the ./docs source folder, and can be browsed at example.com/docs/next. The latest version is v1, which is in the ./versioned_docs/version-1 source folder, and is browsed by most of your users at example.com/docs.
  • You release v1, and will maintain it for some time before thinking about v2. In this case, the current version and latest version will both be point to v1, since the v2 docs doesn't even exist yet!

Docusaurus defaults work great for the first use case. We will label the current version as "next" and you can even choose not to publish it.

For the 2nd use case: if you release v1 and don't plan to work on v2 anytime soon, instead of versioning v1 and having to maintain the docs in 2 folders (./docs + ./versioned_docs/version-1.0.0), you may consider "pretending" that the current version is a cut version by giving it a path and a label:

docusaurus.config.js
export default {
  presets: [
    '@docusaurus/preset-classic',
    docs: {
      lastVersion: 'current',
      versions: {
        current: {
          label: '1.0.0',
          path: '1.0.0',
        },
      },
    },
  ],
};

The docs in ./docs will be served at /docs/1.0.0 instead of /docs/next, and 1.0.0 will become the default version we link to in the navbar dropdown, and you will only need to maintain a single ./docs folder.

See Configuring versioning behavior for more details.

Following the example above, if a commonDoc is included in both sidebars:

sidebars.js
export default {
  tutorialSidebar: {
    'Category A': ['doc1', 'doc2', 'commonDoc'],
  },
  apiSidebar: ['doc3', 'doc4', 'commonDoc'],
};

How does Docusaurus know which sidebar to display when browsing commonDoc? Answer: it doesn't, and we don't guarantee which sidebar it will pick.

When you add doc Y to sidebar X, it creates a two-way binding: sidebar X contains a link to doc Y, and when browsing doc Y, sidebar X will be displayed. But sometimes, we want to break either implicit binding:

  1. How do I generate a link to doc Y in sidebar X without making sidebar X displayed on Y? For example, when I include doc Y in multiple sidebars as in the example above, and I want to explicitly tell Docusaurus to display one sidebar?
  2. How do I make sidebar X displayed when browsing doc Y, but sidebar X shouldn't contain the link to Y? For example, when Y is a "doc home page" and the sidebar is purely used for navigation?

Front matter option displayed_sidebar will forcibly set the sidebar association. For the same example, you can still use doc shorthands without any special configuration:

sidebars.js
export default {
  tutorialSidebar: {
    'Category A': ['doc1', 'doc2'],
  },
  apiSidebar: ['doc3', 'doc4'],
};

And then add a front matter:

commonDoc.md
---
displayed_sidebar: apiSidebar
---

Which explicitly tells Docusaurus to display apiSidebar when browsing commonDoc. Using the same method, you can make sidebar X which doesn't contain doc Y appear on doc Y:

home.md
---
displayed_sidebar: tutorialSidebar
---

Even when tutorialSidebar doesn't contain a link to home, it will still be displayed when viewing home.

If you set displayed_sidebar: null, no sidebar will be displayed whatsoever on this page, and subsequently, no pagination either.