Skip to content

Document glob() loader deferRender option #14208

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
matthewp wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Document glob() loader deferRender option #14208

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 29 additions & 1 deletion src/content/docs/en/reference/content-loader-reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ For simple data fetching, you can also [define a loader as an async function](#d

The `glob()` loader creates entries from directories of files from anywhere on the filesystem. The supported file types are Markdown, MDX, Markdoc, JSON, YAML, and TOML files.

This loader accepts an object with the following properties: `pattern`, `base` (optional), `generateId` (optional), and `retainBody` (optional).
This loader accepts an object with the following properties: `pattern`, `base` (optional), `generateId` (optional), `retainBody` (optional), and `deferRender` (optional).

```ts title="src/content.config.ts"
import { defineCollection } from 'astro:content';
Expand Down Expand Up @@ -124,6 +124,34 @@ For Markdown files, the rendered body will still be available in the [`entry.ren

For MDX collections, this will dramatically reduce the size of the collection, as there will no longer be any body retained in the store.

#### `deferRender`

<p>

**Type:** `boolean`<br />
**Default:** `false`
<Since v="7.1.0" />
</p>

Whether to defer rendering of renderable entries (such as Markdown) until they are rendered in a page, instead of rendering them eagerly during content sync.

@yanthomasdev yanthomasdev Jul 8, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would mention MDX up top so its clear from the get go it benefits both.

Suggested change
Whether to defer rendering of renderable entries (such as Markdown) until they are rendered in a page, instead of rendering them eagerly during content sync.
Whether to defer rendering of renderable entries (such as Markdown and MDX) until they are rendered in a page, instead of rendering them eagerly during content sync.

@ArmandPhilippot ArmandPhilippot Jul 8, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I included Yan suggestion (mentioning MDX) but something is still not clear to me. Does this affects MDX ("using the same on-demand rendering path that .mdx files already use")? And what about Markdoc?

Nonetheless, I think the last sentence should be moved here as it clearly states what is affected and what's not. And I think this also helps a bit with "rendering of renderable... rendered... rendering" which sounds heavy to me in a single sentence.

Suggested change
Whether to defer rendering of renderable entries (such as Markdown) until they are rendered in a page, instead of rendering them eagerly during content sync.
Whether to defer rendering entries until they are rendered in a page. When `false` (the default), their rendering occurs eagerly during content sync. This option only applies to renderable entries (e.g., Markdown, MDX). Data entries (e.g., JSON, YAML) are unaffected.

It might not be perfect... as a non native speaker, I would have used "displayed" instead of "rendered" for the second occurrence in the first sentence. But, maybe "rendered" carry an important nuance.

And whether we use e.g. or such as, if those are examples, we don't have to be exhaustive (ie. Markdoc and TOML are probably less common, it's okay to not mention them)


By default, the `glob()` loader renders each Markdown entry during sync and stores the resulting HTML in the data store. This allows the rendered content to be cached and reused across builds. However, for large collections whose rendered output is much larger than the source, storing all this rendered HTML in memory at once can cause your build to run out of memory.

@yanthomasdev yanthomasdev Jul 8, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the glob() loader renders each Markdown entry during sync and stores the resulting HTML in the data store.

would this mean this has some interaction with the retainBody option? Like, is setting one false/true change how the other works? I am not super familiar with those options, so I don't know for sure, but if there's any sort of interaction or weird combination of both you should avoid maybe we can add some information about it here!


When `deferRender` is `true`, rendering is instead deferred until each entry is actually rendered in a page, using the same on-demand rendering path that `.mdx` files already use. This keeps memory usage bounded during `astro build` at the cost of the rendered HTML no longer being cached in the data store.

```ts title="src/content.config.ts"
const docs = defineCollection({
/* Defer rendering of a large Markdown collection to avoid running out of memory during the build. */
loader: glob({
pattern: '**/*.md',
base: './src/data/docs',
deferRender: true,
}),
});
```

This option only affects renderable entries. Data entries (such as JSON, YAML, and TOML files) are unaffected.
Comment on lines +152 to +153

@ArmandPhilippot ArmandPhilippot Jul 8, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And if you agree with my first suggestion, this means we can delete this:

Suggested change
This option only affects renderable entries. Data entries (such as JSON, YAML, and TOML files) are unaffected.


### `file()` loader

<p>
Expand Down
Loading