From cd1f974cbf135d736be5fc531e0718e617b525fb Mon Sep 17 00:00:00 2001
From: Hamed Rabah <26891088+hamedrabah@users.noreply.github.com>
Date: Thu, 27 Aug 2026 14:52:58 -0700
Subject: [PATCH] docs: clarify nested image paths

---
 create/image-embeds.mdx | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/create/image-embeds.mdx b/create/image-embeds.mdx
index 5f71fb2393..8da8acb4d3 100644
--- a/create/image-embeds.mdx
+++ b/create/image-embeds.mdx
@@ -28,6 +28,19 @@ Use [Markdown syntax](https://www.markdownguide.org/basic-syntax/#images) to add
 
 Image paths are root-relative from your docs repository. For example, if your image is at `images/screenshot.png` in your repository, the path is `/images/screenshot.png`. Relative paths (for example, `./screenshot.png`) are not supported.
 
+You can store images in any directory, including an `assets` folder beside related pages. The path in MDX must still start at the repository root:
+
+```text
+/your-project
+  |- docs.json
+  |- guides/
+    |- setup.mdx
+    |- assets/
+      |- setup-dialog.png
+```
+
+Reference the image from any page with `/guides/assets/setup-dialog.png`. You do not need a global image-directory setting.
+
 <Tip>
   Always include descriptive alt text to improve accessibility and SEO. The alt text should clearly describe what the image shows.
 </Tip>