[v6] New content collections guide includes live collections

[sarah11918]

Description (required)

This PR updates the Content Collections guide so that it describes and differentiates the two types of collections we will have stable in v6: build-time and live. It also updates entries in the astro:content module reference page and the Content Loader API page:

• Guide
• astro:content module reference
• Content Loader API reference

This incorporates content from the current existing Experimental Live Collections reference page into the new main content collections guide page.

My thoughts throughout this PR:

• It is important to name and distinguish the two types of collections (build-time and live)

• the two built-in build time loaders (glob() and file()) now have their own, clear, discoverable sections.

• The natural order of "setting up a collection" is still: define it, add a loader, most likely add a schema; then you're able to query/filter and render; oh, and you probably are going to want dynamic pages based on your entries. So, I've kept that overall structure. Build time and live collections are split out into discrete sections, each following that pattern, based on feedback.

• Did I say I added a LOT of internal page linking?? One big challenge here is that setting up a simple blog with local Markdown files is much less complicated than needing to build your own live loader. Frankly, there's a crap ton of loader content, but you can't do anything until you have a loader so it feels difficult to offload it to the bottom of the page and just say "go off here to learn about loaders so I can show you the rest of content collections". (see next point)

• My solution here is the "Types of Collections" section at the beginning with informative, skeleton content that addresses EVERYTHING with links (defining, querying, rendering, generating pages) for each of build and live collections. e.g. As long as you read the short "Build-time content collections", you'll be armed with everything you need to know via direct links to each section you care about.... including a tip to go look at the Astro Blog starter template to see a simple build-time collection in action for a "quick start" approach. (The same is true about the "Live content collections" section: it provides a good overview of the "getting set up" steps with links to identify all the links in the chain. But sorry, you're going to have to figure out how to build a live loader before you can actually do anything.)

• We now need to differentiate between "build-time rendered on demand" and "live collections", so I've tried to add a few nods to that. (It's possible to have build-time collections that are built once, upon first request and their content added to the data store layer vs. live collections which are always (re)fetched fresh at each individual request time.)

• Since people prefered splitting up build time and live collections into their own headings (##), we're showing headings from ## to #### in the TOC. I think this is necessary now because most content is now a heading level lower, including stuff that is helpful to have visible.

• Lots of section headings have changed, so there was some link damage to fix up.

Comment threads "resolved" to maybe loop back around to

• Should there be a "When to use each type of collection" vs the few bullet points at the beginning of each of Build-time and Live Collections? I reorganized content so that this is included without needing a separate heading, I think.
• Should section headers be standardized when there is duplication, or distinct to help keep the ideas distinct? (e.g. "Querying build-time collections" vs "Accessing Live Data")
  - I (Sarah) am fairly strongly in favour of keeping the distinction since the API are different (though the helper functions names have been made to be similar). "Querying some files" is different from "fetching some data live", and I personally like the headings reflecting this I also think this makes for better page navigation (allows each heading to be distinct and less likely to get them mixed up or click on the wrong one). But, right now I think it's only Oliver and I that have weighed in with an opinion here! Others are welcome to give feedback on this!
• Live collections limitations and differences from build time are currently sections at the bottom of the page as "further reading", but linked to from the main entry on live collections for those who need to read further. My concern with putting them up is "making someone get PhD in everything Live Collections" before they get to read more. This feels like info that is OK to just be available/accessible as long as it's clearly linked to as we've done. I've worked this content in without section headings (keeps the table of content simpler) in the introductory section.

For Astro version: 6.0. See astro PR #14550.

[netlify]

✅ Deploy Preview for astro-docs-2 ready!

Name	Link
🔨 Latest commit	862e58b
🔍 Latest deploy log	https://app.netlify.com/projects/astro-docs-2/deploys/691cbd59ae73d70008c46815
😎 Deploy Preview	https://deploy-preview-12604--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 project 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/cms/keystatic.mdx	Source changed, localizations will be marked as outdated.
en/guides/content-collections.mdx	Source changed, localizations will be marked as outdated.
en/guides/imports.mdx	Source changed, localizations will be marked as outdated.
en/guides/integrations-guide/markdoc.mdx	Source changed, localizations will be marked as outdated.
en/guides/integrations-guide/mdx.mdx	Source changed, localizations will be marked as outdated.
en/guides/markdown-content.mdx	Source changed, localizations will be marked as outdated.
en/guides/media/cloudinary.mdx	Source changed, localizations will be marked as outdated.
en/guides/migrate-to-astro/from-create-react-app.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-nextjs.mdx	Source changed, localizations will be marked as outdated.
en/guides/upgrade-to/v6.mdx	Source changed, localizations will be marked as outdated.
en/reference/cli-reference.mdx	Source changed, localizations will be marked as outdated.
en/reference/content-loader-reference.mdx	Source changed, localizations will be marked as outdated.
en/reference/errors/content-collection-missing-loader.mdx	Source changed, localizations will be marked as outdated.
en/reference/errors/file-glob-not-supported.mdx	Source changed, localizations will be marked as outdated.
en/reference/errors/legacy-content-config-error.mdx	Source changed, localizations will be marked as outdated.
en/reference/modules/astro-content.mdx	Source changed, localizations will be marked as outdated.
en/tutorial/6-islands/4.mdx	Source changed, localizations will be marked as outdated.
es/guides/media/cloudinary.mdx	Localization changed, will be marked as complete.
es/tutorial/6-islands/4.mdx	Localization changed, will be marked as complete.
it/tutorial/6-islands/4.mdx	Localization changed, will be marked as complete.
ja/guides/integrations-guide/markdoc.mdx	Localization changed, will be marked as complete.
ja/guides/migrate-to-astro/from-create-react-app.mdx	Localization changed, will be marked as complete.
pt-br/tutorial/6-islands/4.mdx	Localization changed, will be marked as complete.
ru/reference/errors/mixed-content-data-collection-error.mdx	Localization changed, will be marked as complete.
ru/tutorial/6-islands/4.mdx	Localization changed, will be marked as complete.

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]

And here we go...

[sarah11918]

Pfft... not concerned!

[sarah11918]

you've applied some code snippets changes based on HiDeoo feedbacks!

Yes, the advantage to talking about loaders first, and schema isn't strictly speaking necessary, then I could just remove it from the loader sections!

[ArmandPhilippot]

I reread everything and I didn't spotted any issue with the organization or the wording, this looks good to me!
The only exception is in "What is a loader" (Content Loader reference): we only talk about build time loaders which can be confusing. I also checked every code snippets in the 3 pages and I noticed some additional fixes.

Because it was easier to create a PR than creating multiple review comments, here's my suggestions: #12685

I also noticed something unclear regarding the import of the loader errors classes, maybe Matt can confirm where they should be imported from.

In two code snippets we were importing LiveCollectionValidationError and LiveEntryNotFoundError from astro:content. When I checked with the experimental flag (v5), they were not available. Intellisense (and I, in the next branch) could find them in astro/content/runtime though. But, looking at the most recent update in the roadmap proposal this should be available from astro/loaders. 😅

[yanthomasdev]

Is it final boss time?

[HiDeoo]

Left a few thoughts and suggestions but this looking really great! So many improvements all around while incorporating new content at the same time. 👏

[ArmandPhilippot]

See what you think of the updated example! This doesn't look bad to me to show how is() works. Nice idea!

Edit: updated based on T&D feedbacks to remove is()

[ArmandPhilippot]

Based on T&D, we also need to update two other places in addition to my previous suggestions.

[ArmandPhilippot]

Except one wrong use of slug, I think everything is correct here. And maybe we could reduce the confusion by swapping a valid example.

[sarah11918]

@ascorbic The example shown here on the Loader API page is the same as the one shown in the content collections guide. The content in both places here is pretty much identical.

Do you have a preference for where this example lives, here in reference or in the guide?

(Either way, this note should go because it doesn't provide any additional info)

[sarah11918]

@ascorbic Also noting we show no code examples for a lot of these properties, and not even one big "example loader object" to start. Maybe this could be more helpful with some code?

[sarah11918]

@ascorbic I left a couple of quick comments above, otherwise, I think everyone who intends to has left feedback here and I've addressed it!

Would be great if you could do a final pass review on (deploy preview links):

• Content Collections Guide
• astro:content module reference
• Content Loader API reference

And, of course, no worries if you notice something drastic and want big changes! There's still lots of time! But, I think everyone else has exhausted themselves, so we'll need fresh eyes for anything much new to happen. 😄