Configuring Astro guide is not in nav

[br3ndonland]

📚 Subject area/topic

configuration

📋 Page(s) affected (or suggested, for new content)

https://docs.astro.build/en/guides/configuring-astro/

📋 Description of content that is out-of-date or incorrect

Thanks for Astro and for these helpful docs. I refer to the "Configuring Astro" page a lot, but I can't find it in the sidebar nav, so I have to rely on browser bookmarks to find it.

It looks like nav entries are commented out.

docs/src/i18n/en/nav.ts

Lines 151 to 155 in 2b22e59

	// {
	// text: 'The Astro Config File',
	// slug: 'guides/configuring-astro',
	// key: 'guides/configuring-astro',
	// },

In #8239, @sarah11918 said:

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!

Could we consider including "Configuring Astro" in the nav?

I'm open to suggestions on where to put it. It could potentially go in the "Welcome, World!" section. There's an entry for "Deploy Your Site," which could also be considered an "early and once" action. We could add an entry for "Configure Your Site" just before "Deploy Your Site."

As a sidenote (maybe for a separate issue/PR) the comment that the page "is now highlighted right on the "Install and Setup" page as "Next Steps" with fancy cards" is actually not correct. There's no card for it, and it's actually not mentioned at all. There's a link to the configuration reference but not to the "Configuring Astro" configuration guide.

docs/src/content/docs/en/install-and-setup.mdx

Line 381 in 2b22e59

Read Astro's [API configuration reference](/en/reference/configuration-reference/) for more information.

I'm happy to contribute PRs for any related changes.

🖥️ Reproduction in StackBlitz (if reporting incorrect content or code samples)

No response

[sarah11918]

Thanks @br3ndonland , you're right! That was a huge PR that went through multiple iterations and at one point there was a card alongside editor setup and typescript cards. In the end, it was removed because I wasn't sure what direction I wanted the Configuring Astro page to take - much of the content there is kind of duplicated from the actual configuration page and other places, and I felt like it could be better organized.

Can you let me know what content from there you are regularly using? That would help me figure out whether this separate page is in fact needed, and if so, where!

[br3ndonland]

Thanks @sarah11918 for your prompt reply and for the additional context.

I do find the "Configuring Astro" page helpful as an overview of how the config file works. Some things I refer to:

• Supported config file types (I eventually converted my file to .ts to get improved IntelliSense on some plugin configuration options)
• Referencing relative files (specifically the import.meta.url strategy for referencing other files relative to the config file)

You raise a good question about "whether this separate page is in fact needed" - I think the content could also go directly on the configuration reference page, maybe in the overview section at the beginning.

[sarah11918]

Thanks for this helpful context! It's really useful for me to know. Let me think about this to figure out how to best place or surface that content! (And anyone else with thoughts is welcome to chime in.)

For example, we do list the astro.config.mjs file in the Project Structure page, which then contains a link to this page like this:

We could decide that it's worth saying there that this file can support various config types to at least get that bit of info out early, for example. (I do think adding the other context might make that page longer than it needs to be, so certainly using another page for this makes sense.) But, maybe it doesn't make sense to link to a Guide for more info, that then further tells you to go to a Reference page for more. 😄

Thank you again for bringing this up! And thanks for being the guinea pig tester! We often will decide, "Well, let's make a change and see whether anyone notices/complains..." so, here we are!

[br3ndonland]

That sounds great 👍. Thanks for considering my suggestion. If we decide on a path forward with this, I'm happy to contribute PRs for the related changes.

[sarah11918]

So, immediately, I could see adding this as a second paragraph in that section on the Project Structure page:

We recommend naming this file `astro.config.mjs` in most cases, or `astro.config.ts` if you want to write TypeScript in your config file. However, Astro supports any of the following configuration files: `astro.config.js`, `astro.config.mjs` , `astro.config.cjs`, and `astro.config.ts`.

If you'd like to make a PR to that page with the above, that would be great! I'll keep thinking about the "referencing relative files" situation!

[sarah11918]

Closing this issue for now as I have this, and the other hidden pages, on my radar for 5 beta docs to make sure content is available! This may involve moving content to other pages, and/or making this page more discoverable, but it's part of a larger strategy with some other "configure things" pages like TypeScript and Environment variables, and already recorded as a task to complete for 5 stable docs!