docs: discourage embed component for all use cases and fix broken link

- Update warnings to discourage embed for all asset types (not just videos)
- Recommend video component for videos, Download component for PDFs, img tag for images
- Fix broken link from /learn/docs/content/write-markdown to /learn/docs/writing-content/markdown
- Add notes to PDF and video sections with recommended alternatives
- Update markdown.mdx to be consistent with embed.mdx warnings

Co-Authored-By: Colton Berry <[email protected]>

Author: devin-ai-integration[bot]

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

@@ -13,7 +13,10 @@ Embed local assets like PDFs, videos, and other media directly in your documenta
 ## Usage (embed video)
 
 <Warning>
-  The `<embed>` component isn't well-supported on Safari and may cause compatibility issues. For embedding videos, use the `<video>` component instead, which provides better cross-browser support and more control over playback.
+  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
@@ -33,17 +36,8 @@ Embed local assets like PDFs, videos, and other media directly in your documenta
 
 ### Video file with video tag
 
-    <Warning>
-        The `<embed>` component isn't well-supported on Safari and may cause compatibility issues. For embedding videos, use the [`<video>` component](/learn/docs/content/write-markdown#embedding-videos) instead, which provides better cross-browser support and more control over playback. Additionally, videos with audio will automatically play when the page loads with `<embed>`.
-    </Warning>
-
-  </Tab>
-  <Tab title="Example using `<video>`">
-    <video style={{ aspectRatio: '16 / 9', width: '100%' }} controls>
-      <source src="./growing-fern.mp4" type="video/mp4" />
-    </video>
 <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">
@@ -60,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>
@@ -127,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,20 +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" />
-
-<Warning>
-  The `<embed>` component isn't well-supported on Safari and may cause compatibility issues. For embedding videos, use the `<video>` component instead (see below), which provides better cross-browser support and more control over playback.
-</Warning>
-
 ### 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.