From b90bc5cab66e73385f79fb36bae279d5a1ddd3a9 Mon Sep 17 00:00:00 2001 From: Princesseuh <3019731+Princesseuh@users.noreply.github.com> Date: Mon, 12 Jan 2026 18:55:33 +0100 Subject: [PATCH 1/8] feat: svg rasterization upgrade guide --- src/content/docs/en/guides/upgrade-to/v6.mdx | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index fee6cbdc08e10..123409e863aa1 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -164,6 +164,24 @@ import { z } from 'astro/zod'; See more about [the `astro/zod` module](/en/reference/modules/astro-zod/). +### SVG rasterization + +Astro's default Sharp image service now supports converting SVG files to raster files (such as PNG, WebP, etc.). Note that this is subject to many limitations, for instance SVGs with embedded fonts might not be converted properly. + +#### What should I do? + +If you were previously relying on code like this to automatically skip SVGs: + +```astro +example +``` + +You'll now need to check the format beforehand to avoid converting SVGs to raster images: + +```astro +example +``` + ### Official Astro integrations All of [Astro's official server adapters](/en/guides/on-demand-rendering/#server-adapters) have also updated to a new major version to accompany the upgrade to Vite v7.0 with Vite's Environment API as the development server and production bundler. From 498eeba692b955b12644628cbf66559b166aa8ee Mon Sep 17 00:00:00 2001 From: Erika <3019731+Princesseuh@users.noreply.github.com> Date: Tue, 13 Jan 2026 17:52:16 +0100 Subject: [PATCH 2/8] Update src/content/docs/en/guides/upgrade-to/v6.mdx Co-authored-by: Chris Swithinbank --- src/content/docs/en/guides/upgrade-to/v6.mdx | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index 123409e863aa1..77dd670bf50fa 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -178,8 +178,12 @@ If you were previously relying on code like this to automatically skip SVGs: You'll now need to check the format beforehand to avoid converting SVGs to raster images: -```astro -example +```astro {3} +example ``` ### Official Astro integrations From e49868ed26a61a13da14fa81e63d2fbca721634e Mon Sep 17 00:00:00 2001 From: Erika <3019731+Princesseuh@users.noreply.github.com> Date: Mon, 19 Jan 2026 16:55:02 +0100 Subject: [PATCH 3/8] Update src/content/docs/en/guides/upgrade-to/v6.mdx Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> --- src/content/docs/en/guides/upgrade-to/v6.mdx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index 77dd670bf50fa..f50270d43e24b 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -164,9 +164,11 @@ import { z } from 'astro/zod'; See more about [the `astro/zod` module](/en/reference/modules/astro-zod/). -### SVG rasterization +### Changed: SVG rasterization -Astro's default Sharp image service now supports converting SVG files to raster files (such as PNG, WebP, etc.). Note that this is subject to many limitations, for instance SVGs with embedded fonts might not be converted properly. +In Astro v5.x, Astro's default Sharp image service was unable to convert SVG files to raster files (e.g. PNG, WebP). This meant that the `` component would ignore any value set for `format` when optimizing and transforming SVG files. + +Astro 6.0 now supports SVG rasterization. This is subject to many limitations, for instance SVGs with embedded fonts might not be converted properly. However, when the `format` property is set, the image service will now attempt to convert SVG images. #### What should I do? From 3c239ffd53cb248633a3de751046b68fe4cbab0f Mon Sep 17 00:00:00 2001 From: Erika <3019731+Princesseuh@users.noreply.github.com> Date: Mon, 19 Jan 2026 16:55:19 +0100 Subject: [PATCH 4/8] Update src/content/docs/en/guides/upgrade-to/v6.mdx Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> --- src/content/docs/en/guides/upgrade-to/v6.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index f50270d43e24b..fd8d882a12ba1 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -172,7 +172,7 @@ Astro 6.0 now supports SVG rasterization. This is subject to many limitations, f #### What should I do? -If you were previously relying on code like this to automatically skip SVGs: +If you were previously relying the fact that the image service would automatically skip converting SVGs, you must now check for the format of your images beforehand to avoid converting SVGs to raster images: ```astro example From 03c46a32d81f87cae6a5841d6e1d82dce57c2017 Mon Sep 17 00:00:00 2001 From: Erika <3019731+Princesseuh@users.noreply.github.com> Date: Mon, 19 Jan 2026 16:55:34 +0100 Subject: [PATCH 5/8] Update src/content/docs/en/guides/upgrade-to/v6.mdx Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> --- src/content/docs/en/guides/upgrade-to/v6.mdx | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index fd8d882a12ba1..24c832fd8ade8 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -174,13 +174,9 @@ Astro 6.0 now supports SVG rasterization. This is subject to many limitations, f If you were previously relying the fact that the image service would automatically skip converting SVGs, you must now check for the format of your images beforehand to avoid converting SVGs to raster images: -```astro +```astro del={1} ins=(3-7} example -``` - -You'll now need to check the format beforehand to avoid converting SVGs to raster images: -```astro {3} ``` +Learn more about [the `format` image property](/en/reference/modules/astro-assets/#format) + ### Official Astro integrations All of [Astro's official server adapters](/en/guides/on-demand-rendering/#server-adapters) have also updated to a new major version to accompany the upgrade to Vite v7.0 with Vite's Environment API as the development server and production bundler. From e684a79617b605ef59f3c34d903a2b24c304b71b Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Tue, 20 Jan 2026 10:30:00 -0400 Subject: [PATCH 6/8] move to breaking changes section, add SourcePR component --- src/content/docs/en/guides/upgrade-to/v6.mdx | 48 ++++++++++---------- 1 file changed, 25 insertions(+), 23 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index 24c832fd8ade8..ab81ff207d598 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -164,28 +164,6 @@ import { z } from 'astro/zod'; See more about [the `astro/zod` module](/en/reference/modules/astro-zod/). -### Changed: SVG rasterization - -In Astro v5.x, Astro's default Sharp image service was unable to convert SVG files to raster files (e.g. PNG, WebP). This meant that the `` component would ignore any value set for `format` when optimizing and transforming SVG files. - -Astro 6.0 now supports SVG rasterization. This is subject to many limitations, for instance SVGs with embedded fonts might not be converted properly. However, when the `format` property is set, the image service will now attempt to convert SVG images. - -#### What should I do? - -If you were previously relying the fact that the image service would automatically skip converting SVGs, you must now check for the format of your images beforehand to avoid converting SVGs to raster images: - -```astro del={1} ins=(3-7} -example - -example -``` - -Learn more about [the `format` image property](/en/reference/modules/astro-assets/#format) - ### Official Astro integrations All of [Astro's official server adapters](/en/guides/on-demand-rendering/#server-adapters) have also updated to a new major version to accompany the upgrade to Vite v7.0 with Vite's Environment API as the development server and production bundler. @@ -1192,7 +1170,7 @@ import myImage from '../assets/photo.jpg'; -In Astro 5.0, the default image service would upscale images when the requested dimensions were larger than the source image. +In Astro 5.x, 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. @@ -1200,6 +1178,30 @@ Astro 6.0 removes this behavior: the default image service never upscales images 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: SVG rasterization + + + +In Astro v5.x, Astro's default Sharp image service was unable to convert SVG files to raster files (e.g. PNG, WebP). This meant that the `` component would ignore any value set for `format` when optimizing and transforming SVG files. + +Astro 6.0 now supports SVG rasterization. This is subject to many limitations, for instance SVGs with embedded fonts might not be converted properly. However, when the `format` property is set, the image service will now attempt to convert SVG images. + +#### What should I do? + +If you were previously relying the fact that the image service would automatically skip converting SVGs, you must now check for the format of your images beforehand to avoid converting SVGs to raster images: + +```astro del={1} ins=(3-7} +example + +example +``` + +Learn more about [the `format` image property](/en/reference/modules/astro-assets/#format) + ### Changed: Markdown heading ID generation From bf8d5ed5df974d8a5e6f1d26e6ffe6689a0ba17f Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Mon, 26 Jan 2026 09:15:33 -0400 Subject: [PATCH 7/8] add helpful link to SVG issues Co-authored-by: Julien Cayzac --- src/content/docs/en/guides/upgrade-to/v6.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index ab81ff207d598..760858c67d549 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -1184,7 +1184,7 @@ Review your images and update dimensions as needed. If you do need to upscale im In Astro v5.x, Astro's default Sharp image service was unable to convert SVG files to raster files (e.g. PNG, WebP). This meant that the `` component would ignore any value set for `format` when optimizing and transforming SVG files. -Astro 6.0 now supports SVG rasterization. This is subject to many limitations, for instance SVGs with embedded fonts might not be converted properly. However, when the `format` property is set, the image service will now attempt to convert SVG images. +Astro 6.0 now supports SVG rasterization. This is subject to [many limitations](https://github.com/lovell/sharp/issues?q=is%3Aissue%20state%3Aopen%20svg), for instance SVGs with embedded fonts might not be converted properly. However, when the `format` property is set, the image service will now attempt to convert SVG images. #### What should I do? From d83c904e00b1a95d0a66bd8dba1d9bf813ea361f Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Mon, 2 Feb 2026 15:54:22 -0400 Subject: [PATCH 8/8] Apply suggestions from Yan final boss code review Co-authored-by: Yan <61414485+yanthomasdev@users.noreply.github.com> --- src/content/docs/en/guides/upgrade-to/v6.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index 760858c67d549..9f0de51cecdc5 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -1184,11 +1184,11 @@ Review your images and update dimensions as needed. If you do need to upscale im In Astro v5.x, Astro's default Sharp image service was unable to convert SVG files to raster files (e.g. PNG, WebP). This meant that the `` component would ignore any value set for `format` when optimizing and transforming SVG files. -Astro 6.0 now supports SVG rasterization. This is subject to [many limitations](https://github.com/lovell/sharp/issues?q=is%3Aissue%20state%3Aopen%20svg), for instance SVGs with embedded fonts might not be converted properly. However, when the `format` property is set, the image service will now attempt to convert SVG images. +Astro 6.0 now supports SVG rasterization. This is subject to [many limitations](https://github.com/lovell/sharp/issues?q=is%3Aissue%20state%3Aopen%20svg), for instance, SVGs with embedded fonts might not be converted properly. However, when the `format` property is set, the image service will now attempt to convert SVG images. #### What should I do? -If you were previously relying the fact that the image service would automatically skip converting SVGs, you must now check for the format of your images beforehand to avoid converting SVGs to raster images: +If you were previously relying on the fact that the image service would automatically skip converting SVGs, you must now check the format of your images beforehand to avoid converting SVGs to raster images: ```astro del={1} ins=(3-7} example