Explainer

Versioning

Explainer supports maintaining multiple documentation versions for each project. Each version is a directory inside the project folder.

Version directories

my-api/
├── _meta.json
├── default/           # "latest" (no version in URL)
│   └── en/
│       └── getting-started.mdx
├── v1/                # Version 1
│   └── en/
│       └── getting-started.mdx
└── v2/                # Version 2
    └── en/
        └── getting-started.mdx

The default version

The default directory is special:

  • It represents the latest (unversioned) documentation
  • The version name is omitted from the URL: /en/my-api/getting-started
  • It appears as “latest” in the version switcher

Named versions include the version in the URL: /en/my-api/v2/getting-started.

Adding a version

Create the version directory 

mkdir -p apps/docs/src/content/docs/my-api/v2/en

Add content

Copy or create new MDX files inside the version directory. Each version is completely independent — you can have different pages, structure, and content.

cp -r apps/docs/src/content/docs/my-api/default/en/* apps/docs/src/content/docs/my-api/v2/en/

Verify

The version switcher automatically appears in the navigation when multiple versions exist for a project. Navigate to your project and use the dropdown to switch between versions.

URL patterns

VersionURL
default/en/my-api/getting-started
v1/en/my-api/v1/getting-started
v2/en/my-api/v2/getting-started

Each version has its own independent sidebar navigation. Pages, ordering, and structure can differ across versions.