Support for Versioned Docs about starlight HOT 13 CLOSED

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.

from starlight.

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.

from starlight.

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

from starlight.

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

from starlight.

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!

from starlight.

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.

from starlight.

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.

from starlight.

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 .

from starlight.

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.

from starlight.

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 :)

from starlight.

True

from starlight.

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

from starlight.

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

from starlight.