How to Fix Docusaurus Versioned Docs

In this tutorial, you'll learn about How to Fix Docusaurus Versioned Docs. We cover key concepts, practical examples, and best practices.

Your Docusaurus versioned documentation shows 404s for older versions, the version dropdown is missing, or versioning commands fail.

The Wrong Way

# Manually creating version folders
mkdir versioned_docs/version-1.0
mkdir versioned_sidebars/version-1.0

Manual directory creation breaks the versioning system. Always use the CLI.

The Right Way

Step 1: Use the Docusaurus versioning CLI

npm run docusaurus docs:version 1.0

This automatically:

• Creates versioned_docs/version-1.0/ with a snapshot of current docs
• Creates versioned_sidebars/version-1.0-sidebars.json
• Updates versions.json with the version list

Step 2: Verify versions.json

[
  "1.0",
  "current]
]

Versions appear in the dropdown in this order. "current" refers to the docs/ directory (unversioned).

Step 3: Add version labels

// docusaurus.config.js
presets: [
  [
    '"@docusaurus"/preset-classic',
    {
      docs: {
        lastVersion: 'current',
        versions: {
          current: {
            label: '1.1 (latest)',
            path: '1.1',
          },
          '1.0': {
            label: '1.0',
            path: '1.0',
          },
        },
      },
    },
  ],
];

Step 4: Handle versioned sidebar differences

If the sidebar structure changed between versions:

// versioned_sidebars/version-1.0-sidebars.json
{
  "docs": [
    "intro",
    "getting-started]
  ]
}

This must match the sidebar structure that existed when the version was created.

Version dropdown shows "1.1 (latest)" and "1.0" — both render correct docs, no 404s.

Prevention

• Create a version snapshot before making breaking changes to the documentation structure.
• Keep versions.json trimmed — older than 3 versions back, archive to a separate site.
• The version branching concept mirrors DodaZIP's archive versioning — each release is a snapshot that can be independently accessed.

Common Mistakes with versioned docs

1. Mixing let bindings with <- bindings in do notation, producing type errors
2. Overlapping type class instances that cause GHC to reject the program with ambiguous dispatch errors
3. Non-exhaustive pattern matches that compile with warnings then crash at runtime

These mistakes appear frequently in real-world DOCUSAURUS code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ