[v6] New content collections guide includes live collections #12604
Conversation
…Live Data to focus on using content (not loader building)
…nt seem less overwhelming
…available earlier
✅ Deploy Preview for astro-docs-2 ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
sarah11918
changed the title
Lunaria Status Overview🌕 This pull request will trigger status changes. Learn moreBy default, every PR changing files present in the Lunaria configuration's You can change this by adding one of the keywords present in the Tracked Files
Warnings reference
|
sarah11918
added
improve or update documentation
|
And here we go... |
|
Pfft... not concerned! 
|
github-actions
bot
added
the
i18n
Co-authored-by: Armand Philippot <[email protected]>
Co-authored-by: Armand Philippot <[email protected]>
…o/docs into stable-live-collections
|
This one's for @OliverSpeir and @ArmandPhilippot ! See what you think of the latest reorganization. I will note that to have higher Build/Live sections means every section is now one heading level deeper, and I don't think we could publish this page without showing (Note: JSON schemas and below is still just the accumulated pile at the end of the page 😆 ) |
There was a problem hiding this comment.
I will note that to have higher Build/Live sections means every section is now one heading level deeper, and I don't think we could publish this page without showing h4s now. But, see whether this feels better to you!
Well, I might be biased because I use tables of contents a lot (on all websites), so I don't think displaying h4 is a problem when relevant.
The structure seems clearer to me, and I think it's easier to identify/navigate to the right section! And I haven't noticed too much repeats (e.g. schema), so I think the new organization looks better! Great job!
I left a few comments on sections that haven't been updated, but without suggestions. The new GitHub experience is not so great. 😅
Co-authored-by: Armand Philippot <[email protected]>
Co-authored-by: Matt Kane <[email protected]>
ArmandPhilippot
left a comment
ArmandPhilippot
left a comment
There was a problem hiding this comment.
I haven't reread everything in details yet, only the most recent commits. But, this seems to be in good shape for me. And I see you've applied some code snippets changes based on HiDeoo feedbacks! 🙌🏽
I'll give another (deeper) look tomorrow! At the moment, I only spotted some oddness in headings.
Co-authored-by: Armand Philippot <[email protected]>
Yes, the advantage to talking about loaders first, and |
|
I reread everything and I didn't spotted any issue with the organization or the wording, this looks good to me! 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 |
| You can define a **collection** from a set of data that is structurally similar. This can be a directory of blog posts, a JSON file of product items, or any data that represents multiple items of the same shape. | ||
|
|
||
| Collections stored locally in your project or on your filesystem can have entries of Markdown, MDX, Markdoc, YAML, TOML, or JSON files: | ||
| A content collection is a set of related, structurally-identical data. This data can be stored in one or several files locally (e.g. a folder of individual Markdown files of blog posts, a single JSON file of product descriptions) or fetched from remote sources such as a database, CMS or API endpoint. Each member of the collection is called an entry. |
There was a problem hiding this comment.
no hyphen after a -ly word + comma nit
| A content collection is a set of related, structurally-identical data. This data can be stored in one or several files locally (e.g. a folder of individual Markdown files of blog posts, a single JSON file of product descriptions) or fetched from remote sources such as a database, CMS or API endpoint. Each member of the collection is called an entry. | |
| A content collection is a set of related, structurally identical data. This data can be stored in one or several files locally (e.g. a folder of individual Markdown files of blog posts, a single JSON file of product descriptions) or fetched from remote sources such as a database, CMS, or API endpoint. Each member of the collection is called an entry. |
|
|
||
| - You have only one or a small number of different content pages. Consider [making individual page components](/en/basics/astro-pages/) such as `src/pages/about.astro` with your content directly instead. | ||
| - You are displaying files that are not processed by Astro, such as PDFs. Place these static assets in the [`public/` directory](/en/basics/project-structure/#public) of your project instead. | ||
| - Your data source has its own SDK/client library for imports that is incompatible with or does not offer a content loader and you prefer to use it directly. |
There was a problem hiding this comment.
comma nit
| - Your data source has its own SDK/client library for imports that is incompatible with or does not offer a content loader and you prefer to use it directly. | |
| - Your data source has its own SDK/client library for imports that is incompatible with or does not offer a content loader, and you prefer to use it directly. |
|
|
||
| ## Types of collections | ||
|
|
||
| **[Build-time content collections](#build-time-content-collections)** are updated at build time and data is saved to a storage layer. This provides excellent performance for most content, but may not be suitable for frequently updating data sources requiring up-to-the-moment data freshness such as live stock prices. |
There was a problem hiding this comment.
comma nit
| **[Build-time content collections](#build-time-content-collections)** are updated at build time and data is saved to a storage layer. This provides excellent performance for most content, but may not be suitable for frequently updating data sources requiring up-to-the-moment data freshness such as live stock prices. | |
| **[Build-time content collections](#build-time-content-collections)** are updated at build time, and data is saved to a storage layer. This provides excellent performance for most content, but may not be suitable for frequently updating data sources requiring up-to-the-moment data freshness, such as live stock prices. |
|
|
||
| Both kinds of collections can exist in the same project, so you can always choose the best type of collection for each individual data source. For example, a build-time collection can manage product descriptions, while a live collection can manage content inventory. | ||
|
|
||
| Both types of collections use similar APIs (e.g. `getCollection()` and `getLiveCollection()`) so that working with collections will feel familiar no matter which one you choose, while still ensuring that you always know which type of collection you are working with. |
There was a problem hiding this comment.
comma nit
| Both types of collections use similar APIs (e.g. `getCollection()` and `getLiveCollection()`) so that working with collections will feel familiar no matter which one you choose, while still ensuring that you always know which type of collection you are working with. | |
| Both types of collections use similar APIs (e.g. `getCollection()` and `getLiveCollection()`), so that working with collections will feel familiar no matter which one you choose, while still ensuring that you always know which type of collection you are working with. |
|
|
||
| ## TypeScript configuration for collections | ||
|
|
||
| Content collections rely on TypeScript to provide Zod validation, Intellisense and type checking in your editor. If you are not extending one of Astro's `strict` or `strictest` TypeScript settings, you will need to ensure the following `compilerOptions` are set in your `tsconfig.json`: |
There was a problem hiding this comment.
retroactive comma nit
| Content collections rely on TypeScript to provide Zod validation, Intellisense, and type checking in your editor. If you are not extending one of Astro's `strict` or `strictest` TypeScript settings, you will need to ensure the following `compilerOptions` are set in your `tsconfig.json`: |
|
|
||
| <p><Since v="6.0.0" /></p> | ||
|
|
||
| Live content collections offer APIs to configure, query and render fresh, up-to-the-moment live data from remote sources. |
There was a problem hiding this comment.
| Live content collections offer APIs to configure, query and render fresh, up-to-the-moment live data from remote sources. | |
| Live content collections offer APIs to configure, query, and render fresh, up-to-the-moment live data from remote sources. |
|
|
||
| When you define a schema, it will take precedence over the [live loader’s types](/en/reference/content-loader-reference/#live-loader-api) when you query the collection. | ||
|
|
||
| [See the `Content Collection` guide](/en/guides/content-collections/#using-zod-schemas-with-live-collections) for example usage. |
There was a problem hiding this comment.
Content Collection in backticks feels wrong since we use it for indicating code parts, plus we tend to refer to the usual guide title (in plural, in this case). I see this is replicated all over this page, but in all other pages, we write it as "See the Content Collections guide".
I guess it makes sense to change all the instances here.
| <Since v="6.0.0" /> | ||
| </p> | ||
|
|
||
| A function that retrieves a single live collection entry by collection name and an optional filter either as an `id` string or as a type-safe object. |
There was a problem hiding this comment.
| A function that retrieves a single live collection entry by collection name and an optional filter either as an `id` string or as a type-safe object. | |
| A function that retrieves a single live collection entry by collection name and an optional filter, either as an `id` string or as a type-safe object. |
| **Type:** `(context: LoadCollectionContext<TCollectionFilter>) => Promise<LiveDataCollection<TData> | { error: TError; }>` | ||
| </p> | ||
|
|
||
| Defines a method to load a collection of entries. This function receives a [context object](#loadcollectioncontext) containing an optional `filter` property and must return a the data associated to this collection or the errors. |
There was a problem hiding this comment.
typo + nit
| Defines a method to load a collection of entries. This function receives a [context object](#loadcollectioncontext) containing an optional `filter` property and must return a the data associated to this collection or the errors. | |
| Defines a method to load a collection of entries. This function receives a [context object](#loadcollectioncontext) containing an optional `filter` property and must return the data associated with this collection or the errors. |
| **Type:** `(context: LoadEntryContext<TEntryFilter>) => Promise<LiveDataEntry<TData> | undefined | { error: TError; }>` | ||
| </p> | ||
|
|
||
| Defines a method to load a single entry. This function receives a [context object](#loadentrycontext) containing a `filter` property and returns either the data associated to the requested entry, `undefined` when the entry cannot be found, or the errors. |
There was a problem hiding this comment.
| Defines a method to load a single entry. This function receives a [context object](#loadentrycontext) containing a `filter` property and returns either the data associated to the requested entry, `undefined` when the entry cannot be found, or the errors. | |
| Defines a method to load a single entry. This function receives a [context object](#loadentrycontext) containing a `filter` property and returns either the data associated with the requested entry, `undefined` when the entry cannot be found, or the errors. |
Description (required)
Whew! First draft ready for review!
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 creates placeholder (for now) entries in the
astro:contentmodule reference page. These will need thorough review and also a check to make sure there's nothing else that needs API reference docs!This is currently a NWTWWHB draft: content from the current existing Experimental Live Collections reference page has been interwoven with existing (and updated!) content for "regular" build-time collections. This may not be the correct info architecture, and that's OK! This is where we are starting from.
My thoughts throughout this PR:
It is important to name and distinguish the two types of collections
the two built-in build time loaders (
glob()andfile()) 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 for now, interleaving Build-time Collection content and Live Collection content. There's a world where Build time and live collections are split out into discrete sections, each following that pattern. However, I think that leads to some duplication and I have added a LOT of internal linking so people can get to where they need to go.
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 SSR" and "live collections", so I've tried to add a few nods to that.
Right now, we're showing ALL headings from
##to#####. We won't do that in the final draft. This makes it easy to see the structure while working on it, and for me to easily jump to different sections. But, we'll only have a TOC with##and###and I think the way I have it set up, this will look pretty reasonable.Lots of section headings have changed, so probably some link damage to fix up.
Comment threads "resolved" to maybe loop back around to
For Astro version:
6.0. See astro PR #14550.