Docs: Image README clarifications (#6290)

* hosted on other domains -> accessed by url

* these work like remote images

* including images in public

* Update packages/integrations/image/README.md

Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>

* Update packages/integrations/image/README.md

Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>

* Update packages/integrations/image/README.md

Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>

* Update packages/integrations/image/README.md

Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>

* Update packages/integrations/image/README.md

Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>

* Update packages/integrations/image/README.md

Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>

* reorder remote first

* Update packages/integrations/image/README.md

Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>

* Update packages/integrations/image/README.md

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

---------

Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>
Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

1 files changed, 16 insertions, 12 deletions

diff --git a/packages/integrations/image/README.md b/packages/integrations/image/README.md
index 0c04cb541..ffd75fd3e 100644
--- a/packages/integrations/image/README.md
+++ b/packages/integrations/image/README.md
@@ -133,7 +133,7 @@ If the image is merely decorative (i.e. doesn’t contribute to the understandin
 
 ### `<Image />`
 
-The built-in `<Image />` component is used to create an optimized `<img />` for both remote images hosted on other domains as well as local images imported from your project's `src` directory.
+The built-in `<Image />` component is used to create an optimized `<img />` for both remote images accessed by URL as well as local images imported from your project's `src/` directory.
 
 In addition to the component-specific properties, any valid HTML attribute for the `<img />` included in the `<Image />` component will be included in the built `<img />`.
 
@@ -147,11 +147,12 @@ In addition to the component-specific properties, any valid HTML attribute for t
 
 Source for the original image file.
 
-For images located in your project's `src`: use the file path relative to the `src` directory. (e.g. `src="../assets/source-pic.png"`)
+For remote images, provide the full URL. (e.g. `src="https://astro.build/assets/blog/astro-1-release-update.avif"`)
 
-For images located in your `public` directory: use the URL path relative to the `public` directory. (e.g. `src="/images/public-image.jpg"`)
+For images located in your project's `src/`: use the file path relative to the `src/` directory. (e.g. `src="../assets/source-pic.png"`)
 
-For remote images, provide the full URL. (e.g. `src="https://astro.build/assets/blog/astro-1-release-update.avif"`)
+
+For images located in your `public/` directory: use the URL path relative to the `public/` directory. (e.g. `src="/images/public-image.jpg"`). These work like remote images.
 
 #### alt
 
@@ -201,7 +202,7 @@ The desired width of the output image. Combine with `height` to crop the image t
 
 Dimensions are optional for local images, the original image size will be used if not provided.
 
-For remote images, the integration needs to be able to calculate dimensions for the optimized image. This can be done by providing `width` and `height` or by providing one dimension and an `aspectRatio`.
+For remote images, including images in `public/`, the integration needs to be able to calculate dimensions for the optimized image. This can be done by providing `width` and `height` or by providing one dimension and an `aspectRatio`.
 
 #### height
 
@@ -215,7 +216,7 @@ The desired height of the output image. Combine with `width` to crop the image t
 
 Dimensions are optional for local images, the original image size will be used if not provided.
 
-For remote images, the integration needs to be able to calculate dimensions for the optimized image. This can be done by providing `width` and `height` or by providing one dimension and an `aspectRatio`.
+For remote images, including images in `public/`, the integration needs to be able to calculate dimensions for the optimized image. This can be done by providing `width` and `height` or by providing one dimension and an `aspectRatio`.
 
 #### aspectRatio
 
@@ -231,6 +232,8 @@ A `string` can be provided in the form of `{width}:{height}`, ex: `16:9` or `3:4
 
 A `number` can also be provided, useful when the aspect ratio is calculated at build time. This can be an inline number such as `1.777` or inlined as a JSX expression like `aspectRatio={16/9}`.
 
+For remote images, including images in `public/`, the integration needs to be able to calculate dimensions for the optimized image. This can be done by providing `width` and `height` or by providing one dimension and an `aspectRatio`.
+
 #### background
 
 <p>
@@ -279,7 +282,7 @@ Position of the crop when fit is `cover` or `contain`.
 
 ### `<Picture />`
 
-The built-in `<Picture />` component is used to create an optimized `<picture />` for both remote images hosted on other domains as well as local images imported from your project's `src` directory.
+The built-in `<Picture />` component is used to create an optimized `<picture />` for both remote images accessed by URL as well as local images imported from your project's `src/` directory.
 
 In addition to the component-specific properties, any valid HTML attribute for the `<img />` included in the `<Picture />` component will be included in the built `<img />`.
 
@@ -293,11 +296,12 @@ In addition to the component-specific properties, any valid HTML attribute for t
 
 Source for the original image file.
 
-For images located in your project's `src`: use the file path relative to the `src` directory. (e.g. `src="../assets/source-pic.png"`)
+For remote images, provide the full URL. (e.g. `src="https://astro.build/assets/blog/astro-1-release-update.avif"`)
 
-For images located in your `public` directory: use the URL path relative to the `public` directory. (e.g. `src="/images/public-image.jpg"`)
+For images located in your project's `src/`: use the file path relative to the `src/` directory. (e.g. `src="../assets/source-pic.png"`)
 
-For remote images, provide the full URL. (e.g. `src="https://astro.build/assets/blog/astro-1-release-update.avif"`)
+
+For images located in your `public/` directory: use the URL path relative to the `public/` directory. (e.g. `src="/images/public-image.jpg"`). These work like remote images.
 
 #### alt
 
@@ -352,7 +356,7 @@ A `string` can be provided in the form of `{width}:{height}`, ex: `16:9` or `3:4
 
 A `number` can also be provided, useful when the aspect ratio is calculated at build time. This can be an inline number such as `1.777` or inlined as a JSX expression like `aspectRatio={16/9}`.
 
-For remote images only, `aspectRatio` is required to ensure the correct `height` can be calculated at build time.
+For remote images, including images in `public/`, `aspectRatio` is required to ensure the correct `height` can be calculated at build time.
 
 #### formats
 
@@ -364,7 +368,7 @@ For remote images only, `aspectRatio` is required to ensure the correct `height`
 
 The output formats to be used in the optimized image. If not provided, `webp` and `avif` will be used in addition to the original image format.
 
-For remote images, the original image format is unknown. If not provided, only `webp` and `avif` will be used.
+For remote images, including images in `public/`, the original image format is unknown. If not provided, only `webp` and `avif` will be used.
 
 #### background