feat(reference): Update astro:assets reference for new Astro 6.0 behavior (#12639)

Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com>
Co-authored-by: Florian Lefebvre <contact@florian-lefebvre.dev>
Co-authored-by: Armand Philippot <git@armand.philippot.eu>

Author: 4 people

src/content/docs/en/guides/images.mdx

@@ -51,7 +51,7 @@ All native HTML tags, including `<img>` and `<svg>`, are also available in `.ast
 For all images in `.astro` files, **the value of the image `src` attribute is determined by the location of your image file**:
 
 - A local image from your project `src/` folder uses an import from the file's relative path.
-  
+
   The image and picture components use the named import directly (e.g. `src={rocket}`), while the `<img>` tag uses the `src` object property of the import (e.g. `src={rocket.src}`).
 
 - Remote and `public/` images use a URL path.
@@ -321,7 +321,7 @@ import myImage from '../assets/my_image.png'; // Image is 1600x900
 
 Responsive images are images that adjust to improve performance across different devices. These images can resize to fit their container, and can be served in different sizes depending on your visitor's screen size and resolution.
 
-With [responsive image properties](/en/reference/modules/astro-assets/#responsive-image-properties) applied to the `<Image />` or `<Picture />` components, Astro will automatically generate the required `srcset` and `sizes` values for your images, and apply the necessary [styles to ensure they resize correctly](#responsive-image-styles). 
+With the [layout property](/en/reference/modules/astro-assets/#layout) applied to the `<Image />` or `<Picture />` components, Astro will automatically generate the required `srcset` and `sizes` values for your images, and apply the necessary [styles to ensure they resize correctly](#responsive-image-styles).
 
 When this responsive behavior is [configured globally with `image.layout`](/en/reference/configuration-reference/#imagelayout), it will apply to all image components and also to any local and remote images using [the Markdown `![]()` syntax](/en/guides/images/#images-in-markdown-files).
 
@@ -396,7 +396,7 @@ The global styles applied by Astro will depend on the layout type, and are desig
 
 The styles use the [`:where()` pseudo-class](https://developer.mozilla.org/en-US/docs/Web/CSS/:where), which has a [specificity](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_cascade/Specificity) of 0, meaning that it is easy to override with your own styles. Any CSS selector will have a higher specificity than `:where()`, so you can easily override the styles by adding your own styles to target the image.
 
-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.
 
 #### Responsive images with Tailwind 4
 

src/content/docs/en/guides/upgrade-to/v6.mdx

@@ -375,7 +375,7 @@ You may also wish to consider using glob packages from NPM, such as [`fast-glob`
 
 In Astro 5.0, accessing `routes` on the `astro:build:done` hook was deprecated.
 
-Astro 6.0 removes the `routes` array passed to this hook entirely. Instead, the `astro:routes:resolved` hook should be used. 
+Astro 6.0 removes the `routes` array passed to this hook entirely. Instead, the `astro:routes:resolved` hook should be used.
 
 #### What should I do?
 
@@ -715,6 +715,39 @@ If you need more control over environment variables in Astro, we recommend you u
 
 <ReadMore>Learn more about [environment variables](/en/guides/environment-variables/) in Astro, including `astro:env`.</ReadMore>
 
+### Changed: Cropping by default in default image service
+
+<SourcePR number="14629" title="feat(assets): Always allow cropping and never upscale" />
+
+In Astro 5.0, the default image service would only apply cropping when the `fit` option was provided.
+
+Astro 6.0 applies cropping by default without requiring setting the `fit` option.
+
+#### What should I do?
+
+No changes are needed to your existing cropped images as the `fit` property is still valid. However, if you were previously setting `fit` to `contain` (its default value) in order to crop your images, you may now remove this option and still achieve the same cropping behavior by specifying `width` and `height` alone:
+
+```ts title="src/components/MyImage.astro" del={5} ins={6}
+---
+import { Image } from 'astro:assets';
+import myImage from '../assets/photo.jpg';
+---
+<Image src={myImage} width={400} height={300} fit="contain" />
+<Image src={myImage} width={400} height={300} />
+```
+
+### Changed: Never upscale images in default image service
+
+<SourcePR number="14629" title="feat(assets): Always allow cropping and never upscale" />
+
+In Astro 5.0, the default image service would upscale images when the requested dimensions were larger than the source image.
+
+Astro 6.0 removes this behavior: the default image service never upscales images.
+
+#### What should I do?
+
+Review your images and update dimensions as needed. If you do need to upscale images, you may consider upscaling the images manually or using a custom image service that supports upscaling.
+
 ### Changed: Markdown heading ID generation
 
 <SourcePR number="14494" title="feat!: stabilize experimental.headingIdCompat"/>
@@ -792,7 +825,7 @@ If you want to keep the old ID generation for backward compatibility reasons, yo
    ```
    </Fragment>
    </PackageManagerTabs>
-   
+
 2. Create a custom rehype plugin that will generate headings IDs like Astro v5:
 
    ```js title="plugins/rehype-slug.mjs"
@@ -820,13 +853,13 @@ If you want to keep the old ID generation for backward compatibility reasons, yo
      };
    }
    ```
-   
+
 3. Add the custom plugin to your Markdown configuration in `astro.config.mjs`:
 
    ```js title="astro.config.mjs" ins={2} ins="rehypeSlug"
    import { defineConfig } from 'astro/config';
    import { rehypeSlug } from './plugins/rehype-slug';
-   
+
    export default defineConfig({
      markdown: {
        rehypePlugins: [rehypeSlug],