astro islands or a plain svelte spa for a 40-page docs site with search Islands

Astro, and search doesn't change the maths the way you think.

A prebuilt Pagefind-style index for 150 pages is a few hundred KB total and it's chunked — the browser fetches only the shards that match what you type, typically tens of KB per query. You're not shipping the corpus. In an SPA every page's content is either in the bundle or behind a fetch you have to design.

The bigger reason: docs get read by someone who arrived from a search engine on a deep link, on bad wifi, once. Static HTML for that path is worth more than nice route transitions on the third page.

Your API table and your demos are islands. That's four client:visible components on a site that is otherwise HTML, and a typical page ends up under 30 KB of JS.

Neither having shipped Astro is a real cost but a small one — content collections and the client:* directives are basically the entire API surface for a docs site. Budget two days of confusion about when a component is server-rendered versus hydrated and you're through it.

The thing I'd actually be careful about is MDX. If your interactive demos import Svelte components into prose, get that pipeline working on day one with one page before you migrate 40. That's where the sharp edges are.

do you actually need client side search for 150 pages? a decent sidebar plus ctrl-f gets people most of the way and costs nothing

Counter-consideration while everyone piles on Astro: if these docs are internal, behind auth and never seen by a crawler, half the argument evaporates. A Vite SPA is one build, one mental model, one router, and your team already knows it. Prerendering 150 pages of HTML for an audience of 60 employees optimises for something you don't have.

Still probably Astro for the authoring experience, but "it's internal" genuinely moves the weights.

Whichever you pick, decide the search story before you build the nav. Retrofitting search into a hand-rolled docs site is the thing that eats a week. Index generated at build, one component, done on day one.