Document glob() loader deferRender option

[matthewp]

Documents the new deferRender option for the glob() content loader.

Implementation: withastro/astro#17302

[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.

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.

[github-actions]

Preview deployment

✅ Deployment complete!

• Latest commit: d29a2d4
• Preview: https://docs-glob-defer-render.previews.docs.astro.build
• Workflow run: View logs

[yanthomasdev]

Thanks @matthewp, I have a suggestion and a comment for you!

[yanthomasdev]

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.

[yanthomasdev]

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!

[ArmandPhilippot]

Overall this looks good but Yan pointed out two things that seem a little unclear to me: is MDX affected? And how this works when retainBody is set? Does this affects existing docs?

I also made a suggestion to lighten the sentence around "render" a bit. And, I think the last sentence should be one of the first thing we say (ie. "oh, I'm only using data entries, I don't need to read the whole description" vs "is JSON a renderable entry? I should read everything!").

[ArmandPhilippot]

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)

[ArmandPhilippot]

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.