From fc0b95fc75942c1b9e334a9b918e992a28d834e1 Mon Sep 17 00:00:00 2001
From: mohith2883 <88938356+mohith2883@users.noreply.github.com>
Date: Wed, 1 Oct 2025 19:18:15 +0530
Subject: [PATCH 1/4] docs: migrate guides from v1 to v2 Starlight
---
.../docs/guides/background-removal.mdx | 75 ++++++
.../docs/guides/image-optimization.mdx | 73 ++++++
.../content/docs/guides/image-overlays.mdx | 121 ++++++++++
.../content/docs/guides/image-underlays.mdx | 77 +++++++
.../src/content/docs/guides/placeholders.mdx | 160 +++++++++++++
.../content/docs/guides/responsive-images.mdx | 88 +++++++
.../content/docs/guides/social-media-card.mdx | 216 ++++++++++++++++++
.../src/content/docs/guides/text-overlays.mdx | 131 +++++++++++
.../guides/uploading-images-and-videos.mdx | 54 +++++
vercel.json | 40 ----
10 files changed, 995 insertions(+), 40 deletions(-)
create mode 100644 packages/docs/src/content/docs/guides/background-removal.mdx
create mode 100644 packages/docs/src/content/docs/guides/image-optimization.mdx
create mode 100644 packages/docs/src/content/docs/guides/image-overlays.mdx
create mode 100644 packages/docs/src/content/docs/guides/image-underlays.mdx
create mode 100644 packages/docs/src/content/docs/guides/placeholders.mdx
create mode 100644 packages/docs/src/content/docs/guides/responsive-images.mdx
create mode 100644 packages/docs/src/content/docs/guides/social-media-card.mdx
create mode 100644 packages/docs/src/content/docs/guides/text-overlays.mdx
create mode 100644 packages/docs/src/content/docs/guides/uploading-images-and-videos.mdx
diff --git a/packages/docs/src/content/docs/guides/background-removal.mdx b/packages/docs/src/content/docs/guides/background-removal.mdx
new file mode 100644
index 00000000..0651f44b
--- /dev/null
+++ b/packages/docs/src/content/docs/guides/background-removal.mdx
@@ -0,0 +1,75 @@
+---
+title: Guides/Background Removal
+order: 1
+---
+
+
+
+# Removing a Background from an Image
+
+The CldImage component allows you to easily remove backgrounds from images using the `removeBackground` prop.
+
+
+ Removing backgrounds require enabling the Cloudinary AI Background Removal Add-On which includes a free tier for getting started.
+
+
+## Example
+
+
+
+
+
+
+
+
+```svelte
+
+
+
+```
+
+
+
+
+```html
+
+```
+
+
+
+
+## Learn More
+
+- [CldImage](/cldimage/usage)
+- [getCldImageUrl](/getcldimageurl/usage)
\ No newline at end of file
diff --git a/packages/docs/src/content/docs/guides/image-optimization.mdx b/packages/docs/src/content/docs/guides/image-optimization.mdx
new file mode 100644
index 00000000..e8c341e8
--- /dev/null
+++ b/packages/docs/src/content/docs/guides/image-optimization.mdx
@@ -0,0 +1,73 @@
+---
+title: Guides/Image Optimization
+order: 2
+---
+
+
+
+# Optimizing Images in Svelte/SvelteKit
+
+Automatically optimize images using the CldImage component. By default, CldImage opts you in to automatic optimization including delivering the most optimal format for the browser (WebP, AVIF).
+
+You can further optimize delivery by using [responsive sizing](/guides/responsive-images) by using the `sizes` prop.
+
+## Example
+
+
+
+
+
+
+
+
+```svelte
+
+
+
+```
+
+
+
+
+```svelte
+
+```
+
+
+
+
+## Watch & Learn
+
+
+
+## Learn More
+
+- [Responsive Images](/guides/responsive-images)
+- [CldImage](/cldimage/usage)
+- [getCldImageUrl](/getcldimageurl/usage)
\ No newline at end of file
diff --git a/packages/docs/src/content/docs/guides/image-overlays.mdx b/packages/docs/src/content/docs/guides/image-overlays.mdx
new file mode 100644
index 00000000..2aaf0d51
--- /dev/null
+++ b/packages/docs/src/content/docs/guides/image-overlays.mdx
@@ -0,0 +1,121 @@
+---
+title: Guides/Image Overlays
+order: 3
+---
+
+
+
+# Overlaying Images
+
+You can add images on top of other images by using image-based overlays.
+
+## Example
+
+
+
+
+
+
+
+
+```svelte
+
+
+
+```
+
+
+
+
+```svelte
+
+```
+
+
+
+
+## Learn More
+
+- [CldImage](/cldimage/usage)
+- [getCldImageUrl](/getcldimageurl/usage)
\ No newline at end of file
diff --git a/packages/docs/src/content/docs/guides/image-underlays.mdx b/packages/docs/src/content/docs/guides/image-underlays.mdx
new file mode 100644
index 00000000..4775362a
--- /dev/null
+++ b/packages/docs/src/content/docs/guides/image-underlays.mdx
@@ -0,0 +1,77 @@
+---
+title: Guides/Image Underlays
+order: 4
+---
+
+
+
+# Adding Layers Under Images
+
+Underlays function very similar to overlays in terms of options, however they **do not support text**.
+
+See the examples above under Overlays to learn more about the available configurations.
+
+## Example
+
+
+
+
+
+
+
+
+```svelte
+
+
+
+```
+
+
+
+
+```svelte
+
+```
+
+
+
+
+## Learn More
+
+- [CldImage](/cldimage/usage)
+- [getCldImageUrl](/getcldimageurl/usage)
\ No newline at end of file
diff --git a/packages/docs/src/content/docs/guides/placeholders.mdx b/packages/docs/src/content/docs/guides/placeholders.mdx
new file mode 100644
index 00000000..4b9ea770
--- /dev/null
+++ b/packages/docs/src/content/docs/guides/placeholders.mdx
@@ -0,0 +1,160 @@
+---
+title: Guides/Placeholders
+---
+
+
+
+# Display Placeholder While Image is Loading
+
+CldImage wraps the Unpic Image component, thus giving us access to the placeholder API
+which can display an SVG image while the image itself is loading.
+
+This helps for providing a great user experience, rather than an empty space, to help
+let the visitor know that image is loading.
+
+To do this, we have several options:
+
+- `placeholder="blur"` coupled with a `blurDataURL`
+- `placeholder="..."` with the contents being a data URL
+
+## Blurred Images
+
+To achieve a blurred image effect, we can first convert our Cloudinary image to a Data URL
+then pass it in to our CldImage component.
+
+
+
+
+
+ Inside of the SvelteKit app, we can utilize server side code to generate a data URL from our image.
+
+
+
+```js
+
+import { getCldImageUrl } from 'svelte-cloudinary';
+
+export const load = () => {
+ const imageUrl = getCldImageUrl({
+ src: '',
+ width: 100, // Resize the original file to a smaller size
+ });
+ const response = await fetch(imageUrl);
+ const arrayBuffer = await response.arrayBuffer();
+ const buffer = Buffer.from(arrayBuffer);
+ const base64 = buffer.toString("base64");
+ const dataUrl = `data:${response.type};base64,${base64}`;
+ return {
+ dataUrl
+ }
+}
+```
+
+
+
+ Then when rendering CldImage, utilize the `dataUrl` using `placeholder` and `blurDataURL`:
+
+```svelte
+
+
+
+```
+
+## Shimmer
+
+In a similar fashion, we can create a shimmer effect when
+our images are loading.
+
+
+
+
+
+Inside of the SvelteKit app you can use a server side code `+page.server.js` to generate a data URL from our image.
+
+
+
+```js
+export const load = () => {
+ const shimmer = (w: number, h: number) => `
+ `;
+
+ const toBase64 = (str: string) =>
+ typeof window === 'undefined' ? Buffer.from(str).toString('base64') : window.btoa(str);
+
+ const dataUrl = `data:image/svg+xml;base64,${toBase64(shimmer(600, 400))}`;
+ return {
+ dataUrl
+ };
+};
+```
+
+
+
+ Then when rendering CldImage, utilize the `dataUrl` using `placeholder`:
+
+```svelte
+
+
+
+```
+
+## Learn More
+
+- [CldImage](/cldimage/usage)
+- [getCldImageUrl](/getcldimageurl/usage)
\ No newline at end of file
diff --git a/packages/docs/src/content/docs/guides/responsive-images.mdx b/packages/docs/src/content/docs/guides/responsive-images.mdx
new file mode 100644
index 00000000..0692d9da
--- /dev/null
+++ b/packages/docs/src/content/docs/guides/responsive-images.mdx
@@ -0,0 +1,88 @@
+---
+title: Guides/Responsive Images
+---
+
+
+
+# Responsive Images
+
+The [CldImage](/cldimage/usage) component takes advantage of responsive images generated using the [Unpic component](https://unpic.pics/img/svelte/).
+
+Using the `sizes` prop, you can configure exactly the sizes you need for your application:
+
+```svelte
+
+
+
+ import { CldImage } from 'svelte-cloudinary';
+
+
+
+```
+
+Using cropping, we're setting a width of 600px and a height of 600px, telling Cloudinary we want to take our original image, crop it to that size, then position the focal point to the face in the image detected using AI.
+
+From a responsive standpoint, we're stating that we want full width images on anything less than 480px and half-width images on anything above.
+
+The challenge here is when cropping the image, we're cropping it to 600px, which is smaller than some of the sizes we want to responsively serve. We don't want to responsively change that cropped size, otherwise we would change the cropping results due to the crop attempting to grab different portions of the image depending on the size.
+
+To avoid attempting to load upscaled images, resulting in blurry or grainy images as well as more bandwidth used on a device, any responsive size that is greater than the set width will not be generated and instead, we'll deliver an image at the size specifiy (in this example, 600x600).
+
+For instance, in the above, the resulting responive image in the HTML may look like:
+
+```jsx copy
+
+
+```
+
+Notice that all of the URLs are the same except for the first one, as it's smaller than 600px.
+
+When the browser attempts to load these responsive images, it will effectively ignore the same URLs, only having loaded it once if resizing the browser.
\ No newline at end of file
diff --git a/packages/docs/src/content/docs/guides/social-media-card.mdx b/packages/docs/src/content/docs/guides/social-media-card.mdx
new file mode 100644
index 00000000..1fe3e9e3
--- /dev/null
+++ b/packages/docs/src/content/docs/guides/social-media-card.mdx
@@ -0,0 +1,216 @@
+---
+title: Guides/Social Media Cards
+---
+
+
+
+# Generating Social Media Cards
+
+
+ CldOgImage does not render an `<img>` tag, meaning it can't be visually embedded on a page. The following examples make use of the `<CldImage>` tag to showcase what's possible.
+
+
+## Example
+
+
+
+
+
+
+
+
+```svelte
+
+
+
+```
+
+
+
+
+```svelte
+
+```
+
+
+
+
+## Learn More
+
+- [CldOgImage Configuration](/cldogimage/configuration)
\ No newline at end of file
diff --git a/packages/docs/src/content/docs/guides/text-overlays.mdx b/packages/docs/src/content/docs/guides/text-overlays.mdx
new file mode 100644
index 00000000..e9927dee
--- /dev/null
+++ b/packages/docs/src/content/docs/guides/text-overlays.mdx
@@ -0,0 +1,131 @@
+---
+title: Guides/Text Overlays
+---
+
+
+
+# Adding Text to an Image
+
+You can add text on top of your image with text-based overlays.
+
+## Example
+
+
+
+
+
+
+
+
+```svelte
+
+
+
+```
+
+
+
+
+```svelte
+
+```
+
+
+
+
+## Learn More
+
+- [CldImage](/cldimage/usage)
+- [getCldImageUrl](/getcldimageurl/usage)
\ No newline at end of file
diff --git a/packages/docs/src/content/docs/guides/uploading-images-and-videos.mdx b/packages/docs/src/content/docs/guides/uploading-images-and-videos.mdx
new file mode 100644
index 00000000..97a15f61
--- /dev/null
+++ b/packages/docs/src/content/docs/guides/uploading-images-and-videos.mdx
@@ -0,0 +1,54 @@
+---
+title: Guides/Uploading Images and Videos
+order: 9
+---
+
+
+
+# Uploading Images & Videos
+
+Use the [CldUploadButton](/clduploadbutton/usage) or [CldUploadWidget](/clduploadwidget/usage) components to add upload capabilities to your app.
+
+The components utilize the [Cloudinary Upload Widget](https://cloudinary.com/documentation/upload_widget), built for Svelte.
+
+## Example
+
+ {
+resource = result?.info;
+widget.close();
+}}
+uploadPreset={PUBLIC_CLOUDINARY_UNSIGNED_UPLOAD_PRESET}
+/>
+{#if resource?.resource_type === 'image'}
+
+{/if}
+
+{#if resource?.resource_type === 'video'}
+
+{/if}
+
+```svelte
+
+
+
+ Upload to Cloudinary
+
+```
+
+## Learn More
+
+- [CldUploadButton](/clduploadbutton/usage)
\ No newline at end of file
diff --git a/vercel.json b/vercel.json
index 0ff0df24..7b907c4f 100644
--- a/vercel.json
+++ b/vercel.json
@@ -77,46 +77,6 @@
"source": "/getcldogimageurl/examples",
"destination": "/missing"
},
- {
- "source": "/guides",
- "destination": "/missing"
- },
- {
- "source": "/guides/background-removal",
- "destination": "/missing"
- },
- {
- "source": "/guides/image-optimization",
- "destination": "/missing"
- },
- {
- "source": "/guides/image-overlays",
- "destination": "/missing"
- },
- {
- "source": "/guides/image-underlays",
- "destination": "/missing"
- },
- {
- "source": "/guides/placeholders",
- "destination": "/missing"
- },
- {
- "source": "/guides/responsive-images",
- "destination": "/missing"
- },
- {
- "source": "/guides/social-media-cards",
- "destination": "/missing"
- },
- {
- "source": "/guides/text-overlays",
- "destination": "/missing"
- },
- {
- "source": "/guides/uploading-images-and-videos",
- "destination": "/missing"
- },
{
"source": "/templates",
"destination": "/missing"
From 265f4842aafb7a09ffcc01649fa323decbb5af93 Mon Sep 17 00:00:00 2001
From: mohith2883 <88938356+mohith2883@users.noreply.github.com>
Date: Sun, 5 Oct 2025 07:43:56 +0530
Subject: [PATCH 2/4] docs: migrate guides from v1 to v2 Starlight
---
.../docs/src/content/docs/guides/background-removal.mdx | 8 --------
.../docs/src/content/docs/guides/image-optimization.mdx | 2 ++
packages/docs/src/content/docs/guides/placeholders.mdx | 2 ++
3 files changed, 4 insertions(+), 8 deletions(-)
diff --git a/packages/docs/src/content/docs/guides/background-removal.mdx b/packages/docs/src/content/docs/guides/background-removal.mdx
index 0651f44b..e62fbd48 100644
--- a/packages/docs/src/content/docs/guides/background-removal.mdx
+++ b/packages/docs/src/content/docs/guides/background-removal.mdx
@@ -1,15 +1,7 @@
---
title: Guides/Background Removal
-order: 1
---
-
# Removing a Background from an Image
diff --git a/packages/docs/src/content/docs/guides/image-optimization.mdx b/packages/docs/src/content/docs/guides/image-optimization.mdx
index e8c341e8..bce07c15 100644
--- a/packages/docs/src/content/docs/guides/image-optimization.mdx
+++ b/packages/docs/src/content/docs/guides/image-optimization.mdx
@@ -59,12 +59,14 @@ You can further optimize delivery by using [responsive sizing](/guides/responsiv
+
## Learn More
diff --git a/packages/docs/src/content/docs/guides/placeholders.mdx b/packages/docs/src/content/docs/guides/placeholders.mdx
index 4b9ea770..4b179f54 100644
--- a/packages/docs/src/content/docs/guides/placeholders.mdx
+++ b/packages/docs/src/content/docs/guides/placeholders.mdx
@@ -31,6 +31,7 @@ To do this, we have several options:
To achieve a blurred image effect, we can first convert our Cloudinary image to a Data URL
then pass it in to our CldImage component.
+
Inside of the SvelteKit app, we can utilize server side code to generate a data URL from our image.
From 4aa58a663556c71f4664e331aa073d08cd630a03 Mon Sep 17 00:00:00 2001
From: mohith2883 <88938356+mohith2883@users.noreply.github.com>
Date: Mon, 6 Oct 2025 17:03:15 +0530
Subject: [PATCH 3/4] docs: migrate guides from v1 to v2 Starlight
---
.../docs/src/content/docs/guides/background-removal.mdx | 3 ---
packages/docs/src/content/docs/guides/placeholders.mdx | 8 ++++----
2 files changed, 4 insertions(+), 7 deletions(-)
diff --git a/packages/docs/src/content/docs/guides/background-removal.mdx b/packages/docs/src/content/docs/guides/background-removal.mdx
index e62fbd48..abedd645 100644
--- a/packages/docs/src/content/docs/guides/background-removal.mdx
+++ b/packages/docs/src/content/docs/guides/background-removal.mdx
@@ -24,9 +24,6 @@ The CldImage component allows you to easily remove backgrounds from images using
/>
-
-
-
```svelte
```
-
-
```html