Update images and embeds

image-embeds.mdx

@@ -1,80 +1,113 @@
 ---
-title: 'Images and embeds'
-description: 'Add image, video, and other HTML elements'
-icon: 'image'
+title: "Images and embeds"
+description: "Add images, videos, and iframes"
+icon: "image"
 ---
 
+<Frame>
 <img
   className="rounded-xl"
   src="https://mintlify-assets.b-cdn.net/bigbend.jpg"
+  alt="Photograph of a scenic landscape with purple flowers in the foreground, mountains in the background, and a blue sky with scattered clouds."
 />
+</Frame>
 
-## Image
+## Images
 
-Images are the most common way to add visual content to your documentation.
+Add images to provide visual context, examples, or decoration to your documentation.
 
-### Basics
+### Basic image syntax
 
-The [markdown syntax](https://www.markdownguide.org/basic-syntax/#images) lets you add images using the following code
+Use [Markdown syntax](https://www.markdownguide.org/basic-syntax/#images) to add images to your documentation:
 
 ```mdx
-![title](/path/image.jpg)
+![Alt text describing the image](/path/to/image.png)
 ```
+
 <Tip>
-To make sure images are displayed correctly in production, add a forward slash to the image path (e.g. `/path/image.jpg`).
+  Always include descriptive alt text to improve accessibility and SEO. The alt text should clearly describe what the image shows.
 </Tip>
 
-Note that the image file size must be less than 20MB. Otherwise, we recommend hosting on a CDN provider like [S3](https://aws.amazon.com/s3), [Cloudinary](https://cloudinary.com) or a similar service.
+Image files must be less than 20MB. For larger files, host them on a CDN service like [Amazon S3](https://aws.amazon.com/s3) or [Cloudinary](https://cloudinary.com).
 
-### Embeds
+### HTML image embeds
 
-To get more customizability with images, you can also use embeds to add images.
+For more control over image display, use HTML `<img>` tags:
 
 ```html
-<img height="200" src="/path/image.jpg" />
+<img 
+  src="/images/dashboard.png" 
+  alt="Main dashboard interface"
+  height="300"
+  className="rounded-lg"
+/>
 ```
 
-### Disable Image Zoom
+#### Disable zoom functionality
 
-To disable the default zoom on click for images, add the `noZoom` property to image embeds.
+To disable the default zoom on click for images, add the `noZoom` property:
 
-```html
-<img height="200" noZoom src="/path/image.jpg" />
+```html highlight="4"
+<img 
+  src="/images/screenshot.png" 
+  alt="Descriptive alt text"
+  noZoom 
+  height="200"
+/>
 ```
 
-### Linking Images
+#### Link images
 
-To link an image, for example to create a button on your docs, encompass the image in a link with the `noZoom` property. Images in `a` tags will automatically have a pointer cursor.
+To make an image a clickable link, wrap the image in an anchor tag and add the `noZoom` property:
 
 ```html
 <a href="https://mintlify.com" target="_blank">
-  <img height="200" noZoom src="/path/image.jpg" />
+  <img 
+    src="/images/logo.png" 
+    alt="Mintlify logo"
+    noZoom 
+    height="100"
+  />
 </a>
 ```
 
-### Dark Mode
+<Note>
+  Images within anchor tags automatically display a pointer cursor to indicate they are clickable.
+</Note>
+
+#### Light and dark mode images
 
-To use separate images for light and dark mode, use Tailwind CSS to hide and show images.
+To display different images for light and dark themes, use Tailwind CSS classes:
 
 ```html
-<img className="block dark:hidden" src="/path/image-light.jpg" />
-<img className="hidden dark:block" src="/path/image-dark.jpg" />
+<!-- Light mode image -->
+<img 
+  className="block dark:hidden" 
+  src="/images/light-mode.png" 
+  alt="Light mode interface"
+/>
+
+<!-- Dark mode image -->
+<img 
+  className="hidden dark:block" 
+  src="/images/dark-mode.png" 
+  alt="Dark mode interface"
+/>
 ```
 
-### Related
+## Videos
+
+Mintlify supports [HTML tags in Markdown](https://www.markdownguide.org/basic-syntax/#html), giving you flexibility to create rich content.
 
-For more information, we recommend the following sections:
+<Tip>
+  Always include fallback text content within video elements for browsers that don't support video playback.
+</Tip>
 
-<Card
-  title="Frame Component Reference"
-  icon="frame"
-  href="/components/frames"
->
-  Read the reference for the Frame component
-</Card>
+### YouTube embeds
 
-## Videos
+Embed YouTube videos using iframe elements:
 
+```html
 <iframe
   className="w-full aspect-video rounded-xl"
   src="https://www.youtube.com/embed/4KzFe50RQkQ"
@@ -83,62 +116,64 @@ For more information, we recommend the following sections:
   allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
   allowFullScreen
 ></iframe>
+```
 
-<br />
-
-<Tip>
-
-Mintlify supports [HTML tags in Markdown](https://www.markdownguide.org/basic-syntax/#html). This is helpful if you prefer HTML tags to Markdown syntax, and lets you create documentation with infinite flexibility.
-
-</Tip>
-
-For YouTube videos use:
-
-```html
+<Frame>
 <iframe
-  width="560"
-  height="315"
+  className="w-full aspect-video rounded-xl"
   src="https://www.youtube.com/embed/4KzFe50RQkQ"
   title="YouTube video player"
-  frameborder="0"
+  frameBorder="0"
   allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
   allowFullScreen
 ></iframe>
-```
+</Frame>
 
-For other videos, use:
+### Self-hosted videos
+
+Use the HTML `<video>` element for self-hosted video content:
 
 ```html
 <video
   controls
-  className="w-full aspect-video"
+  className="w-full aspect-video rounded-xl"
   src="link-to-your-video.com"
 ></video>
 ```
 
-To autoplay the video, use:
+### Autoplay videos
+
+To autoplay a video, use:
 
 ```html
 <video
   autoPlay
   muted
   loop
   playsInline
-  className="w-full aspect-video"
-  src="link-to-your-video.com"
+  className="w-full aspect-video rounded-xl"
+  src="/videos/demo.mp4"
 ></video>
 ```
 
-<Warning>
-Since Mintlify needs to adhere to the JSX syntax, double word attributes will need to 
-be written in camelCase such as `autoPlay` and `playsInline`.
-</Warning>
+<Note>
+  When using JSX syntax, write double-word attributes in camelCase: `autoPlay`, `playsInline`, `allowFullScreen`.
+</Note>
 
-## iFrames
+## iframes
 
-Loads another HTML page within the document.
+Embed external content using iframe elements:
 
 ```html
-<iframe src="https://www.youtube.com/embed/4KzFe50RQkQ"> </iframe>
+<iframe 
+  src="https://example.com/embed" 
+  title="Embedded content"
+  className="w-full h-96 rounded-xl"
+></iframe>
 ```
 
+## Related resources
+
+<Card title="Frame component reference" icon="frame" horizontal href="/components/frames">
+  Learn how to use the Frame component for presenting images.
+</Card>

settings/custom-scripts.mdx

@@ -1,10 +1,26 @@
 ---
-title: 'Custom scripts'
-description: 'Fully customize your documentation with custom CSS and JS'
+title: "Custom scripts"
+description: "Fully customize your documentation with custom CSS and JS"
 icon: "code"
 ---
 
-Add custom CSS and JavaScript to your documentation to fully customize the look and feel.
+Use CSS to style HTML elements or add custom CSS and JavaScript to fully customize the look and feel of your documentation.
+
+## Styling with Tailwind CSS
+
+Use Tailwind CSS v3 to style HTML elements. You can control layout, spacing, colors, and other visual properties. Some common classes are:
+
+- `w-full` - Full width
+- `aspect-video` - 16:9 aspect ratio
+- `rounded-xl` - Large rounded corners
+- `block`, `hidden` - Display control
+- `dark:hidden`, `dark:block` - Dark mode visibility
+
+Tailwind CSS arbitrary values are not supported. For custom values, use the `style` prop instead.
+
+```html
+<img style={{ width: '350px', margin: '12px auto' }} src="/path/image.jpg" />
+```
 
 ## Custom CSS