Any support for versioned sites and version selectors?

[mdekstrand]

Description

Many Sphinx themes, e.g. the PyData Sphinx theme and ReadTheDocs' additions to standard themes, support dropdown menus to select versions the site or documentation. (Interestingly, this is a feature that JupyterBook seems to disable, and re-adding it doesn't look very good, but I digress.)

Is there any support for such a thing in Quarto, or plans to add support? I've looked through the docs but haven't seen anything at present. I'm working on a project that eventually should be versioned so people can refer to old versions of the results.

[mcanouil]

• Version selector for websites and html books #474

(Closing as duplicate as there are other discussions and the issue above.)

[cscheid]

(Hi!) Thanks for the message, this is a pretty popular request.

tl;dr: We are unlikely to add first-class support for document versioning in the short- or medium-term future.

The longer story

(Disclosure: this is a largely personal account!)

There are a number of reasons for this decision. The most important of them is relatively personal, but one we've observed in other versioned documentation sites: multiple website versions tend to cause serious confusion on search engines. I am not sure what causes this, but I, JJ, and Charles noticed this early on in our Quarto discussions: note how even to this day, search engines will serve you an unexpected documentation website for (say) the Python standard library, etc.

To some degree, this confusion is, eventually, unavoidable. But part of why we're writing Quarto is that we believe that we can create a system of default configuration and expectations that will eventually lead to online documentation being easier to find. That means trying to avoid common pitfalls, and we believe that in the current environment, creating a well-integrated version selector, on average, causes more harm than good.

This decision also reflects Quarto's position of being extremely conservative with breaking backwards compatibility. In these scenarios, documentation versioning is admittedly felt less acutely. I (and this is a personal opinion!) happen to think that being strict about maintaining backwards compatibility is a sign of respect from the software author to the software users. I think the current open-source culture is largely mistaken about this. I would prefer for Quarto to not eventually become a tool that makes it easy for developers to do wrong by their users.

Facilitating software breakage by gating releases behind a version bump and a fork of the entire documentation --- in my personal opinion again! --- appears to be one way in which developers do wrong by their users, and I don't want Quarto to repeat these mistakes.

[mcanouil]

Note that it's possible to do this manually, it would consist more a less to render in different sub-directories and to link them in the navigation bar.

[mdekstrand]

Thanks for your thoughts and context here. I definitely see your point (even as I'm in the middle of a set of significant breaking changes to another project I maintain, but setting that aside for the moment…).

My specific use case I'm thinking of is somewhat different, but totally understand if it isn't a priority to support (and I may just code something up with custom JS that injects versions into the navigation bar for this use case, if it looks sufficiently useful as things develop): I've got a couple of projects that are data or experiment releases rather than code releases. These projects are also evolving, incorporating new or updated data sets (thereby changing the statistics and plots), or new models or model implementations (again, adding results, or possibly changing performance metrics as model code is improved). However, if people are relying on these data sets, it seems useful for readers to be able to see what the statistics, descriptions, and performance metrics were for the specific version of the data set used, so they can properly contextualize the paper's results.

I can see a some alternatives, like depositing either an archive of the rendered site HTML or a rendered PDF with Zenodo for each tagged version. That may be a better solution than versioned sites, although being able to directly browse the different versions through the web seems easier to access.

But my particular use case here is probably not sufficient reason to deviate from the project's vision :); I just thought it might be helpful to document, either for you all or for others coming by (who might also want one of the alternatives above).

If you want examples of the kinds of things I'm building like this, you can see:

• Book Data Tools, several versions published and a new one in progress.
• LensKit Codex, in early buildout stages. This one will have the interesting property that it will be providing standardized hyperparameter tuning results, but as it evolves we may discover and employ more effective tuning strategies, or update the experiments to incorporate evolving best practices from the community, so these common results may change from version to version. I would like authors to be able to say "We used baseline tunings from the LensKit Codex version 2025.3", and readers to be able to easily resolve what those are (and see if they have changed, if they're reading the paper 3 years later).