[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]

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	May 9, 2024 7:22pm

1 Ignored Deployment

Name	Status	Preview	Comments	Updated (UTC)
docs-i18n	⬜️ Ignored (Inspect)			May 9, 2024 7:22pm

[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
en	community-resources/content.mdx	Source changed, localizations will be marked as outdated.
en	guides/content.mdx	Source changed, localizations will be marked as outdated.
en	install/auto.mdx	Source changed, localizations will be marked as outdated.
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.

[VoxelMC]

Hello, I am back! This is truly awesome. Thank you for spearheading this.

I added some comments about wording and suggested the addition of a sentence. I also made some edits for consistency's sake for sidebar title formatting!

Hope it helps!

[VoxelMC]

Suggested change

	{ text: 'Other Develoment APIs', header: true, type: 'api', key: 'dev' },
	{ text: 'Other Astro APIs', header: true, type: 'api', key: 'dev' },

Note: Typo here if we keep it as "Development".

I think it would help to make it obvious that this is a section for developer tools.
Perhaps "Astro" APIs, is not correct, though. Maybe "Extend Astro" or "Create an Integration" could also work.

[VoxelMC]

Suggested change

	If all goes well, you should see a success message followed by some recommended next steps. `cd` into your new project directory to begin using Astro.
	If all goes well, you will see a success message followed by some recommended next steps. `cd` into your new project directory to begin using Astro.

Perhaps a more hopeful option!

[VoxelMC]

I really love the way you have laid this out. It is quite encompassing yet concise!

[VoxelMC]

Suggested change

	Astro will build a deploy-ready version of your site in a separate folder (`dist/` by default) and you can watch its progress in the terminal. This will alert you to any build errors in your project before you deploy to production.
	Astro will build a deploy-ready version of your site in a separate folder (`dist/` by default) and you can watch its progress in the terminal. This will alert you to any build errors in your project before you deploy to production. If you opted to use Typescript, the `build` script will also check your project for type errors.

Not sure of the accuracy here, but perhaps important to mention. I remember this being discussed quite a bit ago, and how it is not abundantly clear that the create command adds this to your package.json when using Typescript.

[VoxelMC]

Suggested change

	[Astro's official recipes](/en/recipes/) are short, focused how-to guides that walk a reader through completing a working example of a specific task. Recipes are a great way to add new features or behavior to your Astro project by following step-by-step instructions!
	[Astro's official recipes](/en/recipes/) are quick, focused how-to guides that walk a reader through completing a working example of a specific task. Recipes are a great way to add new features or behavior to your Astro project by following step-by-step instructions!

I think this would make it sound like the recipes are concise, rather than simple, and perhaps encourage more people to use them. I might ALSO be overthinking!

[VoxelMC]

Suggested change

	{ text: 'Create Routes', header: true, type: 'learn', key: 'routes' },
	{ text: 'Create routes', header: true, type: 'learn', key: 'routes' },

[VoxelMC]

Suggested change

	{ text: 'Learn the Basics', header: true, type: 'learn', key: 'basics' },
	{ text: 'Learn the basics', header: true, type: 'learn', key: 'basics' },

[VoxelMC]

Suggested change

	{ text: 'Core Concepts', header: true, type: 'learn', key: 'coreConcepts' },
	{ text: 'Core concepts', header: true, type: 'learn', key: 'coreConcepts' },

[VoxelMC]

Suggested change

	{ text: 'Add backend services', slug: 'guides/backend', key: 'guides/backend' },
	{ text: 'Add Backend Services', slug: 'guides/backend', key: 'guides/backend' },

[VoxelMC]

Suggested change

	{ text: 'Add an RSS feed', slug: 'guides/rss', key: 'guides/rss' },
	{ text: 'Add an RSS Feed', slug: 'guides/rss', key: 'guides/rss' },

[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.