diff --git a/src/content/docs/en/reference/content-loader-reference.mdx b/src/content/docs/en/reference/content-loader-reference.mdx index 8d28dece41dba..f2435970a5601 100644 --- a/src/content/docs/en/reference/content-loader-reference.mdx +++ b/src/content/docs/en/reference/content-loader-reference.mdx @@ -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'; @@ -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` + +

+ +**Type:** `boolean`
+**Default:** `false` + +

+ +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. + +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. + +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. + ### `file()` loader