diff --git a/src/content/docs/en/guides/images.mdx b/src/content/docs/en/guides/images.mdx index 9cb5972fd4039..a2208574c0c21 100644 --- a/src/content/docs/en/guides/images.mdx +++ b/src/content/docs/en/guides/images.mdx @@ -13,7 +13,7 @@ Astro provides several ways for you to use images on your site, whether they are ### `src/` vs `public/` -We recommend that local images are kept in `src/` when possible so that Astro can transform, optimize and bundle them. Files in the `/public` directory are always served or copied into the build folder as-is, with no processing. +We recommend that local images are kept in `src/` when possible so that Astro can transform, optimize and bundle them. Files in the `/public` directory are always served or copied into the build folder as-is, with no processing. Your local images stored in `src/` can be used by all files in your project: `.astro`, `.md`, `.mdx`, `.mdoc`, and other UI frameworks. Images can be stored in any folder, including alongside your content. @@ -21,7 +21,7 @@ Store your images in the `public/` folder if you want to avoid any processing or ### Remote images -You can also choose to store your images remotely, in a content management system (CMS) or digital asset management (DAM) platform. +You can also choose to store your images remotely, in a content management system (CMS) or digital asset management (DAM) platform. For extra protection when dealing with external sources, remote images will only be processed from [authorized image sources](#authorizing-remote-images) specified in your configuration. However, any remote images can be displayed. @@ -32,7 +32,7 @@ Astro can fetch your data remotely using APIs or display images from their full In `.astro` files, local images must be imported into the file in order to be used. Remote and `public/` images do not require importing. -Import and use Astro's built-in `` component for optimized images using `astro:assets`. Alternatively, Astro syntax supports writing an HTML `` tag directly, which skips image processing. +Import and use Astro's built-in `` component for optimized images using `astro:assets`. Alternatively, Astro syntax supports writing an HTML `` tag directly, which skips image processing. ```astro title="src/pages/blog/MyImages.astro" --- @@ -110,7 +110,7 @@ The format of the `src` value of your image file depends on where your image fil --- import { Image } from 'astro:assets'; --- - descriptive text`, ``, or `getImage()`. +The image will be imported and transformed into metadata, allowing you to pass it as a `src` to ``, ``, or `getImage()`. The example below shows a blog index page that renders the cover photo and title of each blog post from the schema above: @@ -514,6 +514,14 @@ export default defineConfig({ }); ``` +:::note +When using a [strict package manager](https://pnpm.io/pnpm-vs-npm#npms-flat-tree) like `pnpm`, you may need to manually install Sharp into your project even though it is an Astro dependency: + +```bash +pnpm install sharp +``` +::: + ## Community Integrations There are several third-party [community image integrations](https://astro.build/integrations?search=images) for optimizing and working with images in your Astro project. @@ -526,7 +534,7 @@ There are several third-party [community image integrations](https://astro.build These and other accompanying changes to using images in Astro may cause some breaking changes when you upgrade your Astro project from an earlier version. -Please follow the instructions below as appropriate to upgrade an Astro v2.x project to v3.0. +Please follow the instructions below as appropriate to upgrade an Astro v2.x project to v3.0. ### Upgrade from `experimental.assets` diff --git a/src/content/docs/en/guides/upgrade-to/v3.mdx b/src/content/docs/en/guides/upgrade-to/v3.mdx index 18bf53dcfce00..ecc65eb72539f 100644 --- a/src/content/docs/en/guides/upgrade-to/v3.mdx +++ b/src/content/docs/en/guides/upgrade-to/v3.mdx @@ -20,7 +20,7 @@ Update your project's version of Astro to the latest version using your package ```shell # Upgrade to Astro v3.x npm install astro@latest - + # Example: upgrade React and Tailwind integrations npm install @astrojs/react@latest @astrojs/tailwind@latest ``` @@ -38,7 +38,7 @@ Update your project's version of Astro to the latest version using your package ```shell # Upgrade to Astro v3.x yarn add astro@latest - + # Example: upgrade React and Tailwind integrations yarn add @astrojs/react@latest @astrojs/tailwind@latest ``` @@ -84,7 +84,7 @@ See [the changelog](https://github.com/withastro/astro/blob/main/packages/astro/ ### Removed: Support for Node 16 -Node 16 is scheduled to reach its End of Life in September 2023. +Node 16 is scheduled to reach its End of Life in September 2023. Astro v3.0 drops Node 16 support entirely so that all Astro users can take advantage of Node's more modern features. @@ -100,7 +100,7 @@ Astro v3.0 drops Node 16 support entirely so that all Astro users can take advan -2. Check your [deployment environment's](/en/guides/deploy/) own documentation to verify that they support Node 18. +2. Check your [deployment environment's](/en/guides/deploy/) own documentation to verify that they support Node 18. You can specify Node `18.14.1` for your Astro project either in a dashboard configuration setting or a `.nvmrc` file. @@ -163,7 +163,7 @@ import Markdown from '@astrojs/markdown-component'; --- ``` -To continue using a similar `` component in your code, consider using [community integrations](https://astro.build/integrations/) such as [`astro-remote`](https://github.com/natemoo-re/astro-remote). Be sure to update your `` component imports and attributes as necessary, according to the integration's own documentation. +To continue using a similar `` component in your code, consider using [community integrations](https://astro.build/integrations/) such as [`astro-remote`](https://github.com/natemoo-re/astro-remote). Be sure to update your `` component imports and attributes as necessary, according to the integration's own documentation. Otherwise, delete all references to importing Astro's `` component and the component itself in your `.astro` files. You will need to rewrite your content as HTML directly or [import Markdown](/en/guides/markdown-content/#importing-markdown) from a `.md` file. @@ -203,7 +203,7 @@ If you are using the deprecated `image()` from `astro:content`, remove it as thi ```ts title="astro.config.mjs" del={1} ins={2} "({ image })" import { defineCollection, z, image } from "astro:content"; import { defineCollection, z } from "astro:content"; - + defineCollection({ schema: ({ image }) => z.object({ @@ -243,7 +243,7 @@ Replace any `Set` elements passed to the `class:list` directive with a plain `Ar 'a', 'b', new Set(['c', 'd']) - ['c', 'd'] + ['c', 'd'] ]} /> ``` @@ -485,7 +485,7 @@ Astro v3.0 introduces a new, default value: `"attribute"`. By default, styles ar #### What should I do? -To retain your project's current [style scoping](/en/guides/styling/#scoped-styles), update the configuration file to the previous default value: +To retain your project's current [style scoping](/en/guides/styling/#scoped-styles), update the configuration file to the previous default value: ```js title="astro.config.mjs" ins={4} @@ -524,7 +524,15 @@ Astro v3.0 now includes Sharp as the default image processing service and instea #### What should I do? -If you would prefer to continue to use Squoosh to transform your images, update your config with the following: +:::note +When using a [strict package manager](https://pnpm.io/pnpm-vs-npm#npms-flat-tree) like `pnpm`, you may need to manually install Sharp into your project even though it is an Astro dependency: + +```bash +pnpm install sharp +``` +::: + +If you would prefer to continue to use Squoosh to transform your images, update your config with the following: ```ts title="astro.config.mjs" ins={4-6} import { defineConfig, squooshImageService } from "astro/config"; @@ -675,4 +683,3 @@ Know a good resource for Astro v3.0? [Edit this page](https://github.com/withast ## Known Issues There are currently no known issues. -