responsive images stable

[sarah11918]

Description (required)

Un-experimentalizes responsive images!

Moves the responsive image docs (properties, guide, reference, explanations) to the proper locations throughout the stable docs.

In particular:

• the component properties are moved to the astro:assets module page
• the configuration reference properties are no longer named using experimental
• the Images guide is updated to describe how the image components (and with configuration, images written with Markdown image syntax) behave when given responsive image properties
• deletes the existing experimental reference page
• adds image.responsiveStyles content from Add note on disabling default styles #11787 and feat: unflag responsive images astro#13917 (renamed from image.defaultStyles, defaults to false)
• adds priority option from feat: unflag responsive images astro#13917
• add a redirect from the experimental flag page
• Lunaria command

Additionally, with the addition of new image content, the Image Guide itself has been slightly reorganized and lightly edited with some overall improvements:

• colocating the "Images in X filetype" sections, since the available image options depend firstly on the type of file in which you want to add an image
• adding a new **Options:** list at the start of each of these sections so that at a glance, it is easy to tell which image methods are available in that file type
• creating a new <h2> to group all the "components" (<Image />, <Picture />, SVGs as components, creating a custom component (e.g. <BlogPostImage /> ) for easy reuse of images that share default settings), and removing this content from within the "Images in .astro files" section
  • Note: Originally, this grouping was to emphasize that these are Astro components, for use within .astro files. This draft instead optimizes for quickly identifying your image options based on the file type, but no longer provides all that content within that section. This allows readers to quickly see and compare how different file types work, and find the details later on the page in a dedicated section for components.
• Updating some section headings:
  • the Image and Picture headings were too long and trying to convey too much information in the section heading
  • in fact, the Picture section heading was now "incorrect" as it was previously described as "for producing responsive images" but now we have a responsive image feature that applies to both image and picture components
  • "Setting default values" was originally worded based on having received questions about whether defaults can be set for the components. Previously, the answer was now. Now, it's "no, except for configured responsive images." Now, the section heading focuses on the solution presented: creating custom components when you want/need consistent, reusable image attributes and styles. This also is in keeping with the section now being focused on "components"
• improvements and bug fixes

Related issues & labels (optional)

• Closes #
• Suggested label:

For Astro version: 5.10. See astro PR #13917. // will fill in when known

[netlify]

✅ Deploy Preview for astro-docs-2 ready!

Name	Link
🔨 Latest commit	6c0096e
🔍 Latest deploy log	https://app.netlify.com/projects/astro-docs-2/deploys/6851d24661599900085bafc3
😎 Deploy Preview	https://deploy-preview-11741--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 project 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.
en/reference/configuration-reference.mdx	Source changed, localizations will be marked as outdated.
en/reference/experimental-flags/responsive-images.mdx	Source removed, will stop being tracked.
en/reference/modules/astro-assets.mdx	Source changed, localizations will be marked as outdated.
fr/reference/experimental-flags/responsive-images.mdx	Localization removed, will be marked as missing. 🔄️
ko/reference/experimental-flags/responsive-images.mdx	Localization removed, will be marked as missing. 🔄️
zh-cn/reference/experimental-flags/responsive-images.mdx	Localization removed, will be marked as missing. 🔄️

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.

[ascorbic]

• add a redirect from the experimental flag page

[sarah11918]

add a redirect from the experimental flag page

Updated the main PR description with this checkbox!

[sarah11918]

@ascorbic I've left two suggestions here for handling image.responsiveStyles being true by default.

Specifically, the focus isn't on overriding the defaults anymore, but rather making sure it's clear people should opt in, and when they should avoid enabling it. Also a generic Tailwind 4 section is probably more helpful now (Yes, you can use responsive images with Tailwind 4! Here's how it works...) because the focus is not strictly about overriding.

Please feel free to edit as necessary!

[ascorbic]

Suggested change

	You can override the `object-fit` and `object-position` styles on a per-image basis by setting the `fit` and `position` props on the `<Image />` or `<Picture />` component.
	You can override the `object-fit` and `object-position` styles on a per-image basis by setting the `fit` and `position` props on the `<Image />` or `<Picture />` component. These props also change the way the images are cropped, so you should still use them, even if you apply your own styles.

I think this is improtant to note

[sarah11918]

(Addressed in the next comment)

[sarah11918]

Suggested change

	You can override the `object-fit` and `object-position` styles on a per-image basis by setting the `fit` and `position` props on the `<Image />` or `<Picture />` component.
	The `object-fit` and `object-position` styles determine how your images are cropped to fit their container and are essential for creating responsive images. You can override your default configuration or custom styles and provide your own styling for these properties on a per-image basis by setting the `fit` and `position` props on the `<Image />` or `<Picture />` component.

How about this, @ascorbic ? Is this "you must use them" strongly enough?

[sarah11918]

I think this PR has all the pieces now! (Will need a Lunaria commit message at merge)

Most recent commit adds priority reference entry. Now, it's just polishing!

[yanthomasdev]

Good job. Just a few small nits. PS: This PR shouldn't need a Lunaria tracking directive, since we are not doing anything special here.