How do I add multiple API versions to the same docs site?

A common way to add multiple API versions to the same docs site is to treat each version as its own generated doc set, then route users between them with a version selector.

Here’s the usual pattern:

1) Generate docs per version

Build separate outputs for each API version, for example:

• /docs/v1/
• /docs/v2/
• /docs/v3/

Each version can have:

• its own OpenAPI spec
• its own sidebar/nav
• its own generated pages

2) Add a version switcher

In the site header or sidebar, add a dropdown/list like:

• v1.0
• v1.1
• v2.0 (current)

When the user selects a version, link them to the corresponding docs root.

3) Share common content where possible

If you have reusable content like:

• authentication guide
• error handling
• rate limits

keep it shared, and version only the API reference pages that differ.

4) Keep URLs stable

Make sure old version URLs remain accessible, e.g.:

• docs.example.com/v1/reference/users
• docs.example.com/v2/reference/users

This avoids breaking links for users on older integrations.

5) Mark the latest version clearly

Label the default as:

• Latest
• Stable
• Current

And optionally show a banner on older versions like:

You’re viewing v1. For the latest docs, go to v2.

---

If you’re using a specific docs platform

The exact setup depends on the tool:

• Docusaurus: use versioned docs (docsVersioning)
• MkDocs: use separate builds or plugins
• ReadMe / Stoplight / Redocly: usually support multiple API versions or separate specs
• Custom site: mount each version under a different path and add a selector

---

Recommended structure

A simple, maintainable setup looks like:

/docs
  /v1
  /v2
  /v3

Or, for a static docs site:

/site
  /versions
    /1.0
    /1.1
    /2.0

---

If you want, I can show you how to do this in a specific tool like Docusaurus, Redocly, MkDocs, or ReadMe.