Clarify content collection and page routing for Astro v5

[anaxite]

Summary

This pull request reviews and edits wording around page and content collection routing to better explain file exclusion in 5.0.

Description

In 5.0, content collections don't exclude any files by default. Particular globs are needed to exclude a file, which isn't necessarily clear. This change may also create confusion when comparing the behavior to page routing, which does exclude underscores.

This PR attempts to clarify the behavior change, and make content collection behavior stand out more compared to page routing.

Related issues & labels

• Closes Content collection loader examples are inconsistent #10300
• Suggested labels:
  • code snippet update
  • improve documentation

[netlify]

✅ Deploy Preview for astro-docs-2 ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	7d3e2d3
🔍 Latest deploy log	https://app.netlify.com/sites/astro-docs-2/deploys/6761f4b0bdb3840008b7e683
😎 Deploy Preview	https://deploy-preview-10370--astro-docs-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[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

File	Note
en/guides/routing.mdx	Source changed, localizations will be marked as outdated.
en/guides/upgrade-to/v5.mdx	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.

[sarah11918]

This is looking pretty good @anaxite ! Is there a reason you still have this marked as a draft? Are you doing more with it?

Also noting that I will add something to the v5 upgrade guide in case people were using the built-in prefix trick that was supported in the old content collections API

[anaxite]

I'm doing a last check, and then it'll be out of draft :)

[sarah11918]

Noting that the Upgrade guide should also something like the following changes to the Legacy collections introduction:

In Astro 4.x, content collections were defined, queried, and rendered using [the Content Collections API first introduced in Astro v2.0](https://astro.build/blog/introducing-content-collections/). All collection entries were local files within the reserved `src/content/` folder. Additionally, Astro's [file name convention to exclude building individual pages](/en/guides/routing/#excluding-pages) was built in to the Content Collections API.

Astro 5.0 introduces a new version of content collections using the Content Layer API which brings several performance improvements and added capabilities. While old (legacy) and new (Content Layer API) collections can continue exist together in this release, there are potentially breaking changes to existing legacy collections.

This release also removes the option to prefix collection entry file names with an underscore (`_`) to prevent building a route.

(for readability):

In Astro 4.x, content collections were defined, queried, and rendered using the Content Collections API first introduced in Astro v2.0. All collection entries were local files within the reserved src/content/ folder. Additionally, Astro's file name convention to exclude building individual pages was built in to the Content Collections API.

Astro 5.0 introduces a new version of content collections using the Content Layer API which brings several performance improvements and added capabilities. While old (legacy) and new (Content Layer API) collections can continue exist together in this release, there are potentially breaking changes to existing legacy collections.

This release also removes the option to prefix collection entry file names with an underscore (_) to prevent building a route.

[anaxite]

Alright, feel free to go ahead with the upgrade guide!

[anaxite]

Under #updating-existing-collections, on step 2, would it be worth adding a sentence like "Edit the pattern depending on what files you want to exclude." or is that too wordy? I'm thinking that's another signal that behavior has changed.

[sarah11918]

It's not a bad idea, but you're right, it's starting to get a bit much for something that probably most people will not have, and therefore an extra thought that might get put in their head? "Wait, exclude?"

Can we try as-is to start, as already a definite improvement?

[anaxite]

Sounds good. I like the addition!