Top level site structure

[dummdidumm]

We gotta decide a bit on how to structure the site at the top level, also taking into account landing pages. I'd like to keep the landing pages for both Svelte and Kit. They both give a nice overview of the things and help you get a grasp of this if you have no idea what Svelte(Kit) is yet.

I like what the Turbo docs do: They have a brief entry-landing page with links to landing pages of Turborepo and Turbopack: https://turbo.build/

Considering that, we would have

• svelte.dev -> entry
• svelte.dev/svelte -> Svelte landing page
• svelte.dev/svelte/docs -> Svelte docs
• svelte.dev/kit -> SvelteKit landing page
• svelte.dev/kit/docs -> SvelteKit docs
• (same for everything else we bring into this site eventually)
• svelte.dev/tutorial -> what's currently on learn.svelte.dev
• svelte.dev/blog -> blog

Rough sketch:

[Rich-Harris]

Not sure about changing the top-level nav. As well as being a bit confusing, it'd be a nightmare to keep it looking sensible across different screen sizes, especially once we add other languages (i.e. we'd forget to check that the nav looks sensible on the Hungarian version of svelte.dev/vite-plugin-svelte or whatever).

Do we expect to have package-specific pages other than docs? If not then I might propose reversing things (i.e. /docs/svelte rather than /svelte/docs). Otherwise we'll end up having to create landing pages for prettier-plugin-eslint and whatever. Maybe that's fine? Not sure. From a code organisation perspective /docs/<package> feels more sustainable. And actually now that I think about it maybe /docs/svelte or /docs/kit is the landing page, but /docs/vite-plugin-svelte or whatever redirects to the actual docs?

Maybe /learn rather than /tutorial?

For docs, do we want to keep the existing /docs/[slug] or do we want /docs/[section]/[slug]? Turbo does the latter, and maybe it's a more scalable approach.

[dummdidumm]

If we don't have something in the nav bar, how do we go about switching between top levels then? To be clear my proposal is to have less things on the right but one new thing on the left.

The appeal of svelte/docs over docs/svelte is more flexibility with regards to pages within that top level. Current eslint-plugin-svelte has some kind of playground, and having that under eslint/playground makes more sense compared to other approaches. So yes, I expect top level entries to have different pages eventually.
If we don't have a landing page for certain top level entries they can just redirect to the docs.
Splitting docs into [section]/[slug] makes sense to me.

[Rich-Harris]

I think what I'd advocate for is a double-decker nav for the sections that need it:

(Note that there's no SVELTE.DEV in the top-left because we no longer need to distinguish different *.svelte.dev sites — that space can be used for a drop-down package switcher menu)

[Rich-Harris]

Minor detail but is it weird to have svelte.dev/svelte and pages under it? Maybe svelte.dev/docs should be conceptually equivalent to svelte.dev/svelte/docs

[dummdidumm]

https://turbo.build/ has a overview landing page pointing to more in-depth landing pages. Assuming we want that, too, then we need svelte.dev/svelte. If you want to quickly change the docs through the URL it's also easier to do if they all follow the same pattern. It does look a bit weird though, I give you that.

Regarding secondary nav: if we want landing pages, where would those be available from the navigation then? Does a landing page mean you always have that second nav (Home | Docs)?
Or does the first page of the docs become the landing page? Big drawback is that the side bar makes things less appealing.

[Rich-Harris]

I think the package name itself could link to the landing page — it's probably enough that the docs would be clearly signposted from there, without any need for a secondary nav

[Rich-Harris]

One consequence of /<package>/docs rather than /docs/<package> is that we're going to have to choose between this, where we define the docs page once but have a weird split (pages like /eslint/docs aren't defined inside the eslint directory, and selecting the right layout for things like double-decker nav could be a heck of a challenge)...

[package]
  docs
    [section]
      [slug]
        +page
    content
eslint
  playground
    +page
kit
  +page
svelte
  +page

...and this, where the doc pages are duplicated:

eslint
  docs
    [section]
      [slug]
        +page
  playground
    +page
kit
  docs
    [section]
      [slug]
        +page
  +page
svelte
  docs
    [section]
      [slug]
        +page
  +page

Even if the +page.server.js and +page.svelte files are very simple, that's going to get old real fast.

How about this alternative: we have landing pages like /kit and one-offs like /eslint/playground and whatever, but /docs is its own top-level page with /docs/svelte and /docs/kit etc? I think this makes more sense.

[dummdidumm]

This also depends a bit on whether or not we think that docs will actually look exactly the same between all packages. Code duplication doesn't worry me because we can put it in lib or sth and just import the component/load function in each file. Whether or not it makes sense from a "looking at the URL" perspective is not that big of a deal for me - there are pros and cons for each variant and I don't see a clear winner.

We could also turn it around and make Documentation a real top level entry, from which you can navigate to the different packages you're interested in, similar to how https://vercel.com/docs or https://docs.solidjs.com/ do it. That means we only have a single landing page though (we could have mini-landing pages in the docs). That would also resolve the "docs/<package> or <package>/docs"-question. It would restrict us with regards to the things we can put into each package though - we would have to put everything under <package>/docs because there's no other top level entry to point towards other things. For example the eslint playground would move into the docs sidebar. That also means we would have to have more specific docs +page files per package (or how else am I supposed to describe that docs/eslint/playground does show a playground?).

Another thought: How do we do versioning? Ideally we'd have something like vX.svelte.dev which shows the page at the point in time when package X was at version Y - but how do we do that when we now have multiple packages under one? For secondary packages like eslint etc it doesn't really matter IMO, but for Svelte and Kit it does.

[dummdidumm]

Idea we could use for switching top docs more easily: Have a select menu at the top of the left side bar

[Rich-Harris]

I think the current structure is working pretty well, so I'll close this