[reorg] New sidebar!

[sarah11918]

Description (required)

This PR attempts to tame our wild sidebar!

This is a WIP and feedback is welcome! The goals of this PR:

• a more helpful organization of the sidebar nav. As it has grown and we have added more and more features, it has become more difficult to use the sidebar to quickly find what you need.
• a nicer "new user journey" for those entering the docs for the first time.

Non-goals of this PR right now (although they could be future goals!)

• Significant content updates. We generally are not making individual pages better, just the sidebar.
• Reintroducing our old Learn/Reference split from before Starlight.

Notable strategies I have taken with this PR: Changing from headings emphasizing content type to headings describing topics included.

• "Guides" is maybe no longer as helpful as it once was now that we have so many of them, and it's one big pile of them.
• We had started to separate some things out to draw more attention to them as key features, but this only made more sections that were "categories" (e.g. Built in Features) that didn't give any indication as to what would be included.
• These new headings attempt to categorize a bunch of our pages by topics, so that even if collapsed (but we won't!), you would still have helpful ideas of where the page you wanted exists
• Note that it is still worth keeping some original headings because the type of page itself is helpful for readers wanting that kind of information:
  • Basics/Concepts: things you probably should know/understand before you try to go too far. (It's helpful for readers to get that idea)
  • Reference: the pages where you'll want to look up stuff without much fluff. (It's helpful for readers to know where the most technical details are for quickly checking things)

Rethinking the "new user journey".

• Our current "install, run, good luck!" page is short, which admittedly looks not scary, but not as helpful as it could be.
• We often find that some things from the tutorial, which are more intro-friendly and hand-holding, are things we point new users to, but pointing them somewhere mid-way through a tutorial doesn't make much sense
• We want to set new users up for success, so even though I've made the "install" page longer, I think the extra content gives new users a sense of support, and where to go.
• Specifically, our advice on starting from a new theme/template has always been a sub-par experience because it comes AFTER starting a new project... at which point it's too late to "add a theme".

Eliminating some things from the sidebar nav entirely

• Everything that has been removed is still discoverable, perhaps from a page with more context. (And, CTRL+F works!)
• Fewer items in the sidebar lets us control the reader journey more to higher level intro spots, and the pages themselves do the work of linking to more details.
• Specifically, the section on configuring Astro has been removed from the sidebar (where it was unceremoniously located near the bottom anyway) and is now highlighted right on the "Install and Setup" page as "Next Steps" with fancy cards. This should ensure that things like setting up the editor, configuring TypeScript and import aliases, which are often "early and once" actions, are visible and promoted when someone is starting a new project!

FINAL THOUGHTS

This is very much a work in progress, and feedback/thoughts are WELCOME! I may have not yet thought of things, or some things may yet be only in my head! This is only a starting point!

[vercel[bot]]

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

Name	Status	Preview	Comments	Updated (UTC)
docs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jun 14, 2024 3:55pm

1 Ignored Deployment

Name	Status	Preview	Comments	Updated (UTC)
docs-i18n	⬜️ Ignored (Inspect)			Jun 14, 2024 3:55pm

[astrobot-houston]

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

Locale	File	Note
ar	basics/project-structure.mdx	Localization changed, will be marked as complete.
ar	getting-started.mdx	Localization changed, will be marked as complete. 🔄️
de	basics/project-structure.mdx	Localization changed, will be marked as complete.
de	getting-started.mdx	Localization changed, will be marked as complete. 🔄️
de	guides/deploy/cloudflare.mdx	Localization changed, will be marked as complete. 🔄️
de	guides/deploy/render.mdx	Localization changed, will be marked as complete. 🔄️
de	guides/imports.mdx	Localization changed, will be marked as complete.
de	guides/typescript.mdx	Localization changed, will be marked as complete.
de	tutorial/0-introduction/1.mdx	Localization changed, will be marked as complete.
en	basics/project-structure.mdx	Source changed, localizations will be marked as outdated.
en	community-resources/content.mdx	Source changed, localizations will be marked as outdated.
en	getting-started.mdx	Source changed, localizations will be marked as outdated.
en	guides/aliases.mdx	Source removed, will stop being tracked.
en	guides/cms/apostrophecms.mdx	Source changed, localizations will be marked as outdated.
en	guides/cms/buttercms.mdx	Source changed, localizations will be marked as outdated.
en	guides/cms/contentful.mdx	Source changed, localizations will be marked as outdated.
en	guides/cms/cosmic.mdx	Source changed, localizations will be marked as outdated.
en	guides/cms/datocms.mdx	Source changed, localizations will be marked as outdated.
en	guides/cms/ghost.mdx	Source changed, localizations will be marked as outdated.
en	guides/cms/hashnode.mdx	Source changed, localizations will be marked as outdated.
en	guides/cms/payload.mdx	Source changed, localizations will be marked as outdated.
en	guides/cms/statamic.mdx	Source changed, localizations will be marked as outdated.
en	guides/cms/storyblok.mdx	Source changed, localizations will be marked as outdated.
en	guides/cms/strapi.mdx	Source changed, localizations will be marked as outdated.
en	guides/cms/umbraco.mdx	Source changed, localizations will be marked as outdated.
en	guides/cms/wordpress.mdx	Source changed, localizations will be marked as outdated.
en	guides/content.mdx	Source changed, localizations will be marked as outdated.
en	guides/deploy/render.mdx	Source changed, localizations will be marked as outdated.
en	guides/images.mdx	Source changed, localizations will be marked as outdated.
en	guides/imports.mdx	Source changed, localizations will be marked as outdated.
en	guides/markdown-content.mdx	Source changed, localizations will be marked as outdated.
en	guides/migrate-to-astro/from-docusaurus.mdx	Source changed, localizations will be marked as outdated.
en	guides/migrate-to-astro/from-eleventy.mdx	Source changed, localizations will be marked as outdated.
en	guides/migrate-to-astro/from-gatsby.mdx	Source changed, localizations will be marked as outdated.
en	guides/migrate-to-astro/from-gitbook.mdx	Source changed, localizations will be marked as outdated.
en	guides/migrate-to-astro/from-gridsome.mdx	Source changed, localizations will be marked as outdated.
en	guides/migrate-to-astro/from-hugo.mdx	Source changed, localizations will be marked as outdated.
en	guides/migrate-to-astro/from-jekyll.mdx	Source changed, localizations will be marked as outdated.
en	guides/migrate-to-astro/from-nextjs.mdx	Source changed, localizations will be marked as outdated.
en	guides/migrate-to-astro/from-nuxtjs.mdx	Source changed, localizations will be marked as outdated.
en	guides/migrate-to-astro/from-pelican.mdx	Source changed, localizations will be marked as outdated.
en	guides/migrate-to-astro/from-sveltekit.mdx	Source changed, localizations will be marked as outdated.
en	guides/migrate-to-astro/from-vuepress.mdx	Source changed, localizations will be marked as outdated.
en	guides/migrate-to-astro/from-wordpress.mdx	Source changed, localizations will be marked as outdated.
en	guides/rss.mdx	Source changed, localizations will be marked as outdated.
en	guides/typescript.mdx	Source changed, localizations will be marked as outdated.
en	install/auto.mdx	Source removed, will stop being tracked.
en	install/manual.mdx	Source removed, will stop being tracked.
en	recipes.mdx	Source changed, localizations will be marked as outdated.
en	recipes/bun.mdx	Source changed, localizations will be marked as outdated.
en	reference/cli-reference.mdx	Source changed, localizations will be marked as outdated.
en	tutorial/0-introduction/1.mdx	Source changed, localizations will be marked as outdated.
es	basics/project-structure.mdx	Localization changed, will be marked as complete.
es	getting-started.mdx	Localization changed, will be marked as complete. 🔄️
es	guides/cms/apostrophecms.mdx	Localization changed, will be marked as complete. 🔄️
es	guides/cms/buttercms.mdx	Localization changed, will be marked as complete.
es	guides/cms/contentful.mdx	Localization changed, will be marked as complete.
es	guides/cms/cosmic.mdx	Localization changed, will be marked as complete.
es	guides/cms/datocms.mdx	Localization changed, will be marked as complete.
es	guides/cms/ghost.mdx	Localization changed, will be marked as complete.
es	guides/cms/payload.mdx	Localization changed, will be marked as complete.
es	guides/cms/statamic.mdx	Localization changed, will be marked as complete.
es	guides/cms/storyblok.mdx	Localization changed, will be marked as complete.
es	guides/cms/strapi.mdx	Localization changed, will be marked as complete.
es	guides/cms/wordpress.mdx	Localization changed, will be marked as complete.
es	guides/deploy/render.mdx	Localization changed, will be marked as complete. 🔄️
es	guides/images.mdx	Localization changed, will be marked as complete.
es	guides/imports.mdx	Localization changed, will be marked as complete.
es	guides/markdown-content.mdx	Localization changed, will be marked as complete. 🔄️
es	guides/migrate-to-astro/from-docusaurus.mdx	Localization changed, will be marked as complete.
es	guides/migrate-to-astro/from-eleventy.mdx	Localization changed, will be marked as complete.
es	guides/migrate-to-astro/from-gatsby.mdx	Localization changed, will be marked as complete.
es	guides/migrate-to-astro/from-gitbook.mdx	Localization changed, will be marked as complete.
es	guides/migrate-to-astro/from-gridsome.mdx	Localization changed, will be marked as complete.
es	guides/migrate-to-astro/from-hugo.mdx	Localization changed, will be marked as complete.
es	guides/migrate-to-astro/from-jekyll.mdx	Localization changed, will be marked as complete.
es	guides/migrate-to-astro/from-nextjs.mdx	Localization changed, will be marked as complete.
es	guides/migrate-to-astro/from-nuxtjs.mdx	Localization changed, will be marked as complete.
es	guides/migrate-to-astro/from-pelican.mdx	Localization changed, will be marked as complete.
es	guides/migrate-to-astro/from-sveltekit.mdx	Localization changed, will be marked as complete.
es	guides/migrate-to-astro/from-vuepress.mdx	Localization changed, will be marked as complete.
es	guides/migrate-to-astro/from-wordpress.mdx	Localization changed, will be marked as complete.
es	guides/typescript.mdx	Localization changed, will be marked as complete.
es	install-and-setup.mdx	Localization changed, will be marked as complete. 🔄️
es	recipes/bun.mdx	Localization changed, will be marked as complete.
es	reference/cli-reference.mdx	Localization changed, will be marked as complete. 🔄️
es	tutorial/0-introduction/1.mdx	Localization changed, will be marked as complete.
fr	basics/project-structure.mdx	Localization changed, will be marked as complete.
fr	guides/cms/apostrophecms.mdx	Localization changed, will be marked as complete. 🔄️
fr	guides/cms/buttercms.mdx	Localization changed, will be marked as complete.
fr	guides/cms/contentful.mdx	Localization changed, will be marked as complete.
fr	guides/cms/cosmic.mdx	Localization changed, will be marked as complete.
fr	guides/cms/datocms.mdx	Localization changed, will be marked as complete.
fr	guides/cms/ghost.mdx	Localization changed, will be marked as complete.
fr	guides/cms/payload.mdx	Localization changed, will be marked as complete.
fr	guides/cms/statamic.mdx	Localization changed, will be marked as complete.
fr	guides/cms/storyblok.mdx	Localization changed, will be marked as complete.
fr	guides/cms/strapi.mdx	Localization changed, will be marked as complete.
fr	guides/cms/wordpress.mdx	Localization changed, will be marked as complete.
fr	guides/deploy/render.mdx	Localization changed, will be marked as complete. 🔄️
fr	guides/images.mdx	Localization changed, will be marked as complete.
fr	guides/imports.mdx	Localization changed, will be marked as complete.
fr	guides/markdown-content.mdx	Localization changed, will be marked as complete. 🔄️
fr	guides/typescript.mdx	Localization changed, will be marked as complete.
fr	recipes/bun.mdx	Localization changed, will be marked as complete.
fr	reference/cli-reference.mdx	Localization changed, will be marked as complete. 🔄️
fr	tutorial/0-introduction/1.mdx	Localization changed, will be marked as complete.
hi	basics/project-structure.mdx	Localization changed, will be marked as complete.
hi	getting-started.mdx	Localization changed, will be marked as complete. 🔄️
it	basics/project-structure.mdx	Localization changed, will be marked as complete.
it	getting-started.mdx	Localization changed, will be marked as complete. 🔄️
it	recipes/bun.mdx	Localization changed, will be marked as complete.
ja	basics/project-structure.mdx	Localization changed, will be marked as complete.
ja	getting-started.mdx	Localization changed, will be marked as complete. 🔄️
ja	guides/cms/buttercms.mdx	Localization changed, will be marked as complete.
ja	guides/cms/contentful.mdx	Localization changed, will be marked as complete.
ja	guides/cms/storyblok.mdx	Localization changed, will be marked as complete.
ja	guides/deploy/render.mdx	Localization changed, will be marked as complete. 🔄️
ja	guides/images.mdx	Localization changed, will be marked as complete.
ja	guides/imports.mdx	Localization changed, will be marked as complete.
ja	guides/markdown-content.mdx	Localization changed, will be marked as complete. 🔄️
ja	guides/typescript.mdx	Localization changed, will be marked as complete.
ja	recipes/bun.mdx	Localization changed, will be marked as complete.
ja	reference/cli-reference.mdx	Localization changed, will be marked as complete. 🔄️
ja	tutorial/0-introduction/1.mdx	Localization changed, will be marked as complete.
ko	basics/project-structure.mdx	Localization changed, will be marked as complete.
ko	getting-started.mdx	Localization changed, will be marked as complete. 🔄️
ko	guides/cms/apostrophecms.mdx	Localization changed, will be marked as complete. 🔄️
ko	guides/cms/buttercms.mdx	Localization changed, will be marked as complete.
ko	guides/cms/contentful.mdx	Localization changed, will be marked as complete.
ko	guides/cms/cosmic.mdx	Localization changed, will be marked as complete.
ko	guides/cms/datocms.mdx	Localization changed, will be marked as complete.
ko	guides/cms/ghost.mdx	Localization changed, will be marked as complete.
ko	guides/cms/hashnode.mdx	Localization changed, will be marked as complete.
ko	guides/cms/payload.mdx	Localization changed, will be marked as complete.
ko	guides/cms/statamic.mdx	Localization changed, will be marked as complete.
ko	guides/cms/storyblok.mdx	Localization changed, will be marked as complete.
ko	guides/cms/strapi.mdx	Localization changed, will be marked as complete.
ko	guides/cms/umbraco.mdx	Localization changed, will be marked as complete. 🔄️
ko	guides/cms/wordpress.mdx	Localization changed, will be marked as complete.
ko	guides/deploy/render.mdx	Localization changed, will be marked as complete. 🔄️
ko	guides/images.mdx	Localization changed, will be marked as complete.
ko	guides/imports.mdx	Localization changed, will be marked as complete.
ko	guides/markdown-content.mdx	Localization changed, will be marked as complete. 🔄️
ko	guides/migrate-to-astro/from-docusaurus.mdx	Localization changed, will be marked as complete.
ko	guides/migrate-to-astro/from-eleventy.mdx	Localization changed, will be marked as complete.
ko	guides/migrate-to-astro/from-gatsby.mdx	Localization changed, will be marked as complete.
ko	guides/migrate-to-astro/from-gitbook.mdx	Localization changed, will be marked as complete.
ko	guides/migrate-to-astro/from-gridsome.mdx	Localization changed, will be marked as complete.
ko	guides/migrate-to-astro/from-hugo.mdx	Localization changed, will be marked as complete.
ko	guides/migrate-to-astro/from-jekyll.mdx	Localization changed, will be marked as complete.
ko	guides/migrate-to-astro/from-nextjs.mdx	Localization changed, will be marked as complete.
ko	guides/migrate-to-astro/from-nuxtjs.mdx	Localization changed, will be marked as complete.
ko	guides/migrate-to-astro/from-pelican.mdx	Localization changed, will be marked as complete.
ko	guides/migrate-to-astro/from-sveltekit.mdx	Localization changed, will be marked as complete.
ko	guides/migrate-to-astro/from-vuepress.mdx	Localization changed, will be marked as complete.
ko	guides/migrate-to-astro/from-wordpress.mdx	Localization changed, will be marked as complete.
ko	guides/typescript.mdx	Localization changed, will be marked as complete.
ko	install-and-setup.mdx	Localization changed, will be marked as complete. 🔄️
ko	recipes/bun.mdx	Localization changed, will be marked as complete.
ko	reference/cli-reference.mdx	Localization changed, will be marked as complete. 🔄️
ko	tutorial/0-introduction/1.mdx	Localization changed, will be marked as complete.
pl	getting-started.mdx	Localization changed, will be marked as complete. 🔄️
pt-br	basics/project-structure.mdx	Localization changed, will be marked as complete.
pt-br	getting-started.mdx	Localization changed, will be marked as complete. 🔄️
pt-br	guides/cms/wordpress.mdx	Localization changed, will be marked as complete.
pt-br	guides/deploy/render.mdx	Localization changed, will be marked as complete. 🔄️
pt-br	guides/images.mdx	Localization changed, will be marked as complete.
pt-br	guides/imports.mdx	Localization changed, will be marked as complete.
pt-br	guides/markdown-content.mdx	Localization changed, will be marked as complete. 🔄️
pt-br	guides/typescript.mdx	Localization changed, will be marked as complete.
pt-br	reference/cli-reference.mdx	Localization changed, will be marked as complete. 🔄️
pt-br	tutorial/0-introduction/1.mdx	Localization changed, will be marked as complete.
ru	basics/project-structure.mdx	Localization changed, will be marked as complete.
ru	getting-started.mdx	Localization changed, will be marked as complete. 🔄️
ru	guides/cms/buttercms.mdx	Localization changed, will be marked as complete.
ru	guides/cms/wordpress.mdx	Localization changed, will be marked as complete.
ru	guides/markdown-content.mdx	Localization changed, will be marked as complete. 🔄️
ru	guides/typescript.mdx	Localization changed, will be marked as complete.
ru	reference/cli-reference.mdx	Localization changed, will be marked as complete. 🔄️
ru	tutorial/0-introduction/1.mdx	Localization changed, will be marked as complete.
zh-cn	basics/project-structure.mdx	Localization changed, will be marked as complete.
zh-cn	getting-started.mdx	Localization changed, will be marked as complete. 🔄️
zh-cn	guides/cms/apostrophecms.mdx	Localization changed, will be marked as complete. 🔄️
zh-cn	guides/cms/buttercms.mdx	Localization changed, will be marked as complete.
zh-cn	guides/cms/contentful.mdx	Localization changed, will be marked as complete.
zh-cn	guides/cms/cosmic.mdx	Localization changed, will be marked as complete.
zh-cn	guides/cms/datocms.mdx	Localization changed, will be marked as complete.
zh-cn	guides/cms/ghost.mdx	Localization changed, will be marked as complete.
zh-cn	guides/cms/hashnode.mdx	Localization changed, will be marked as complete.
zh-cn	guides/cms/payload.mdx	Localization changed, will be marked as complete.
zh-cn	guides/cms/statamic.mdx	Localization changed, will be marked as complete.
zh-cn	guides/cms/storyblok.mdx	Localization changed, will be marked as complete.
zh-cn	guides/cms/strapi.mdx	Localization changed, will be marked as complete.
zh-cn	guides/cms/umbraco.mdx	Localization changed, will be marked as complete. 🔄️
zh-cn	guides/cms/wordpress.mdx	Localization changed, will be marked as complete.
zh-cn	guides/deploy/render.mdx	Localization changed, will be marked as complete. 🔄️
zh-cn	guides/images.mdx	Localization changed, will be marked as complete.
zh-cn	guides/imports.mdx	Localization changed, will be marked as complete.
zh-cn	guides/markdown-content.mdx	Localization changed, will be marked as complete. 🔄️
zh-cn	guides/migrate-to-astro/from-docusaurus.mdx	Localization changed, will be marked as complete.
zh-cn	guides/migrate-to-astro/from-eleventy.mdx	Localization changed, will be marked as complete.
zh-cn	guides/migrate-to-astro/from-gatsby.mdx	Localization changed, will be marked as complete.
zh-cn	guides/migrate-to-astro/from-gitbook.mdx	Localization changed, will be marked as complete.
zh-cn	guides/migrate-to-astro/from-gridsome.mdx	Localization changed, will be marked as complete.
zh-cn	guides/migrate-to-astro/from-hugo.mdx	Localization changed, will be marked as complete.
zh-cn	guides/migrate-to-astro/from-jekyll.mdx	Localization changed, will be marked as complete.
zh-cn	guides/migrate-to-astro/from-nextjs.mdx	Localization changed, will be marked as complete.
zh-cn	guides/migrate-to-astro/from-nuxtjs.mdx	Localization changed, will be marked as complete.
zh-cn	guides/migrate-to-astro/from-pelican.mdx	Localization changed, will be marked as complete.
zh-cn	guides/migrate-to-astro/from-sveltekit.mdx	Localization changed, will be marked as complete.
zh-cn	guides/migrate-to-astro/from-vuepress.mdx	Localization changed, will be marked as complete.
zh-cn	guides/migrate-to-astro/from-wordpress.mdx	Localization changed, will be marked as complete.
zh-cn	guides/typescript.mdx	Localization changed, will be marked as complete.
zh-cn	install-and-setup.mdx	Localization changed, will be marked as complete. 🔄️
zh-cn	reference/cli-reference.mdx	Localization changed, will be marked as complete. 🔄️
zh-cn	tutorial/0-introduction/1.mdx	Localization changed, will be marked as complete.
zh-tw	basics/project-structure.mdx	Localization changed, will be marked as complete.
zh-tw	getting-started.mdx	Localization changed, will be marked as complete. 🔄️
en	nav.ts	Source changed, localizations will be marked as outdated.

Warnings reference

Icon	Description
🔄️	The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

[lorenzolewis]

possibly slightly re-order the upper-level sections to be like this:

• Welcome, World!
• Core Concepts
• Learn the Basics
• Manage your Content
• Assets
• Create Routes
• Connect your Data
• Client Side Interactivity
• …the rest of the entries

I bumped up “Manage your Content” and “Assets” because I personally need to reference them more. Creating routes I only need IF I’m doing dynamic routing.

I also noticed that image and asset topics seem to pop up more in support than routing it feels like.

[sarah11918]

Thank you, @lorenzolewis - will play with this idea and see how it feels!

[sarah11918]

To self: I just moved the install/auto and install/manual files to "old translations" to let link check confirm that we caught all the links. If this passes, I'll keep them there. If not, I'll move them back! :sweat_smile:

[sarah11918]

!coauthor

[github-actions[bot]]

Co-authored-by: Houston (Bot) <[email protected]>
Co-authored-by: Lorenzo Lewis <[email protected]>
Co-authored-by: Chris Swithinbank <[email protected]>
Co-authored-by: voxel!() <[email protected]>
Co-authored-by: Reuben Tier <[email protected]>
Co-authored-by: Yan <[email protected]>
Co-authored-by: Kevin <[email protected]>

[sarah11918]

Full co-author list!

Co-authored-by: Chris Swithinbank [email protected] Co-authored-by: Yan [email protected] Co-authored-by: Reuben Tier [email protected] Co-authored-by: HiDeoo [email protected] Co-authored-by: Kevin [email protected] Co-authored-by: Luiz Ferraz [email protected] Co-authored-by: Bryce Russell [email protected] Co-authored-by: Atharva [email protected] Co-authored-by: liruifengv [email protected] Co-authored-by: Junseong Park [email protected] Co-authored-by: Thomas Bonnet [email protected] Co-authored-by: Lorenzo Lewis [email protected] Co-authored-by: Sergio A. Arevalo Soria [email protected] Co-authored-by: voxel!() [email protected] Co-authored-by: Ricardo Jaime Gil Simões <[email protected] Co-authored-by: Jasper 張 [email protected]

[yanthomasdev]

Before merging, do not forget:

@lunaria-track:src/content/docs/en/community-resources/*.mdx;src/content/docs/en/tutorial/0-introduction/1.mdx;src/i18n/en/nav.ts