Let’s say in our project we’re working on a new major version. This may come with new features or even breaking changes. Users that did not upgrade yet reading documentation for the new version might get confused. This is why we want to serve a separate version of the documentation along with each major version of our project.
A Temporary Solution
Using Starlight and Vercel, this quick guide shows how I did it in my own
project: serve a separate version of the documentation at its own path. We’re
assuming the documentation is deployed from the
main branch (still at v1) and
we’re working in the
v2 branch to prepare the next major release. We’re going
to deploy this version branch and make it accessible at the
/v2 path of a
domain we already own.
This solution requires a separate Vercel project for each major version.
Hopefully the Starlight team will deliver a built-in solution, but until then this approach might work for you if you need it.
This guide assumes we have our site (
example.org) running, and want to add the
next version at
We start by setting up a new versioned project, make sure it works, and then integrate the main project with it. It’s a short story in three parts:
outDiroptions for Starlight in the versioned branch.
- Create a new project in Vercel and deploy this versioned branch.
rewritesfor Vercel in the
Configure the versioned branch
Create or switch to the version branch,
v2 in our example.
In your Astro configuration, set both the
base and the
outDir to match the
version in the current branch:
This example has trailing slashes removed, which makes sense with Vercel’s
cleanUrls option we’ll set later on. The example site is using the default
Now is the time to verify a local
astro dev serves the site at the
properly and links are working fine. Push your version branch to your Git
remote. Make sure not to merge these changes to the
Create a new project in Vercel
Create a new project in the Vercel control panel and connect it with your Git repository. It makes sense to name the project after the version, something like “example-org-v2”.
Go to Settings → Git → Production Branch to set the version branch:
In the screenshots we see “v4”, because I was at v3 in the
No need to buy or connect a new domain, versioned docs can be served from a free
Vercel subdomain such as
example-org-v2.vercel.app. No worries: users won’t
see this, they will only see the main domain you’ve already set up.
Go to Settings → Domains, edit and double-check it does not have redirects
configured and that the Git branch is
Verify the site is deployed and working at the Vercel domain and version path
(our example would run at
Need to trigger a deployment? Go to
Settings → Git → Deploy Hooks:
You can copy the link and use
curl in a shell to trigger a deployment:
Once your versioned site is running smoothly we’re ready for the final step!
Configure rewrites for Vercel
Switch to the
main branch and create a
vercel.json file in the same folder
astro.config.mjs (if it isn’t already there). Add two items to the
rewrites array as follows:
Modify the domain and the paths to match your situation. In this example,
is still the default version. You can basically swap them around once
the new default in the main branch. You’ll want to omit the
cleanUrls if you
prefer trailing slashes.
Push this in the
main branch to the remote and wait for the deployment to
finish. Verify everything works as expected:
We’ve completed all steps and this process can be repeated for new versions in the future.
What’s left to do is to show the user the current version of the documentation and a way to navigate to a different version. There’s multiple ways to do this, so this is left as an exercise to the reader.
Feel free to check out my basic solution using a dropdown in a custom
Header.astro component with minimal configuration to keep track of
available versions. The repo contains the
configuration files in the
main branch too. This solution is currently running
Good luck and have a great day!