feat: docs versioning

[dummdidumm]

build upon #69 which should be merged first

WIP of having versioned docs. The idea is that we're doing Git clones of the target repositories into our gitignored folder, then copying over the docs / generating the types as needed. A version selector at the top of the side nav then allows you to switch versions.

That all is straightforward, but it reveals a general problem: The structure of how we do docs has changed slightly (and may change in a distant future), and the old Svelte docs don't follow that. I see a few options:

• Adjust docs in old site to the new format. Straightforward in this case, but possibly tricky in future cases
• Add logic to work with the old format, too. A bit unfortunate because more code, but maybe more scalable depending on the changes

I went with the latter because as it turns out the only real change in this instance was meta.json -> index.md, and for the rest we could just reuse the existing "fill these placeholders" logic - which makes me think we should just go back to using that one (> TYPES etc) instead of the new one (<!-- @include ... -->). Ben also started creating PRs to the related repos so we can eventually undo that little migration function.

Another thing this revealed is that our approach to type-checking docs doesn't work for older versions. For example, some APIs have changed between Svelte 4 and Svelte 5, so the type-checks for Svelte 4 fail because it runs the type-checks against the most recent types of version 5. There's no way to make this work within the omnisite, regardless of how we approach this. The only two solutions to this are a) abort omnisite (a bit drastic) b) don't type-check older versions (a sensible solution IMO).

Other things to tackle / open questions:

• how to approach this for search? As a first solution we should probably excempt older versions from the search index. In the future we can get smarter about (like, which version have you selected influences search results). Long term we could make it so that depending on what version you chose you'll get different search results (for that version). For that the site would notice which version you have previously selected (possibly via sessionstorage, so you're back to latest when revisiting)
• is it sensible to have our latest docs on docs/svelte/v5/...? Or should we additionally have latest as an alias, or omit the version slug for latest? The former means links never die, the latter possibly means that Google etc show more recent doc versions more reliably (and in the handle hook we could detect outdated links and reroute on a best effort basis). Docosaurus uses the "latest appears without additional slug" approach.
• do we need to make sure that SEO doesn't punish us for having multiple versions of what seems like very similar content? Or is that fine?
• if versions are very similar to each other (for example Svelte 3 and 4), should we create a new version, or just make one entry for both?
• where to put versioning on mobile? how to structure the navigation?

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
omnisite	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Sep 5, 2024 1:26pm

[benmccann]

Adjust docs in old site to the new format. Tricky because that requires bumping site-kit with changes from in here, which it isn't setup to do

I actually did that already for SvelteKit. I think I'd prefer to do it that way because then it's a one-time cost vs code that sticks around that we have to continue to maintain. We can copy the changes from https://github.com/sveltejs/kit/pull/12459/files#diff-13e7d156a0c1d8acfb9f88938211da2ac45fb638821e5e9d92f4ff05a006d63a into the Svelte repo as well

[benmccann]

The idea is that we're doing Git clones of the target repositories into our gitignored folder, then copying over the docs / generating the types as needed.

I'm confused. I see lots of files being added in this PR. If they were in a gitignored folder, then we shouldn't be adding lots of new files right?

And I thought from #69 that you wanted to commit all the files in which case why rely on git for old versions of docs, but not the most current version of docs?

[dummdidumm]

I actually did that already for SvelteKit. I think I'd prefer to do it that way because then it's a one-time cost vs code that sticks around that we have to continue to maintain.

I realized that it's super simple to transfer, just run some code that replaces the meta.json files with index.md on the fly - 10 lines of code.

I'm confused. I see lots of files being added in this PR. If they were in a gitignored folder, then we shouldn't be adding lots of new files right?

I did commit all the doc files in #69, and in this PR I also committed the docs for version 1 of SvelteKit and version 4 of Svelte (notice how this PR targets the #69 PR branch).

The flow is this:

1. git clone into gitignored folder
2. copy over documentation from cloned repository
3. run the docs reference generation script on the cloned repository's types and replace placeholders from copied over documentation which reference sections from said generated reference docs
4. commit everything into folder

It's similar to #55 but instead of doing it everytime on the fly (and having no insights into what is generated) the results are committed to the repo. The advantages of this are listed in #69

[benmccann]

I realized that it's super simple to transfer, just run some code that replaces the meta.json files with index.md on the fly - 10 lines of code.

I sent sveltejs/svelte#13120 to save those 10 lines 😄

[dummdidumm]

We decided to not go with docs versioning for now, and instead have Svelte 4 content merged into Svelte 5 content. Something like "bla bla new docs ... In Svelte 4 you did ... blabla", along with a toggle to not show the Svelte 4 content / a runes mode toggle. We can also deploy the old docs on v4.svelte.dev if there's popular demand.