[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 - focuses on what collections are; how to configure/define; how to use data in a collection (querying, rendering, generating routes)
• astro:content module reference - API reference for things imported from astro:content
• Content Loader API reference - API reference for Content Loader (including Build-time collections and Live Collections) including explaining the basic format/functions of loaders and how to build them.

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

TODO:

• LiveData* types are still mostly placeholders
• check for needed updates to Content collections guide now that we don't talk about these "types" of loaders anymore (inline, object, live)

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	eb4431c
🔍 Latest deploy log	https://app.netlify.com/projects/astro-docs-2/deploys/6928c62e002fd50008202d3b
😎 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]

(Note that previous commit updates from changes made in #12571 )

[ArmandPhilippot]

Based on Chris feedback in #12790 I made two suggestions for the cacheHint code snippet.

Edit: Hmm Github is buggy on my side... 👀 The first comment should have removed import { byLastModified } from "./sort"; too... And if I go back to the file diff, I can't even see my suggestions...

[sarah11918]

We're going to have stuff to look at during Talking and Doc'ing tomorrow 😅

[ArmandPhilippot]

The following suggestions should fix the issues @HiDeoo noticed on T&D!