[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! 
|
| :::note | ||
| Projects may continue using the legacy Content Collections API introduced in Astro v2.0. However, we encourage you to [update any existing collections](/en/guides/upgrade-to/v5/#legacy-v20-content-collections-api) when you are able. | ||
| ::: | ||
| Whether your content lives locally in your project, is stored remotely, or is even fetched from a live, frequently-updating source, Astro provides performant, scalable APIs to load, query, and render your content. |
There was a problem hiding this comment.
| Whether your content lives locally in your project, is stored remotely, or is even fetched from a live, frequently-updating source, Astro provides performant, scalable APIs to load, query, and render your content. | |
| Astro provides performant, scalable APIs to load, query, and render content from local, remote, or live sources. |
There was a problem hiding this comment.
I guess the idea is to hype the feature a bit in the intro and make it flow more smoothly with the previous sentence.
I don't have a strong opinion on this, but perhaps your suggestion is a little too abrupt because of the previous sentence? (not a native speaker, so maybe this is just a me thing)
There was a problem hiding this comment.
You're probably right theres a golden middle ground, the core of my suggestion is just that that sentence could be polished
There was a problem hiding this comment.
Fair! There are a lot of commas. 😅 Yes, let's tag this as a sentence that def needs polishing, and perhaps breaking up into multiple sentences, but with the reminder that its goal is to (a little bit) overwhelm with ALL THINGS ARE POSSIBLE
| ## What are Content Collections? | ||
|
|
||
| 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. | ||
| 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. Individual items within a collection are called **entries**. |
There was a problem hiding this comment.
This does not actually answer the question of what is a content collection, just starts of with a list of things you can do
maybe something like "A Content Collection in Astro is a schema-based structure that defines the shape of related content and provides a consistent way to access it"
There was a problem hiding this comment.
Since we're revisiting the whole page, I think this section could be improved:
- I like Oliver's suggestion.
- We're linking to build time and live collections without explaining what they are/their difference before. To avoid duplicating the "Types of collections", I think a link to that section could make sense.
Maybe something like:
Content Collections are schema-based structures that define the shape of your data and provide a consistent way to access it.
You can define ...
Two [types of content collections]((#types-of-collections)) are available to allow you to work with local or remote data, fetched at build time or at request time. Both [build-time collections](#build-time-content-collections) and [live updating collections](#live-content-collections) use:
* an optional [`schema`](#defining-the-collection-schema) to define the expected shape of each entry, providing type safety, autocomplete, and validation in your editor.
* a required `loader` to retrieve your content from wherever it is stored.
/* ... */
Not quite sure about the wording tough, but I don't know something bothers me with the current flow. Maybe this is just because we don't introduce the types before saying "Both"...
The rest looks great to me! I get Oliver's remark but I think "how they work" being part of "what they are" is fine.
| Both [build-time collections](#build-time-content-collections) and [live updating collections](#live-content-collections) use a `loader` to retrieve your content from wherever it is stored. | ||
|
|
||
| Collections stored locally in your project or on your filesystem can have entries of Markdown, MDX, Markdoc, YAML, TOML, or JSON files: | ||
| Collections stored locally in your project or on your filesystem can use one of Astro's [built-in build-time loaders](#build-time-collection-loaders) to fetch data from Markdown, MDX, Markdoc, YAML, TOML, or JSON files: |
There was a problem hiding this comment.
This doesnt seem to be part of the defintion of what is a content collection to me, more of usage type section information
There was a problem hiding this comment.
Yes, this is part of the "can we keep the simple stuff up front" attempt by keeping this here. It could absolutely move to join with build-time! But we lose a bit of a) a visual break and b) seeing how easy this is for the simple case super early.
| Much of the benefit of using collections comes from: | ||
|
|
||
| - Defining a common data shape to validate that an individual entry is "correct" or "complete", avoiding errors in production. | ||
| - Content-focused APIs designed to make querying intuitive (e.g. `getCollection()` instead of `import.meta.glob()`) when importing and rendering content on your pages. | ||
| - Both built-in loaders and access to the low-level [Content Loader API](/en/reference/content-loader-reference/) for retrieving your content. There are additionally several third-party and community-built loaders available, and you can build your own custom loader to fetch data from anywhere. | ||
| - Performance and scalability. Build-time content collections data can be cached between builds and is suitable for tens of thousands of content entries. |
There was a problem hiding this comment.
This doesnt seem to me to answer the question of when to create a collection out of a certain set of data, more why to create collections in general. If we really want it in this section I'd put it after the direct answer in the list below "Define your data as a collection when:"
| - 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. | ||
|
|
||
| ## Types of collections |
There was a problem hiding this comment.
This seems to be to fit into the What are content collections section
There was a problem hiding this comment.
So your idea would be to have all the "general presentation" stuff first in a single section and then getting to technical guidance?
I'm trying to visualize your suggestions as a whole to see what the structure would look like:
- move
Types of collectionsinWhat are content collections - move some parts of
Build-time content collectionsandLive content collectionsto a newWhen to use which type of collectionsection which would be created inWhat are content collections? or inTypes of collections? - but then what do you do with what's left in
Build-time content collectionsandLive content collections? do you keep them inTypes of collectionsor do you extract them as top-level sections?
If nested inside "What are content collections", the discoverability might not be great (I'm thinking table of contents here). And, I'm not sure this fits the "general presentation" first approach because not everything presented there looks like "general presentation" to me.
If these are top-level sections, I guess we should move other stuff there (loaders as subheadings) to avoid confusion if people expect to find everything relevant to them there... This sounds like Sarah's other idea:
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.
Not sure how much duplication there would be. I haven't read it all yet. 😅
I agree, the "direct" content (excluding subheadings) looks like "general presentation" as before, so it could be put in the same section. But I'm not sure what to do with the subheadings... I don't have a strong opinion on this, I'm mostly curious about your idea!
There was a problem hiding this comment.
I wouldn't say it's a fully formed idea haha just grasping at one
When I wrote it I had in mind to leave what's left where it is 😅
There was a problem hiding this comment.
move some parts of Build-time content collections and Live content collections to a new When to use which type of collection section which would be created in What are content collections? or in Types of collections?
great question, I'm not sure haha
There was a problem hiding this comment.
Haha, no worries. It's not easy to be the first to review so many content changes! Glad you came first. 😁
I tried to think about what this might look like based on the current headings and your ideas.
Quick reorganization overview
What are Content Collections?
When to create a collection
When not to create a collection
Types of collections
Live collection limitations
Differences from build-time collections
Build-time content collections
Build time collection loaders
The glob() loader
The file() loader
Custom build-time loaders
Querying build-time collections
Using content in Astro templates
Rendering body content
Passing content as props
Filtering collection queries
Accessing referenced data
Live content collections
Creating a live loader
Providing rendered content
Error handling in live loaders
Type safety in live loaders
Defining data types
Defining custom filter types
Creating live loader error types
Cache hints
Accessing live data
Rendering content
Error handling
Defining the collection schema
Defining datatypes with Zod
Using Zod schemas with live collections
Defining collection references
Defining custom IDs
Generating Routes from Content
Building for static output (default)
Building routes on demand at request time
TypeScript configuration for collections
Distributing your loader
This doesn't include all the subheadings. And as I said before, I'm not sure how to deal with "Defining the collection schema" and "Generating Routes from Content".
I guess "Generating Routes from Content" in its current state could belong to "Build-time content collections". But we might need, in both cases, the same content adapted to live collections?
And maybe it's fine if "Defining the collection schema" is in its own section? But I'm not sure if "Defining collection references" and "Defining custom IDs" are shared or specific to build time collections. I would need to test this to get a better idea of how it works.
Now, moving headings is easy... evaluating whether the content flow is better and whether we are not duplicating too much content (maintenance cost) is another question...
There was a problem hiding this comment.
I like the list you've got my only thought is put these two headings into Live Content collections heading
Live collection limitations
Differences from build-time
I think that having both Build time collections and Live collections headings have their own sub heading for defining the schema at risk of duplication makes the most sense to me
If duplicating results in a more useful and easily digested page I think it's worth it. I know Sarah originally mentioned choosing not to split them out like this, but I think it's the right way to do it 😅 feel free to disregard of course just my thought
| We suggest using build-time content collections whenever possible, and using live collections when your content needs updating in real time and the performance tradeoffs are acceptable. | ||
|
|
||
| You may have both kinds of collections 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. `getEntry()` and `getLiveEntry()`) 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.
This seems to be to be worthy of its own sub heading "When to use which type of collection" or something like that
There was a problem hiding this comment.
I know we've talked about broader organization in other threads here. In general, this isn't so much about choosing which one (except line 77) but things like, "You can have both kinds in the same project!" and "they'll both look familiar, but it'll be clear which one is which!" which is more about the two types in general and not related to making a choice.
So it may be that line 77 only goes into some new section in a new structure we devise, but 79 and 81 are not about choosing, but belong somewhere where we are talking about both, and I think where we have the two definitions makes sense like this.
| For the best performance and scalability, use build-time content collections when: | ||
|
|
||
| - **Performance is critical** and you want to prerender data at build time. | ||
| - **Your data is relatively static** (e.g., blog posts, documentation, product descriptions). | ||
| - **You want to benefit from build-time optimization** and caching. | ||
| - **You need to process MDX** or perform image optimization. | ||
| - **Your data can be fetched once and reused** across multiple builds. |
There was a problem hiding this comment.
If a when to use which type of collection subheading is made, this also seems like good content for that section which would then free up this heading to be all about getting to the business of using a build time collection
| ))} | ||
| ``` | ||
|
|
||
| ## Accessing live data |
There was a problem hiding this comment.
Think this would make sense to mirror the "Querrying build time collections" and be "Querrying Live collections"
and for these to attempt to have symmetrical sub sections such as both covering error handling filtering body content etc
There was a problem hiding this comment.
It could, yes! But they actually both work differently (even though we've camouflaged that with nearly identical looking API names) so I intentionally made them different, and to make sections easier to distinguish. (Just explaining my thought process.)
There was a problem hiding this comment.
I think them being the same for both types will make the page more "usable" for the user. For example when wanting to learn the difference they won't need to translate in their head "accessing" to "querying" even though the intention is for these headings to refer the essentially the same action. "How do I actually get my stuff" is one of the key questions for a user to "get" the whole point of collections
There was a problem hiding this comment.
I'm not entirely sure it makes it more useable? (It for sure might, but there is a counter argument!) Seeing analogous phrases in a TOC can make them harder to stand out:
## Querying build-time collections
## Querying live collections
vs
## Querying build-time collections
## Accessing live data
I'm not convinced in it at all, so we should all talk about it, but a part of me likes that we're introducing terminology/phrases like "accessing live data" that makes distinctions clear. (I also feel like for live collections, the nature of the "entries" is more arbitrary -- it's kind of like we're polling live data and creating entries from it, vs build-time collections where we have entries. It feels like having distinct terminology could be helpful here!)
There was a problem hiding this comment.
Makes sense, loop me into the convo whenever/wherever it happens if you don't mind
github-actions
bot
added
the
i18n
There was a problem hiding this comment.
This wasn't an easy task, well done! 🙌🏽
I think the differentiation between the two types of collection is clear!
Seeing the table of contents, I'm tempted to gather every "Build-time" and every "Live" headings in a parent section for each... But I'm not sure how to handle "Defining the collection schema" and "Generating Routes from Content". I can see this could introduce some duplication...
So, your current approach looks fine to me. But, I'm curious to ear more about Oliver's idea.
I have not reviewed in detail the astro:content page because we might want to check the types using the v6 branch. Using Astro 5 with the experimental flag, there are currently a lot of (undocumented) types available. And one of them is confusing: LiveDataCollectionResult is exported from "astro" instead of "astro:content".
| ## What are Content Collections? | ||
|
|
||
| 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. | ||
| 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. Individual items within a collection are called **entries**. |
There was a problem hiding this comment.
Since we're revisiting the whole page, I think this section could be improved:
- I like Oliver's suggestion.
- We're linking to build time and live collections without explaining what they are/their difference before. To avoid duplicating the "Types of collections", I think a link to that section could make sense.
Maybe something like:
Content Collections are schema-based structures that define the shape of your data and provide a consistent way to access it.
You can define ...
Two [types of content collections]((#types-of-collections)) are available to allow you to work with local or remote data, fetched at build time or at request time. Both [build-time collections](#build-time-content-collections) and [live updating collections](#live-content-collections) use:
* an optional [`schema`](#defining-the-collection-schema) to define the expected shape of each entry, providing type safety, autocomplete, and validation in your editor.
* a required `loader` to retrieve your content from wherever it is stored.
/* ... */
Not quite sure about the wording tough, but I don't know something bothers me with the current flow. Maybe this is just because we don't introduce the types before saying "Both"...
The rest looks great to me! I get Oliver's remark but I think "how they work" being part of "what they are" is fine.
| - 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. | ||
|
|
||
| ## Types of collections |
There was a problem hiding this comment.
So your idea would be to have all the "general presentation" stuff first in a single section and then getting to technical guidance?
I'm trying to visualize your suggestions as a whole to see what the structure would look like:
- move
Types of collectionsinWhat are content collections - move some parts of
Build-time content collectionsandLive content collectionsto a newWhen to use which type of collectionsection which would be created inWhat are content collections? or inTypes of collections? - but then what do you do with what's left in
Build-time content collectionsandLive content collections? do you keep them inTypes of collectionsor do you extract them as top-level sections?
If nested inside "What are content collections", the discoverability might not be great (I'm thinking table of contents here). And, I'm not sure this fits the "general presentation" first approach because not everything presented there looks like "general presentation" to me.
If these are top-level sections, I guess we should move other stuff there (loaders as subheadings) to avoid confusion if people expect to find everything relevant to them there... This sounds like Sarah's other idea:
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.
Not sure how much duplication there would be. I haven't read it all yet. 😅
I agree, the "direct" content (excluding subheadings) looks like "general presentation" as before, so it could be put in the same section. But I'm not sure what to do with the subheadings... I don't have a strong opinion on this, I'm mostly curious about your idea!
|
|
||
| You can then use the dedicated `getCollection()` and `getEntry()` functions to [query your content collections data](#querying-build-time-collections) and render your content. | ||
|
|
||
| You can choose to [generate page routes](#generating-routes-from-content) from your build-time collection entries at build time for an entirely static, prerendered site. Or, you can render your build-time collections on demand, choosing to delay building your page until it is first requested. This is useful when you have a large number of pages (e.g. thosands, or tens of thousands) and want to delay building a static page until it is needed. |
There was a problem hiding this comment.
typo:
| You can choose to [generate page routes](#generating-routes-from-content) from your build-time collection entries at build time for an entirely static, prerendered site. Or, you can render your build-time collections on demand, choosing to delay building your page until it is first requested. This is useful when you have a large number of pages (e.g. thosands, or tens of thousands) and want to delay building a static page until it is needed. | |
| You can choose to [generate page routes](#generating-routes-from-content) from your build-time collection entries at build time for an entirely static, prerendered site. Or, you can render your build-time collections on demand, choosing to delay building your page until it is first requested. This is useful when you have a large number of pages (e.g. thousands, or tens of thousands) and want to delay building a static page until it is needed. |
|
|
||
| ### Error handling in live loaders | ||
|
|
||
| Loaders should handle all errors and return an [Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) subclass for errors. You can create custom error types and use them for more specific error handling if needed. If an error is thrown in the loader, it will be caught and returned, wrapped in a `LiveCollectionError`. You can also create [custom error types](#creating-live-loader-error-types) for proper typing. |
There was a problem hiding this comment.
This sentence is a bit confusing because we say "You can create custom error types.... You can also create custom error types". 😅 Maybe we don't need the last sentence?
| Loaders should handle all errors and return an [Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) subclass for errors. You can create custom error types and use them for more specific error handling if needed. If an error is thrown in the loader, it will be caught and returned, wrapped in a `LiveCollectionError`. You can also create [custom error types](#creating-live-loader-error-types) for proper typing. | |
| Loaders should handle all errors and return an [Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) subclass for errors. You can create [custom error types](#creating-live-loader-error-types) and use them for more specific error handling if needed. If an error is thrown in the loader, it will be caught and returned, wrapped in a `LiveCollectionError`. |
|
|
||
| ### Distributing your loader | ||
|
|
||
| Loaders can be defined in your site or as a separate npm package. If you want to share your loader with the community, you can [publish it to NPM with the `astro-component` and `astro-loader` keywords](/en/reference/publish-to-npm/#packagejson-data). |
There was a problem hiding this comment.
consistency:
| Loaders can be defined in your site or as a separate npm package. If you want to share your loader with the community, you can [publish it to NPM with the `astro-component` and `astro-loader` keywords](/en/reference/publish-to-npm/#packagejson-data). | |
| Loaders can be defined in your site or as a separate npm package. If you want to share your loader with the community, you can [publish it to npm with the `astro-component` and `astro-loader` keywords](/en/reference/publish-to-npm/#packagejson-data). |
| You can [create a collection](#defining-collections) any time you have a group of related data or content that shares a common structure. | ||
|
|
||
| Much of the benefit of using collections comes from: | ||
| ### Live collection limitations |
There was a problem hiding this comment.
This is currently nested in "Generating Routes from Content", is this intentional? This doesn't sound related to me. Same for "Differences from build-time collections".
Maybe both could make more sense in "Types of collections"?
| ::: | ||
|
|
||
|
|
||
| ### Distributing your loader |
There was a problem hiding this comment.
This section is also true for build time content collections, so I think it seems a bit odd to have this heading in the ToC under live loaders.
|
Great comments everyone, and obviously hard to digest them in GitHub interface! Especially since some later comments propose alternate restructuring, I won't address every individual "this could maybe go here!" comment, and we'll try to work more high level first and make some decisions there! |
|
|
||
| ```ts title="src/content.config.ts" | ||
| import { defineLiveCollection } from 'astro:content'; | ||
| import { storeLoader } from '@mystore/astro-loader'; |
There was a problem hiding this comment.
| import { storeLoader } from '@mystore/astro-loader'; | |
| import { storeLoader } from '@example/astro-loader'; |
Probably safer
| **Type:** <code>() => Promise<Array<\{ id: string, [key: string]: any }> | Record<string, Record<string, any>>> | <a href="/en/reference/content-loader-reference/#object-loader-api">Loader</a></code> | ||
| <Since v="5.0.0" /> | ||
| </p> | ||
|
|
||
| A `loader` is either an object or a function that allows you to load data from any source, local or remote, into a live content collections. | ||
|
|
||
| [See the `Content Collection` guide](/en/guides/content-collections/#creating-a-live-loader) for example usage. |
There was a problem hiding this comment.
This is a LiveLoader, not a Loader. It is never a function.
|
|
||
| `getLiveCollection()` is a function that retrieves a list of live content collection entries by collection name. | ||
|
|
||
| It returns all items in the collection by default, and accepts an optional `filter` function to narrow by entry properties. This allows you to query for only some items in a collection based on `id` or frontmatter values via the `data` object. |
There was a problem hiding this comment.
This isn't how live filters work. They're objects that are passed to the loader, which can use them as they want. See the experimental flag docs for some info. lmk if that's unclear
| const draftBlogPosts = await getLiveCollection('blog', ({ data }) => { | ||
| return data.draft === true; | ||
| }); |
There was a problem hiding this comment.
| const draftBlogPosts = await getLiveCollection('blog', ({ data }) => { | |
| return data.draft === true; | |
| }); | |
| const draftBlogPosts = await getLiveCollection('blog', { draft: true }); |
This does need explanation though. This filter format is entirely dependent on the loader.
| <Since v="5.0.0" /> | ||
| </p> | ||
|
|
||
| `getLiveEntry()` is a function that retrieves a single live collection entry by collection name and the entry `id`. `getLiveEntry()` can also be used to get referenced entries to access the `data` or `body` properties: |
There was a problem hiding this comment.
It accepts either a string id or a LiveLoaderEntryFilterType
Co-authored-by: Armand Philippot <[email protected]> Co-authored-by: Matt Kane <[email protected]>
|
Thanks @ascorbic !
I believe @ArmandPhilippot is on this, as a later task as I initially needed placeholders so I could link from the guide to reference items. Thank you for some direct quick fixes and reminders of where/what to look for! I committed the simple updates, and we'll go through it thoroughly! |
|
Yes, I will take a look at this. Depending on the number of changes, maybe I'll create another PR targeting this one to make the review easier. |
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.
Related issues & labels (optional)
For Astro version:
6.0. See astro PR #14550.