Broken link to unmaintained v2.10.15 docs snapshot (Netlify deploy-preview) on Upgrade Astro pages

[Yusaku01]

Description

On the Upgrade Astro pages, the "unmaintained v2.10.15 snapshot" link points to a Netlify deploy preview URL (https://deploy-preview-4405--astro-docs-2.netlify.app/...) that now shows "Site not found". This appears to be a PR preview and is no longer available.
Expected: link should point to a stable snapshot (or be updated/removed).
Steps: open any of the pages below and click the "unmaintained v2.10.15 snapshot" link.
That said, since it's unmaintained, feel free to close this if it's working as expected.

Target Pages and Where

• https://docs.astro.build/en/upgrade-astro/
• https://docs.astro.build/ja/upgrade-astro/
• https://docs.astro.build/ko/upgrade-astro/
• https://docs.astro.build/pt-br/upgrade-astro/
• https://docs.astro.build/es/upgrade-astro/
• https://docs.astro.build/fr/upgrade-astro/
• https://docs.astro.build/zh-cn/upgrade-astro/
• https://docs.astro.build/ru/upgrade-astro/

Current Behavior

As shown in the screenshot, "Site not found" is displayed.

Browser used for verification

Chrome

How I found this

While working on updating the Japanese version of upgrade-astro.mdx

My suggestions for improvement

I can think of four possible solutions:

• I'm not sure how many users are still on v2.x, but we could simply remove the following:

- [unmaintained v2.10.15 snapshot](https://deploy-preview-4405--astro-docs-2.netlify.app/en/getting-started/)

• If removal isn't an option, we should replace it with a working link. Since the broken Netlify URL is a preview version, we could swap it with a production URL if one exists.
• If there's no production URL available, we could use a web.archive.org snapshot from around August 2023:
• Closest snapshot after v2.10.15 release: https://web.archive.org/web/20230909135157/https://docs.astro.build/en/getting-started/
• Closest snapshot before v2.10.15 release: https://web.archive.org/web/20230822134745/https://docs.astro.build/en/getting-started/
• Remove the broken link and add a note explaining that the link is no longer available.

I'd appreciate it if you could take a look when you have a chance.

[sarah11918]

Thank you very much for letting us know, and for providing a helpful discussion and possible solutions, @Yusaku01 !

We discussed this on our public Discord call "Talking and Doc'ing" today, and we agree that the best quick fix here is to replace the link with the closest snapshot before v2.10.15 release: https://web.archive.org/web/20230822134745/https://docs.astro.build/en/getting-started (Thank you, it was very helpful that you already found that link for us!) Would you like to make a docs PR to update the link for v2?

We may still want to discuss further a more permanent strategy. Will we keep the web.archive links, or try to deploy v2.docs.astro.build etc.? The problem with doing so is that it may be difficult to publish from an older point of docs that rely on outdated versions of Astro and dependencies, including Node.js. We would have to explore whether that is reasonably easy to do or not, or whether it is worth the effort.

We will also face this very soon when we update to Astro 6 and will need to decide what our v5 docs link should be, so I'm open to people's ideas here for solutions. At least publishing now and just leaving the site should mean it continues to work. Going back to older versions may not even be possible without a lot of work.

[Yusaku01]

@sarah11918

Thank you for the quick check and discussion!
Got it! I’ll replace the target document’s link with the closest snapshot before the v2.10.15 release and create a PR with the update!

---

About permanent strategy.

There are basically two options I think

• Deploy all older docs somewhere (e.g., v2, v3…, etc.)
• Keep links to web.archive snapshot

First option is the most user-friendly, but I’m worried the operational/maintenance cost is simply too high. For example, React keeps very old docs (even pre-v16) deployed (I believe via Netlify), but that likely works because the ecosystem is huge and there are many contributors maintaining the tooling. Even then, older build/dependency stacks (Node.js, tooling) are hard to keep working long-term—in some environments it’s painful to even install old Node versions.

Also, for many other frameworks (Next.js, Nuxt, Svelte, Vue, Solid), my impression is they usually don’t keep links beyond the immediately previous major version.

Svelte might be another useful reference point. For compatibility/design reasons, Svelte effectively guides users to a shared docs experience for v3 and v4. If something similar is feasible for Astro, that could be another option worth considering.

For Astro specifically, I pulled npm download stats (last 7 days) and the usage seems heavily concentrated in v5.x, some v4.x, and only a small tail for v3/v2. Not perfect data, but directionally useful. v2.x was <2%:

{
  "all": 770273,
  "v2": { "count": 14166, "share": 0.018390882193715735 },
  "v3": { "count": 7222, "share": 0.009375896597699777 },
  "v4": { "count": 75407, "share": 0.09789646008622917 },
  "v5": { "count": 667761, "share": 0.8669147172495986 }
}

Given that, I think the current approach (current docs + web.archive snapshots for a few previous majors) is already quite considerate.

If I had to propose a pragmatic middle ground:

• Keep the current major docs fully maintained (obviously).
• Keep “unmaintained” links for only the past two majors:
  • Previous major: keep it deployed and easy to browse (and if it drops below, say, ~5% usage, we could switch it to a web.archive snapshot).
  • Two majors back: keep a web.archive snapshot link.

Concretely (if current is v5)

• v4: deployed “unmaintained” docs link
• v3: web.archive snapshot link

That said, it’s a trade-off: keeping older versions is always kinder to users, and that goodwill can help the ecosystem—so I get why this isn’t an easy call 😄

---

References (for comparison)

• React
• Next.js
• Svelte

[Yusaku01]

@sarah11918
Sorry for the rapid follow-up...
I created a PR to replace the link!:
#13026

I'd appreciate it if you could take a look when you have a chance😌

[sarah11918]

Thanks again for your analysis @Yusaku01 !

Just to make sure it's clearly stated for anyone in this discussion, any older docs deploys would be unmaintained. Even right now we do have v4.docs.astro.build and it's clearly labelled as outdated and unmaintained (both in the link text where it's linked to from current docs and with a banner across all pages when you visit the page). So, I would say that the maintenance of these older, friendly-URL sites is minimal. They will never be updated and we only expect them to exist in their "final form."

Given that, I think docs that are currently already deployed that way (which would be v4 only) can stay that way, as it might actually be more maintenance to go back and update them after the fact to point to the web archive! 😂 We could choose to keep only v2 and v3 around as web archive snapshots for either kindness or even historical curiosity! But going forward, we do have the option of properly preparing for the future (as we did with the v4 branch).