[v6] Update astro:content docs

[ArmandPhilippot]

Description (required)

• Updates some existing types (build-time) to:
  • add links when we document the type
  • simplify the types (i.e. while CollectionEntry is generic, maybe it's not important to show <collection> in the return type: it makes it easier to read and to be valid we should rather use CollectionEntry<CollectionKey>?)
• Fixes live content collections docs (types, description and snippets)
• Rewords some existing descriptions for consistency and to follow our API references guide
• Adds docs for filePath and rendered in CollectionEntry
• Removes some undocumented types from the types import list because, if we list undocumented types, there are a bunch of them available! (see below, I listed them in a details)

Note: I left a TODO inside the file because we need to create the reference docs for live loaders and add a link!

TODO: Document the live collections types

Related issues & labels (optional)

• Related: to be merged in [v6] New content collections guide includes live collections #12604
• Suggested label: 6.0, improve or update documentation

---

I haven't created the types yet because, except LiveDataEntry I'm not sure which ones to document yet. And some types (including LiveDataEntry) are not exported from astro:content but astro!

See all the imports available from `astro:content`

import {
  type AllValuesOf,
  type BaseSchema,
  type CollectionEntry,
  type CollectionKey,
  type ContentCollectionKey,
  type ContentConfig,
  type DataCollectionKey,
  type DataEntry,
  type DataEntryMap,
  type DataStore,
  type ExtractCollectionFilterType,
  type ExtractEntryFilterType,
  type ExtractErrorType,
  type ExtractLoaderTypes,
  type Flatten,
  type ImageFunction,
  type InferEntrySchema,
  type LiveContentConfig,
  type LiveLoaderCollectionFilterType,
  type LiveLoaderDataType,
  type LiveLoaderEntryFilterType,
  type LiveLoaderErrorType,
  type MetaStore,
  type ReferenceDataEntry,
  type ReferenceLiveEntry,
  type Render,
  type RenderResult,
  type RenderedContent,
  type ReturnTypeOrOriginal,
  type SchemaContext,
  defineCollection,
  defineLiveCollection,
  getCollection,
  getDataEntryById,
  getEntries,
  getEntry,
  getEntryBySlug,
  getLiveCollection,
  getLiveEntry,
  reference,
  render,
  z,
} from "astro:content";

See the imports related to live collections available from `astro`

import type {
  LiveDataCollection,
  LiveDataCollectionResult,
  LiveDataEntry,
  LiveDataEntryResult,
} from "astro";

I guess the import from astro should be fixed at least in the next branch in core.

I also noticed:

• the ReferenceLiveEntry type is available but it doesn't seem to be used anywhere?
• we don't have a LiveCollectionKey alias similar to CollectionKey for build-time collections, it would be nice I think.

Nothing blocking here, but I was also surprised (because they were already deprecated in v4) to see we still have getEntryBySlug and getDataEntryById in v6! 👀 It seems they will be removed in v7.

[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/reference/content-loader-reference.mdx	Source changed, localizations will be marked as outdated.
en/reference/modules/astro-content.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]

Thank you Armand! Let's get @ascorbic to review this one!

[sarah11918]

Question: is the schema property any different for the two collections? I'm wondering whether these should just be combined into one if not?

(Then, the line can say e.g. "When you define a schema in a live collection, it will take precedence over the live loader’s types when you query the collection."

[ascorbic]

Live collections can't have the function syntax for schemas (i.e. no image helper)

[ArmandPhilippot]

Yes, as Matt said, because they don't share the same type it might be better to have them separated. But we could apply the same changes that you've suggested for loader to reduce the confusion between the two!

[ArmandPhilippot]

I pushed a new commit to add some links between the two schema as Sarah's suggested for the loader property.

I think everything seems okay if you want to merge this in your PR Sarah. We can always update the types later once we figured out:

• if the import from astro should be moved to astro:content
• if we should have a LiveCollectionKey alias similar to CollectionKey for build-time collections, to have balanced types between the two.

And as reminder there is a TODO comment in my PR because a link would make sense here I think, but we'll need to describe the API to build a live loader first.

And thank you both for your reviews! 🙌🏽

[sarah11918]

Thank you Armand! I believe this is good to merge, yes. It can still be updated in the other PR as necessary, but this was super helpful to keep the noise lower on that one!

[ascorbic]

Moving the type export to astro:content makes sense I think. I can't remember what my reason was for exporting it from the astro, but it's probably somehting that no longer exists

[yanthomasdev]

Good work, just a couple small nits from me!

[ArmandPhilippot]

I was annoyed about merging this with the TODO, so I pushed a new commit that adds docs for the Live Loader API! I haven't added much content in "Loader types" because we already describe that in the Content Collections guide.