Support for Versioned Docs #957
Replies: 21 comments 3 replies
-
|
I think that there is already a thread in discord, if you wanna join us. https://discord.com/channels/830184174198718474/1117052663520034866 |
Beta Was this translation helpful? Give feedback.
-
|
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. |
Beta Was this translation helpful? Give feedback.
-
|
Another project that implements this: https://docs.antora.org/antora/latest/content-source-versioning-methods/ |
Beta Was this translation helpful? Give feedback.
-
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. |
Beta Was this translation helpful? Give feedback.
-
|
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: |
Beta Was this translation helpful? Give feedback.
-
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. |
Beta Was this translation helpful? Give feedback.
-
|
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! |
Beta Was this translation helpful? Give feedback.
-
|
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 :) |
Beta Was this translation helpful? Give feedback.
-
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. |
Beta Was this translation helpful? Give feedback.
-
|
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=v2I’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.
UPDATE: |
Beta Was this translation helpful? Give feedback.
-
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. |
Beta Was this translation helpful? Give feedback.
-
|
A fully in memory way to read files from other branch/tag could be possible with isomorphic-git and BrowserFS (by using 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 |
Beta Was this translation helpful? Give feedback.
-
|
Hi @Genteure, I'm the maintainer of BrowserFS. I'd like to let you know that BrowserFS has been deprecated. You can read more about that in the BrowserFS readme: https://github.com/jvilk/browserfs. ZenFS is an updated and active fork that I created. I've opened an issue on isomorphic-git about migrating. You should be able to use ZenFS instead of BrowserFS for the use case your talking about. |
Beta Was this translation helpful? Give feedback.
-
|
I work on two sets of docs -- one that manages versions by branch (built with Hugo), and one that manages versions by folder (built by docusaurus). There are trade-offs in either direction, but my experience is that versioning by folder is much more enjoyable to maintain...or at least, much less frustrating. The main pain points for me with versioning by branch are:
There are certainly things I/we could be doing differently, and probably better, with both sites. But in their current form, I find the versioned-by-branch site to be a much more painful site to manage. |
Beta Was this translation helpful? Give feedback.
-
|
When working with versions by folder, it seems that seems to fit ergonomically with Astro's content collections already. While I like the idea of doing it git-based, I don't love the idea of adding a Git dependency. |
Beta Was this translation helpful? Give feedback.
-
|
I would like to mention that MkDocs also has third party support for versioning using mike. This is done by using a combination of branches and GitHub Actions to deploy the branch as a seperate version. In my opinion, I like this approach as it makes the repo more organised and makes it easer to find other versions for your docs. I have both implemented and used this approach when using MkDocs and it works pretty well, you can find an example here of my GitHub Actions file and see how I used mike to create versioned docs. |
Beta Was this translation helpful? Give feedback.
-
|
Fun fact is, that I just had to deploy the docs for version 0.13 of starlight in order to be able to browse these. I have to use 0.13 since the |
Beta Was this translation helpful? Give feedback.
-
|
Fwiw I wrote up a temp, branch-based solution that works for me: https://www.webpro.nl/scraps/versioned-docs-with-starlight-and-vercel. |
Beta Was this translation helpful? Give feedback.
-
|
In your example (and in the knip) how did you get the sidebar to re-render with the write version? |
Beta Was this translation helpful? Give feedback.
-
|
I'd really love to see this happen. Can we bump this back up on the radar? I'd be happy to contribute a PR for this. |
Beta Was this translation helpful? Give feedback.
-
|
I'm planning to start a "Starlight Studio" project, and I believe this feature is essential. Over the next few weeks, I'll be working on a POC. I think the "folders + repeated files + CLI to manage" approach is much clearer than trying to "hack git" to create a structure that covers multiple, often unmapped scenarios. One important aspect I haven't mentioned yet is implementing "multiple versioning" similar to what Docusaurus does very well. I'll also consider this for the POC. |
Beta Was this translation helpful? Give feedback.
-
|
@gloredo do have a look how Antora (Asciidoc docs site generator) does "component" versions. I haven't seen anything as powerful and well designed as this one. Posting the link for inspiration: |
Beta Was this translation helpful? Give feedback.
-
|
Sharing an approach I'm starting to experiment with based on a Starlight plugin: |
Beta Was this translation helpful? Give feedback.
-
What version of
starlightare 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?
Participation
Beta Was this translation helpful? Give feedback.
All reactions