Add Safari compatibility warnings for embed component

fern/products/docs/pages/component-library/default-components/embed.mdx

@@ -12,6 +12,18 @@ Embed local assets like PDFs, videos, and other media directly in your documenta
 
 ## Usage (embed video)
 
+<Warning>
+  The `<embed>` component isn't recommended for use as it has inconsistent browser support, particularly on Safari and mobile browsers. Instead, use the recommended alternatives below for better cross-browser compatibility:
+  - **Videos**: Use the [`<video>` component](/learn/docs/writing-content/markdown#local-videos)
+  - **PDFs**: Use the `<Download>` component (see [below](#downloadable-assets))
+  - **Images**: Use the `<img>` tag or Markdown image syntax
+</Warning>
+
+## Properties
+
+<ParamField path="src" type="string" required={true}>
+  Path to your local asset (relative to current MDX file)
+</ParamField>
 <div className="highlight-frame">
 <embed src="./growing-fern.mp4" type="video/mp4" style={{ aspectRatio: '16 / 9', width: '100%' }} />
 </div>
@@ -25,7 +37,7 @@ Embed local assets like PDFs, videos, and other media directly in your documenta
 ### Video file with video tag
 
 <Note>
-  Videos with audio will automatically play when the page loads. Using [`<video>` component](/learn/docs/content/write-markdown#embedding-videos) disables this behavior and provides more control over playback.
+  The `<video>` component is the recommended approach for embedding videos, providing better cross-browser support and more control over playback. Using [`<video>` component](/learn/docs/writing-content/markdown#local-videos) prevents videos with audio from automatically playing when the page loads.
 </Note>
 
 <div className="highlight-frame">
@@ -42,6 +54,10 @@ Embed local assets like PDFs, videos, and other media directly in your documenta
 
 ### PDF document
 
+<Note>
+  For PDFs, use the `<Download>` component (see [below](#downloadable-assets)) instead of `<embed>` for better cross-browser compatibility, especially on mobile devices.
+</Note>
+
 <div className="highlight-frame">
 <embed src="./all-about-ferns.pdf" type="application/pdf" width="100%" height="500px" />
 </div>
@@ -109,5 +125,3 @@ Enable users to download assets from within your documentation, instead of linki
 
 <br />
 <br />
-
-

fern/products/docs/pages/component-library/writing-content/markdown.mdx

@@ -110,16 +110,21 @@ For more details about the HTML image element and its attributes, see the [MDN d
 
 ## Embedding local assets
 
-You can embed local assets in your Markdown pages using the [`<embed>` component](/learn/docs/content/components/embed). This is useful for displaying PDFs, images, videos, OpenAPI files, and other assets into your docs.
+You can embed local assets in your Markdown pages using the [`<embed>` component](/learn/docs/writing-content/components/embed). However, the `<embed>` component isn't recommended for use due to inconsistent browser support.
 
-For example, to embed a video, use the following Markdown:
+<Warning>
+  The `<embed>` component isn't recommended for use as it has inconsistent browser support, particularly on Safari and mobile browsers. Instead, use these recommended alternatives:
+  - **Videos**: Use the `<video>` component (see [below](#local-videos))
+  - **PDFs**: Use a download link or the `<Download>` component
+  - **Images**: Use the `<img>` tag or Markdown image syntax
+</Warning>
+
+For example, if you need to embed a video, use the `<video>` component instead:
 
 ```mdx
-<embed src="./path/to/asset.mp4" type="video/mp4" />
+<video src="./path/to/asset.mp4" controls />
 ```
 
-<embed src="./embed-fern-waving.mp4" type="video/mp4" width="640px" height="360px" />
-
 ### Local videos
 
 You can embed videos in your documentation using the HTML `<video>` tag. This gives you control over video playback settings like autoplay, looping, and muting.