feat: Add remote image caching behaviour docs

[oliverlynch]

Description (required)

Currently the behaviour of Astro's remote image cache is undocumented, which makes discovering the feature difficult and its behaviour unclear. This change adds an explanation of the asset cache, as well as some technical details on how it functions, which should be helpful for anyone configuring a remote image server for Astro.

Part of this change references the revalidation feature introduced in Astro PR #12426, however the rest documents existing functionality.

Related issues & labels (optional)

• Closes #
• Suggested label: add new content

For Astro version: 5.1. See astro PR #12426.

Not yet merged - milestone.

[netlify]

✅ Deploy Preview for astro-docs-2 ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	46fcf53
🔍 Latest deploy log	https://app.netlify.com/sites/astro-docs-2/deploys/6762d9f46250e800085bd42f
😎 Deploy Preview	https://deploy-preview-10377--astro-docs-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[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/guides/images.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.

[astrobot-houston]

Hello! Thank you for opening your first PR to Astro’s Docs! 🎉

Here’s what will happen next:

1. Our GitHub bots will run to check your changes.
   If they spot any broken links you will see some error messages on this PR.
   Don’t hesitate to ask any questions if you’re not sure what these mean!

2. In a few minutes, you’ll be able to see a preview of your changes on Netlify 🥳.

3. One or more of our maintainers will take a look and may ask you to make changes.
   We try to be responsive, but don’t worry if this takes a few days.

[sarah11918]

Thank you for submitting this extra content! I will ask @Princesseuh and/or @ascorbic to verify the technical content is what they'd like to appear in documentation. Once confirmed that this is the information they're comfortable documenting, then I'll edit for docs! This might mean moving the content to a different section, as this at first glance seems more suited to the section on remote authorization, and not in "where you can store your images."

But first, just want to make sure this is the technical information we intend to document!

[ascorbic]

This looks technically correct (which is the best kind of correct)

[Princesseuh]

Might be interesting to note that local images are also cached.

[sarah11918]

@Princesseuh Do you think maybe an entire section on Image Caching would make sense? (not strictly contained in a section about remote images?)

[Princesseuh]

I would say so! But it might be confusing for some users, since it's a bit more advanced than the rest and it's not something you interact with directly

[Princesseuh]

It might be interesting to mention where the images are cached, sometimes users want to know what to need to keep between builds for caching (here you can link to cacheDir in the config)

[oliverlynch]

I've moved the new documentation to its own section "Asset Caching", and mentioned how local images are also cached.

I added a mention of cacheDir in the body text instead of just the readmore link -
Is it okay to write the default cacheDir value here, or should I avoid repeating it and have people click through to the configuration reference?

I also expanded on revalidation, explaining that the remote server requires support for the If-Modified-Since and If-None-Match headers for revalidation to work. While this is a bit technical, if someone is having difficulty getting revalidation working it is probably best for this to be clearly documented.

[sarah11918]

Looks fantastic, @oliverlynch ! I really appreciate the great docs here, and the going above and beyond to document more than just your feature! 💜

Had some small suggestions for your consideration, and can't wait to get this in with the next minor release! 🥳

[oliverlynch]

Thanks @sarah11918 for the suggestions, I've committed them as-is.

[sarah11918]

Fantastic @oliverlynch ! Welcome to Team Docs! 🥳