docs: migrate guides from v1 to v2 Starlight

packages/docs/astro.config.mjs

@@ -158,12 +158,7 @@ export default defineConfig({
 				},
 				{
 					label: 'Guides',
-					items: [
-						{
-							label: 'Custom Domain',
-							link: '/guides/custom-domain',
-						},
-					],
+					autogenerate: { directory: 'guides' },
 				},
 				{
 					label: 'Migrate',
@@ -182,6 +177,7 @@ export default defineConfig({
 		optimizeDeps: {
 			exclude: ['svelte-cloudinary'],
 		},
+		envPrefix: ['PUBLIC', 'VITE'],
 		plugins: [
 			{
 				// https://github.com/sveltejs/svelte/issues/9288#issuecomment-1748034687

packages/docs/src/content/docs/guides/background-removal.mdx

@@ -0,0 +1,55 @@
+---
+title: Background Removal
+description: Learn how to use Cloudinary to remove a background from your image.
+---
+
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+import { CldImage } from 'svelte-cloudinary';
+
+:::note
+The Cloudinary AI Background Removal add-on is required to use this feature.
+:::
+
+You can use the `removeBackground` option to generatively remove the background from an image, for example:
+
+<CldImage
+	width="960"
+	height="600"
+	src="images/turtle"
+	alt="turtle image"
+	removeBackground
+/>
+
+<Tabs syncKey="image-api">
+<TabItem label="<CldImage />">
+
+```svelte {10}
+<script>
+	import { CldImage } from 'svelte-cloudinary';
+</script>
+
+<CldImage
+	width="960"
+	height="600"
+	src="images/turtle"
+	alt="turtle image"
+	removeBackground />
+```
+
+</TabItem>
+
+<TabItem label="getCldImageUrl()">
+
+```ts {5}
+import { getCldImageUrl } from 'svelte-cloudinary';
+
+const url = getCldImageUrl({
+	src: 'images/turtle',
+	removeBackground: true,
+	width: 960,
+	height: 600,
+});
+```
+
+</TabItem>
+</Tabs>

packages/docs/src/content/docs/guides/image-underlays.mdx

@@ -0,0 +1,56 @@
+---
+title: Image Underlays
+description: Learn how to use Cloudinary to programatically place images under images.
+---
+
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+import { CldOgImage, CldImage } from 'svelte-cloudinary';
+
+An image underlay allows you to place one image under another (it doesn't work with text). For example we can remove the background from this turtle image, then underlay an image of space:
+
+<CldImage
+	width="960"
+	height="600"
+	src="images/turtle"
+	sizes="100vw"
+	alt="Turtle swimming in a galaxy"
+	removeBackground
+	underlay="images/galaxy"
+/>
+
+<Tabs syncKey="image-api">
+<TabItem label="<CldImage />">
+
+```svelte {11-12}
+<script>
+	import { CldImage } from 'svelte-cloudinary';
+</script>
+
+<CldImage
+	width="960"
+	height="600"
+	src="images/turtle"
+	sizes="100vw"
+	alt="Turtle swimming in a galaxy"
+	removeBackground
+	underlay="images/galaxy" />
+```
+
+</TabItem>
+
+<TabItem label="getCldImageUrl()">
+
+```ts {7-8}
+import { getCldImageUrl } from 'svelte-cloudinary';
+
+const url = getCldImageUrl({
+	width: 960,
+	height: 600,
+	src: 'images/turtle',
+	removeBackground: true,
+	underlay: 'images/galaxy',
+});
+```
+
+</TabItem>
+</Tabs>

packages/docs/src/content/docs/guides/overlays.mdx

@@ -0,0 +1,161 @@
+---
+title: Overlays
+description: Learn how to use Cloudinary to programatically place images/text on top of other images/text.
+---
+
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+import { CldOgImage, CldImage } from 'svelte-cloudinary';
+
+You can use the overlays feature to stack images or text on top of each other, for example:
+
+<CldImage
+	width="960"
+	height="600"
+	src="images/turtle"
+	sizes="100vw"
+	alt="Turtle with earth"
+	overlays={[
+		{
+			publicId: 'images/earth',
+			position: {
+				x: 50,
+				y: 50,
+				gravity: 'north_west',
+			},
+			effects: [
+				{
+					crop: 'fill',
+					gravity: 'auto',
+					width: 500,
+					height: 500,
+				},
+			],
+		},
+		{
+			width: 2670 - 20,
+			crop: 'fit',
+			position: {
+				x: 140,
+				y: 140,
+				angle: -20,
+				gravity: 'south_east',
+			},
+			text: {
+				color: 'blueviolet',
+				fontFamily: 'Source Sans Pro',
+				fontSize: 80,
+				fontWeight: 'bold',
+				textDecoration: 'underline',
+				letterSpacing: 14,
+				text: 'Svelte x Cloudinary',
+			},
+		},
+	]}
+/>
+
+<Tabs syncKey="image-api">
+<TabItem label="<CldImage />">
+
+```svelte {11-47}
+<script>
+	import { CldImage } from 'svelte-cloudinary';
+</script>
+
+<CldImage
+	width="960"
+	height="600"
+	src="images/turtle"
+	sizes="100vw"
+	alt="Turtle with earth"
+	overlays={[
+		{
+			publicId: 'images/earth',
+			position: {
+				x: 50,
+				y: 50,
+				gravity: 'north_west',
+			},
+			effects: [
+				{
+					crop: 'fill',
+					gravity: 'auto',
+					width: 500,
+					height: 500,
+				},
+			],
+		},
+		{
+			width: 2670 - 20,
+			crop: 'fit',
+			position: {
+				x: 140,
+				y: 140,
+				angle: -20,
+				gravity: 'south_east',
+			},
+			text: {
+				color: 'blueviolet',
+				fontFamily: 'Source Sans Pro',
+				fontSize: 80,
+				fontWeight: 'bold',
+				textDecoration: 'underline',
+				letterSpacing: 14,
+				text: 'Svelte x Cloudinary',
+			},
+		},
+	]} />
+```
+
+</TabItem>
+
+<TabItem label="getCldImageUrl()">
+
+```ts {7-43}
+import { getCldImageUrl } from 'svelte-cloudinary';
+
+const url = getCldImageUrl({
+	width: 960,
+	height: 600,
+	src: 'images/turtle',
+	overlays: [
+		{
+			publicId: 'images/earth',
+			position: {
+				x: 50,
+				y: 50,
+				gravity: 'north_west',
+			},
+			effects: [
+				{
+					crop: 'fill',
+					gravity: 'auto',
+					width: 500,
+					height: 500,
+				},
+			],
+		},
+		{
+			width: 2670 - 20,
+			crop: 'fit',
+			position: {
+				x: 140,
+				y: 140,
+				angle: -20,
+				gravity: 'south_east',
+			},
+			text: {
+				color: 'blueviolet',
+				fontFamily: 'Source Sans Pro',
+				fontSize: 80,
+				fontWeight: 'bold',
+				textDecoration: 'underline',
+				letterSpacing: 14,
+				text: 'Svelte x Cloudinary',
+			},
+		},
+	],
+});
+```
+
+</TabItem>
+</Tabs>

packages/docs/src/content/docs/guides/responsive-images.mdx

@@ -0,0 +1,35 @@
+---
+title: Responsive Images
+description: Learn how to use Cloudinary to generate performant responsive images.
+---
+
+import { CldOgImage, CldImage } from 'svelte-cloudinary';
+
+Responsive images are great for performance since the browser can load a smaller image on a smaller device, where the drop in quality isn't noticable. This will increase page load times and general user experience for everyone, as they get both a noticably high quality image and faster page load.
+
+You can configure specifically the image sizes you want, using a media query like synax, with the `sizes` prop/option. Cloudinary will generate the necessary sizes on the fly, as usual!
+
+<CldImage
+	width="960"
+	height="600"
+	src="images/turtle"
+	sizes="(max-width: 768px) 100vw,
+        (max-width: 1200px) 50vw,
+        33vw"
+	alt="turtle image"
+/>
+
+```svelte
+<script>
+	import { CldImage } from 'svelte-cloudinary';
+</script>
+
+<CldImage
+	width="960"
+	height="600"
+	src="images/turtle"
+	sizes="(max-width: 768px) 100vw,
+        (max-width: 1200px) 50vw,
+        33vw"
+	alt="turtle image" />
+```