Support for Versioned Docs

[lorenzolewis]

What version of starlight are you using?

0.5.5

What is your idea?

Built-in support for versioned docs

Why is this feature necessary?

As projects mature they will usually need to support multiple versions of their docs at once. There are ways to do this using the options already available in Starlight (such as routing) but I think adding this as a fully supported use case would be amazing.

This can be tricky when building on top of i18n, but I'd recommend constructing a path similar to this https://starlight.astro.build/es/1/getting-started/ where the version comes after the locale in the slug.

This could also let Starlight build in first-party solutions such as a version dropdown similar to what is already done for locales.

This might be something that's outside of my depth to code, but I'd be more than happy to help figure out a system that works based on what I've worked with before.

Oh, and you all are awesome! <3

Do you have examples of this feature in other projects?

• Docusaurus: https://docusaurus.io/docs/versioning

Participation

• I am willing to submit a pull request for this issue.

[dreyfus92]

I think that there is already a thread in discord, if you wanna join us. https://discord.com/channels/830184174198718474/1117052663520034866

[delucis]

Thanks for the issue @lorenzolewis! Yes, absolutely something we’d like to support. This is a bigger feature and may take some time as we understand all the implications fully, but would love to use this issue to collect feedback and suggestions from anyone who has experience and ideas.

[jason-seqera]

Another project that implements this: https://docs.antora.org/antora/latest/content-source-versioning-methods/

[caesar]

Another project that implements this: https://docs.antora.org/antora/latest/content-source-versioning-methods/

I really like the approach they've gone with of using branches for the versioned docs content. That's what we've done with https://codeberg.org/forgejo/docs/, for which we'd really like to use Starlight once support for versioned docs is available.

[ematipico]

The way I would like use versioning is a bit different compared to the normal workflow.

We have documentation that is generated from the source code, this means that a PR is merged, the documentation goes straight online.

We managed to mask the problem somehow, although it would be great if we could have some kind of "promotion" process. But versioning also works: next and latest will be the versions I could use .

[azan-n]

Another project that implements this: https://docs.antora.org/antora/latest/content-source-versioning-methods/

I really like the approach they've gone with of using branches for the versioned docs content. That's what we've done with https://codeberg.org/forgejo/docs/, for which we'd really like to use Starlight once support for versioned docs is available.

ReadTheDocs also does this for multiple VCS.

I agree that branches for versioning are the best approach to take here. Folders can get tricky and start to require a lot of manual work, as is pointed out in the Docusaurus community. I think we should collaborate to chart this out and explore the many use cases and objectives so we can start, or help in building this.

[delucis]

A branch-based system would make Git a hard requirement for using Starlight which isn't the case currently, so that makes me a tiny bit hesitant. (Enabling our "last updated" feature does already rely on Git, but that's a much smaller scope than versioning.)

The Docusaurus approach certainly seems like the most simple from an implementation perspective, but I'm keen to hear the pain points there people have experienced!

[newtoallofthis123]

I mean, the easiest way I think would be to just use the docs with v1 and v2 scheme. However, that would mean significant complexity for Starlight to recognize that.

The docusaurus approach on the other hand I like very much, but I often ran into issues like git conflicts and such. This was obviously due to my mistakes, but still, worth simplifying :)

[azan-n]

The Docusaurus approach certainly seems like the most simple from an implementation perspective, but I'm keen to hear the pain points there people have experienced!

There is lots of duplication and manual effort if you have documentation for something that changes fast (something like v3.1.1 -> v3.9.0 itself would lead to a huge repo).

The effort of managing directories and JSON sidebar configurations is much harder than just creating a git tag which can easily be automated in the CI.

[newtoallofthis123]

True

[delucis]

If tracking a git tag, it becomes hard to update docs for a past version right? You essentially “freeze” docs but can’t go back and improve them. That wouldn‘t be the case with version branches, because you could continue to commit to an old version’s branch.

Even then, I’m not even sure how or if Astro could successfully synthesize versions from different branches — you’d need some process that does something like repeatedly checking out and building version branches during the build step like this:

git checkout main
npx astro build --outDir=./dist
git checkout v1
npx astro build --outDir=./dist/v1 --base=v1
git checkout v2
npx astro build --outDir=./dist/v2 --base=v2

I’d have to test but could imagine this causing issues with some CI providers too where not all branches may be cloned.

Maybe someone is up for testing this approach? I think in theory a bash script like the above may even work to some extent if suboptimal and with our new component overrides support adding some UI to the nav bar for switching versions could work.

---

N.B. the --outDir argument doesn’t actually exist currently, so this would also need wiring up using an environment variable like:

// astro.config.mjs

defineConfig({
  outDir: process.env.OUTDIR || 'dist',
})

OUTDIR=./dist/v1 npx astro build

[caesar]

I’m not even sure how or if Astro could successfully synthesize versions from different branches — you’d need some process that does something like repeatedly checking out and building version branches during the build step

On the Forgejo website we check out each branch of our docs repo as a submodule in a different directory. That way Astro can run on all the content at once.

[Genteure]

A fully in memory way to read files from other branch/tag could be possible with isomorphic-git and BrowserFS (by using InMemory, OverlayFS and/or MountableFileSystem).

In theory we can fetch and checkout another branch fully in memory. While I haven't tested this idea, I don't see a reason why it can't be achieved.

isomorphic-git have an interactive demo right in the browser: https://isomorphic-git.org/docs/en/quickstart