Comparing Docusaurus and Starlight and why we made the switch

> how often do you really want to explore the docs in a specific version?

All the time. It's inevitable. If you ever sell software in the tools / configuration / package management space to "the enterprise" (which I think you do) then some of your biggest customers are going to be stuck on old versions. They'll need to easily select the version they're running if only to figure out how to upgrade to the version you want them to be running.

Edit: To clarify and drive the point home, in a previous life I was at a startup that sold something like Glasskube to enterprises. Version 3 of our software was significantly more performant and had some desirable features compared to version 2. Many of our largest paying customers literally called us up and asked us for help upgrading them. In that situation it was invaluable for our own CEO and pro services team to pull up version 2 docs side-by-side with version 3 docs, pull up a copy of the customer's code, then plan the migration for them step by step. This resulted in both revenue from the professional services and revenue from the license expansion as the customer scaled out on version 3.

So, versioned docs aren't just for customers, they're also for you, your developers (who may need to patch an old version or develop a migration tool), and your service delivery team.

> but how often do you really want to explore the docs in a specific version?

Absolutely any time I'm not using the latest version?

The versioned docs for both MUI and Tanstack Query have been very helpful in recent projects I’m working on. Obviously versioned docs are only valuable against major / breaking changes. Changelog is sufficient for non-breaking stuff.

I also really like sites that have site wide settings for code examples in different available languages, package managers, etc. I know this must be a maintenance burden on the teams of those projects but boy do I appreciate it as an implementer.

Are you serious? In the real world, people dont update software as soon as a new version comes out. Sometimes I am still using an age old version of an app or a framework because the client doesnt want to pay to upgrade, there are dependencies, or whatever…

Having easily accessible documentation for the older versions is a must, for anything that is remotely “serious”.

Just check the Laravel docs for example, or Vue, etc…

It's wild that you are offering your views on software documentation while you think checking git blame is a substitute for retaining documentation, and you don't understand why users would want documentation for old versions.

You're correct. Versioned docs = major maintenance headache. What if you want to add some new content that is applicable to all versions?

Docs are notorious already for not being updated. Adding "versioned docs" exponentially increases the complexity, and makes updating them and reading them far harder. It's a lose/lose, for the writer and the reader.

I want versioned docs literally always. I am basically never on the _most_ recent version of a software package, so being able to pick the version of the docs that matches my actual version is genuinely not negotiable.

I never want to "pinpoint changes", I want to avoid documentation totally irrelevant for the version I actually use. Here's a real world example:

Redis.io doesn't let you look up docs for any version but the latest version. The URL for docs has "latest" in the path, but swapping that for a version number just 404s. Let's look at the EXPIRE redis command and how it interacts with HSET, in the context of using Redis to cache some data with a TTL. https://redis.io/docs/latest/commands/expire/

HSET means setting a field of a hash (object/dictionary/map) to a value. EXPIRE means setting the expiration (TTL, time before autodelete) of a particular thing in redis. You can set the expiration for an entire hash in redis, but not for individual fields of that hash. HSET is like an upsert by default; it creates the hash in redis and then populates the given field with the value you set. In your application, it's pretty reasonable to want to have an operation which is like an HSET as an upsert which also sets a maximum expiration time on the parent hash, but only if there's not an expiration time set. Looking at the docs for EXPIRE, you might note that there's a special option you can set which does this exact thing, the NX flag. Thus you can implement a simple "sharded-by-hash upsert with a maximum TTL" by doing an HSET followed by an EXPIRE NX. Great!

Except that is not true! You cannot do that! Read all the paragraphs you want, you won't find this critical note unless you scroll aaaaaalll the way to the bottom of the page, past the "Differences in Redis X.Y.Z", past the Appendix, to the very last little section called "History", which isn't about the history of this page, but is instead a single bullet point of critical information noting the following:

    Starting with Redis version 7.0.0: Added options: NX, XX, GT and LT.

In such a case as this, I desperately wish that I could have clicked a little dropdown and chosen docs for Redis 6 instead of Redis 7, because this caused a serious problem as hashes just weren't expiring at all. It was especially bad because the Redis clients would send those command options to the server and the server would silently drop them, so everything looked completely fine except that the hash keys were being perpetually moved forward and never expiring!

Please version your docs!

> the people who maintain starlight have some level of billions less at their disposal to keep the project going. If Astro and the company behind it go belly up now you have a new problem on your hands

Starlight and Docusaurus aren't much different in this aspect. Meta could decide to stop paying slorber (the main maintainer of Docusaurus) at any time. I hear from friends in Meta that Docusaurus isn't even widely used internally.

Both projects are MIT-licensed, at least, and that's a plus for continuity if someone ever wants to fork them.

There is no real reason you can't have a monorepo, with one project being the Astro site and the other Starlight docs.