Feat: Docs version selector

[rChaoz]

POC for a documentation version switcher on the svelte.dev site - see issue #11599 for more details.

How to test

Just clone the PR, run pnpm install and npm run dev. By default, the Svelte 5 docs will load. Use the version switcher in the top-left to see the documentation for any Svelte version. Example links (need to have the dev server running to be able to open them):

• 3.0 - earliest documentation from this repo (v2 stored docs on a separate repo)
• 3.59 - latest Svelte 3 release
• 4.2 - same docs that are currently live on svelte.dev
• 5.0.0-next.1 - first ever Svelte 5 docs, before snippets or new event handlers

How it works

• Added a new script that does git checkout --work-tree=<some-path> <some-revision> -- documentation. This command checks out the documentation folder from a specific branch. Each version is checked out into its own directory.
• Some configuration files are used to decide which versions to be loaded (one per major version). You can find them in scripts/previous-docs/v[123]/config.json. Most importantly, they specify a regex for matching git tags.
• A new optional slug parameter has been added - the route for docs is now /docs/[[version]]/[slug]. If version is not specified, it loads the docs normally. Otherwise, it loads the docs for the specified version. Currently only v4 is added to versions.js, which contains the docs from the svelte-4 branch, so going to /docs/v4 will display the docs from the svelte-4 branch (what's currently live on svelte.dev)

What it does

In its current shape, it loads the documentation for the latest patch version of every minor release for Svelte 3, 4, and every next version for Svelte 5. Each version is then accessed using the path /docs/v-<version>/<page>. <page is the usual page slug, such as introduction or svelte-components. <version> is the version you want to use, such as 3.0, 4.2 or 5.0.0-next.100.

Why

DX-wise, the goal is to allow easy maintenance of multiple versions without having to worry about bringing documentation to the main branch. For the users, this means being able to access the documentation for your exact version, so you don't have to stumble across features that aren't available for you.

Svelte 5 rewrite

Please note that the Svelte codebase is currently being rewritten for Svelte 5. Changes should target Svelte 5, which lives on the default branch (main).

If your PR concerns Svelte 4 (including updates to svelte.dev.docs), please ensure the base branch is svelte-4 and not main.

Before submitting the PR, please make sure you do the following

• It's really useful if your PR references an issue where it is discussed ahead of time. In many cases, features are absent for a reason. For large changes, please create an RFC: https://github.com/sveltejs/rfcs
• Prefix your PR title with feat:, fix:, chore:, or docs:.
• This message body should clearly illustrate what problems it solves.
• Ideally, include a test that fails without this PR but passes with it.

Tests and linting

• Run the tests with pnpm test and lint the project with pnpm lint

[changeset-bot]

⚠️ No Changeset found

Latest commit: 9904495

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[dummdidumm]

Thanks for the POC, appriciate the effort! This assumes that the pages stay the same though. We're not really sure that will be the case. We might instead want to freeze the v4 docs in time and deploy them at v4.svelte.dev, and put most of the docs in a legacy section on the new site. Nothing set in stone yet, so it's best to hold off from further exploration for now.

[rChaoz]

@dummdidumm I'm not exactly sure what you mean. Do you mind checking out the PR and running with the new changes I made? I think that will explain things better.

This assumes that the pages stay the same though.

It really doesn't (or I misunderstood what you meant), they don't have to stay the same. The idea is that a version switcher would allow anything as the new docs, possibly even a new structure/interface, while keeping the old docs intact and accessible.

We might instead want to freeze the v4 docs in time and deploy them at v4.svelte.dev

My version switcher does exactly that, but provides them on the same site at /docs/v4