feat: add experimetal svgo docs

astro.sidebar.ts

@@ -152,6 +152,7 @@ export const sidebar = [
 					'reference/experimental-flags/static-import-meta-env',
 					'reference/experimental-flags/chrome-devtools-workspace',
 					'reference/experimental-flags/fail-on-prerender-conflict',
+					'reference/experimental-flags/svg',
 				],
 			}),
 			'reference/legacy-flags',

src/content/docs/en/reference/experimental-flags/svg.mdx

@@ -0,0 +1,187 @@
+---
+title: Experimental SVG optimization
+sidebar:
+  label: SVG optimization
+i18nReady: true
+---
+
+import Since from '~/components/Since.astro'
+
+<p>
+
+**Type:** `object`<br />
+**Default:** `undefined`<br />
+<Since v="5.8.0" />
+</p>
+
+This experimental feature enables automatic optimization of SVG assets using [SVGO](https://svgo.dev/) during build time.
+
+When enabled, all imported SVG files will be optimized for smaller file sizes and better performance while maintaining visual quality. This can significantly reduce the size of your SVG assets by removing unnecessary metadata, comments, and redundant code.
+
+To enable this feature, add the experimental flag in your Astro config:
+
+```js title="astro.config.mjs" ins={4-8}
+import { defineConfig } from "astro/config"
+
+export default defineConfig({
+  experimental: {
+    svg: {
+      optimize: true
+    }
+  }
+})
+```
+
+## Configuration
+
+### `optimize`
+
+**Type:** `boolean`<br />
+**Default:** `true`
+
+Whether to enable SVG optimization using SVGO during build time.
+
+When enabled, all imported SVG files will be optimized for smaller file sizes and better performance while maintaining visual quality.
+
+```js title="astro.config.mjs"
+export default defineConfig({
+  experimental: {
+    svg: {
+      optimize: true
+    }
+  }
+})
+```
+
+### `svgoConfig`
+
+**Type:** `Config` (SVGO configuration object)<br />
+**Default:** `{}`
+
+Configuration object passed directly to SVGO for customizing SVG optimization.
+
+See [SVGO documentation](https://svgo.dev/docs/preset-default/) for available options and plugins.
+
+```js title="astro.config.mjs"
+export default defineConfig({
+  experimental: {
+    svg: {
+      optimize: true,
+      svgoConfig: {
+        plugins: [
+          'preset-default',
+          {
+            name: 'removeViewBox',
+            active: false
+          }
+        ]
+      }
+    }
+  }
+})
+```
+
+## Usage
+
+Once enabled, SVG optimization will automatically apply to all SVG files imported in your project:
+
+```astro title="src/pages/index.astro"
+---
+import Logo from '../assets/logo.svg';
+---
+
+<Logo />
+```
+
+The SVG will be optimized during the build process, resulting in smaller file sizes in your production build.
+
+## Common use cases
+
+### Preserve specific attributes
+
+You may want to preserve certain SVG attributes that SVGO removes by default:
+
+```js title="astro.config.mjs"
+export default defineConfig({
+  experimental: {
+    svg: {
+      optimize: true,
+      svgoConfig: {
+        plugins: [
+          'preset-default',
+          {
+            name: 'removeViewBox',
+            active: false // Preserve viewBox attribute
+          }
+        ]
+      }
+    }
+  }
+})
+```
+
+### Remove specific elements
+
+Remove unwanted elements like metadata or hidden layers:
+
+```js title="astro.config.mjs"
+export default defineConfig({
+  experimental: {
+    svg: {
+      optimize: true,
+      svgoConfig: {
+        plugins: [
+          'preset-default',
+          {
+            name: 'removeHiddenElems',
+            active: true
+          }
+        ]
+      }
+    }
+  }
+})
+```
+
+### Custom precision
+
+Control the precision of numeric values in path data:
+
+```js title="astro.config.mjs"
+export default defineConfig({
+  experimental: {
+    svg: {
+      optimize: true,
+      svgoConfig: {
+        floatPrecision: 2
+      }
+    }
+  }
+})
+```
+
+## Error handling
+
+If SVGO optimization fails for any reason, Astro will gracefully fall back to using the original, unoptimized SVG content. A warning will be logged to the console, but your build will continue without errors.
+
+## Performance considerations
+
+SVG optimization happens during the build process, not at runtime. This means:
+
+- **Development:** SVGs are not optimized during development for faster rebuild times
+- **Production:** All SVGs are optimized once during the build
+- **No runtime overhead:** Optimized SVGs are served as static assets
+
+The optimization process can increase build times slightly, but results in smaller file sizes and faster page loads for your users.
+
+## Migration notes
+
+This feature is experimental and may have breaking changes in future versions. When this feature becomes stable:
+
+- The `experimental.svg` configuration will move to a top-level `svg` configuration
+- Default behavior may change based on community feedback
+
+## Further reading
+
+- [SVGO documentation](https://svgo.dev/)
+- [SVGO preset-default plugins](https://svgo.dev/docs/preset-default/)