From bb28e7374fee861843aecc93d27921624e5d895a Mon Sep 17 00:00:00 2001
From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Mon, 3 Nov 2025 18:20:20 +0000
Subject: [PATCH 1/8] docs: add Safari compatibility warnings for embed
 component

- Add warning to embed component page about Safari compatibility issues
- Recommend using <video> component instead for embedding videos
- Update markdown content page with same Safari warning
- Emphasize better cross-browser support with <video> component

Co-Authored-By: Colton Berry <coltonsberry@gmail.com>
---
 .../component-library/default-components/embed.mdx     | 10 +++++++---
 .../component-library/writing-content/markdown.mdx     |  4 ++++
 2 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/fern/products/docs/pages/component-library/default-components/embed.mdx b/fern/products/docs/pages/component-library/default-components/embed.mdx
index 0deacd302..aa91e96d4 100644
--- a/fern/products/docs/pages/component-library/default-components/embed.mdx
+++ b/fern/products/docs/pages/component-library/default-components/embed.mdx
@@ -12,6 +12,10 @@ Fern also implements a custom component for embedding downloadable assets:
 
 - `<Download src="..." />` - read more about it [below](#downloadable-assets).
 
+<Warning>
+  The `<embed>` component is not 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.
+</Warning>
+
 ## Properties
 
 <ParamField path="src" type="string" required={true}>
@@ -38,9 +42,9 @@ Fern also implements a custom component for embedding downloadable assets:
     <embed src="./growing-fern.mp4" type="video/mp4" style={{ aspectRatio: '16 / 9', width: '100%' }} />
     ```
 
-    <Note>
-        Videos with audio will automatically play when the page loads. If you want to prevent this behavior, consider using the [`<video>` component](/learn/docs/content/write-markdown#embedding-videos) instead, which provides more control over playback.
-    </Note>
+    <Warning>
+        The `<embed>` component is not 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>`">
diff --git a/fern/products/docs/pages/component-library/writing-content/markdown.mdx b/fern/products/docs/pages/component-library/writing-content/markdown.mdx
index 889090b05..7ac12c165 100644
--- a/fern/products/docs/pages/component-library/writing-content/markdown.mdx
+++ b/fern/products/docs/pages/component-library/writing-content/markdown.mdx
@@ -120,6 +120,10 @@ For example, to embed a video, use the following Markdown:
 
 <embed src="./embed-fern-waving.mp4" type="video/mp4" width="640px" height="360px" />
 
+<Warning>
+  The `<embed>` component is not 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.

From 0940b966459c7fe838cb9fbefca96f44c70e090a Mon Sep 17 00:00:00 2001
From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Mon, 3 Nov 2025 18:25:20 +0000
Subject: [PATCH 2/8] fix: use contractions in Safari warnings per Vale linting

Co-Authored-By: Colton Berry <coltonsberry@gmail.com>
---
 .../docs/pages/component-library/default-components/embed.mdx | 4 ++--
 .../docs/pages/component-library/writing-content/markdown.mdx | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/fern/products/docs/pages/component-library/default-components/embed.mdx b/fern/products/docs/pages/component-library/default-components/embed.mdx
index aa91e96d4..8e410c7bb 100644
--- a/fern/products/docs/pages/component-library/default-components/embed.mdx
+++ b/fern/products/docs/pages/component-library/default-components/embed.mdx
@@ -13,7 +13,7 @@ Fern also implements a custom component for embedding downloadable assets:
 - `<Download src="..." />` - read more about it [below](#downloadable-assets).
 
 <Warning>
-  The `<embed>` component is not 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 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.
 </Warning>
 
 ## Properties
@@ -43,7 +43,7 @@ Fern also implements a custom component for embedding downloadable assets:
     ```
 
     <Warning>
-        The `<embed>` component is not 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>`.
+        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>
diff --git a/fern/products/docs/pages/component-library/writing-content/markdown.mdx b/fern/products/docs/pages/component-library/writing-content/markdown.mdx
index 7ac12c165..78762c0cd 100644
--- a/fern/products/docs/pages/component-library/writing-content/markdown.mdx
+++ b/fern/products/docs/pages/component-library/writing-content/markdown.mdx
@@ -121,7 +121,7 @@ For example, to embed a video, use the following Markdown:
 <embed src="./embed-fern-waving.mp4" type="video/mp4" width="640px" height="360px" />
 
 <Warning>
-  The `<embed>` component is not 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.
+  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

From ca5ff5cfcf1c51b5542583dfc740f3170d9e44ce Mon Sep 17 00:00:00 2001
From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Tue, 4 Nov 2025 18:49:51 +0000
Subject: [PATCH 3/8] 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 <coltonsberry@gmail.com>
---
 .../default-components/embed.mdx              | 22 ++++++++-----------
 .../writing-content/markdown.mdx              | 19 ++++++++--------
 2 files changed, 19 insertions(+), 22 deletions(-)

diff --git a/fern/products/docs/pages/component-library/default-components/embed.mdx b/fern/products/docs/pages/component-library/default-components/embed.mdx
index fd60be944..0d2946cf3 100644
--- a/fern/products/docs/pages/component-library/default-components/embed.mdx
+++ b/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 />
-
-
diff --git a/fern/products/docs/pages/component-library/writing-content/markdown.mdx b/fern/products/docs/pages/component-library/writing-content/markdown.mdx
index 78762c0cd..3308b926c 100644
--- a/fern/products/docs/pages/component-library/writing-content/markdown.mdx
+++ b/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.

From 6340f8a3aa6517ac1e2fdfa29926381f8e160317 Mon Sep 17 00:00:00 2001
From: Devin Logan <devinannlogan@gmail.com>
Date: Wed, 5 Nov 2025 16:39:25 -0500
Subject: [PATCH 4/8] refactor docs

---
 fern/docs.yml                                 |   2 +
 fern/products/docs/docs.yml                   |   6 +-
 .../default-components/download.mdx           |  34 +++++
 .../default-components/embed.mdx              | 127 ------------------
 .../writing-content/markdown.mdx              |  32 ++---
 5 files changed, 55 insertions(+), 146 deletions(-)
 create mode 100644 fern/products/docs/pages/component-library/default-components/download.mdx
 delete mode 100644 fern/products/docs/pages/component-library/default-components/embed.mdx

diff --git a/fern/docs.yml b/fern/docs.yml
index c6e6601f4..67fa87672 100644
--- a/fern/docs.yml
+++ b/fern/docs.yml
@@ -308,6 +308,8 @@ redirects:
     destination: /learn/docs/writing-content/components/accordions
   - source: /learn/docs/writing-content/components/card-groups
     destination: /learn/docs/writing-content/components/cards
+  - source: /learn/docs/writing-content/components/embed
+    destination: /learn/docs/writing-content/components/download
   - source: /learn/docs/building-and-customizing-your-docs/navigation
     destination: /learn/docs/configuration/navigation
   - source: /learn/docs/navigation/overview
diff --git a/fern/products/docs/docs.yml b/fern/products/docs/docs.yml
index c46be377c..469c88223 100644
--- a/fern/products/docs/docs.yml
+++ b/fern/products/docs/docs.yml
@@ -64,9 +64,9 @@ navigation:
             path: ./pages/component-library/default-components/code-blocks.mdx
             icon: fa-duotone fa-code
             slug: code-blocks
-          - page: Embed
-            path: ./pages/component-library/default-components/embed.mdx
-            icon: fa-duotone fa-window-restore
+          - page: Download
+            path: ./pages/component-library/default-components/download.mdx
+            icon: fa-duotone fa-download
           - page: Endpoint request snippet
             path: ./pages/component-library/default-components/endpoint-request-snippet.mdx
             icon: fa-duotone fa-arrow-up
diff --git a/fern/products/docs/pages/component-library/default-components/download.mdx b/fern/products/docs/pages/component-library/default-components/download.mdx
new file mode 100644
index 000000000..9a939f09f
--- /dev/null
+++ b/fern/products/docs/pages/component-library/default-components/download.mdx
@@ -0,0 +1,34 @@
+---
+title: "Download"
+description: "Download assets like PDFs directly from your documentation"
+---
+
+The `<Download>` component lets users download assets like PDFs directly from your documentation.
+
+## Usage
+
+<div className="highlight-frame">
+<Download src="./all-about-ferns.pdf">
+  <Button intent="primary">Download PDF</Button>
+</Download>
+</div>
+
+```jsx Markdown
+<Download src="./all-about-ferns.pdf">
+  <Button intent="primary">Download PDF</Button>
+</Download>
+```
+
+## Properties
+
+<ParamField path="src" type="string" required={true}>
+  Path to your local asset (relative to current MDX file). The asset must be located within the `fern` folder.
+</ParamField>
+
+<ParamField path="children" type="React.ReactNode" required={true}>
+  The text or element to display as the click target for the download.
+</ParamField>
+
+<ParamField path="filename" type="string">
+  The filename to use for the downloaded asset. If not provided, the filename will be the same as the asset's name.
+</ParamField>
diff --git a/fern/products/docs/pages/component-library/default-components/embed.mdx b/fern/products/docs/pages/component-library/default-components/embed.mdx
deleted file mode 100644
index 0d2946cf3..000000000
--- a/fern/products/docs/pages/component-library/default-components/embed.mdx
+++ /dev/null
@@ -1,127 +0,0 @@
----
-title: "Embedded assets and files"
-description: "Embed local assets like PDFs, videos, and more in your documentation"
----
-
-Embed local assets like PDFs, videos, and other media directly in your documentation using native HTML5 tags. This allows you to include rich content without relying on external hosting.
-
-<Info title="Supported tags">
-  Fern supports using the `<embed src="..." />` tag to embed [external content](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/embed) and the `<source src="..." />` tag to embed [media or image sources](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/source).
-</Info>
-
-
-## 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>
-
-```jsx Markdown
-<embed src="./growing-fern.mp4" type="video/mp4" style={{ aspectRatio: '16 / 9', width: '100%' }} />
-```
-
-## Variants
-
-### Video file with video tag
-
-<Note>
-  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">
-<video style={{ aspectRatio: '16 / 9', width: '100%' }} controls>
-  <source src="./growing-fern.mp4" type="video/mp4" />
-</video>
-</div>
-
-```jsx Markdown
-<video style={{ aspectRatio: '16 / 9', width: '100%' }} controls>
-  <source src="./growing-fern.mp4" type="video/mp4" />
-</video>
-```
-
-### 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>
-
-```jsx Markdown
-<embed src="./all-about-ferns.pdf" type="application/pdf" width="100%" height="500px" />
-```
-
-## Downloadable assets
-
-<div className="highlight-frame">
-<Download src="./all-about-ferns.pdf">
-  <Button intent="primary">Download PDF</Button>
-</Download>
-</div>
-
-```jsx Markdown
-<Download src="./all-about-ferns.pdf">
-  <Button intent="primary">Download PDF</Button>
-</Download>
-```
-
-## Properties
-
-<ParamField path="src" type="string" required={true}>
-  Path to your local asset (relative to current MDX file)
-</ParamField>
-
-<ParamField path="type" type="string" required={true}>
-  MIME type of the asset (e.g. 'video/mp4', 'application/pdf')
-
-  <Accordion title="Common MIME types">
-
-  | File Type  | MIME Type         |
-  | ---------- | ----------------- |
-  | PDF        | `application/pdf` |
-  | MP4 Video  | `video/mp4`       |
-  | WebM Video | `video/webm`      |
-  | SVG Image  | `image/svg+xml`   |
-  | PNG Image  | `image/png`       |
-  | JPEG Image | `image/jpeg`      |
-
-  <Note>
-    The supported file types and behavior may vary depending on the browser and the type of content being embedded. For
-    video files, consider using MP4 format for maximum compatibility.
-  </Note>
-  </Accordion>
-</ParamField>
-
-### Downloadable asset properties
-
-Enable users to download assets from within your documentation, instead of linking to them, by using the `<Download>` component.
-
-<ParamField path="src" type="string" required={true}>
-  Path to your local asset (relative to current MDX file). The asset must be located within the `fern` folder.
-</ParamField>
-
-<ParamField path="children" type="React.ReactNode" required={true}>
-  The text or element to display as the click target for the download.
-</ParamField>
-
-<ParamField path="filename" type="string">
-  The filename to use for the downloaded asset. If not provided, the filename will be the same as the asset's name.
-</ParamField>
-
-<br />
-<br />
diff --git a/fern/products/docs/pages/component-library/writing-content/markdown.mdx b/fern/products/docs/pages/component-library/writing-content/markdown.mdx
index 3308b926c..5aaa32e5f 100644
--- a/fern/products/docs/pages/component-library/writing-content/markdown.mdx
+++ b/fern/products/docs/pages/component-library/writing-content/markdown.mdx
@@ -67,7 +67,7 @@ Read the [Introduction](/learn/overview/introduction).
 
 ## Images
 
-You can use locally stored images or URLs to include images in your Markdown pages. Use either [Markdown syntax](https://www.markdownguide.org/basic-syntax/#images-1) or the [`<img>` HTML tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img) to insert the image.
+You can use locally stored images or URLs to include images in your Markdown pages. Use either [Markdown syntax](https://www.markdownguide.org/basic-syntax/#images-1) or the [`<img>` HTML tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img) to insert the image. Don't use the `<embed>` element, as it has inconsistent browser support.
 
 <Info title="Image paths">
   You can reference images using paths relative to the page's location (using `./` or `../`) or relative to the `fern` folder root (using `/`). For example, an image at `fern/assets/images/logo.png` can be referenced from any page as `/assets/images/logo.png`.
@@ -108,26 +108,26 @@ Common image attributes:
 For more details about the HTML image element and its attributes, see the [MDN documentation on the img element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img).
 </Note>
 
-## Embedding local assets
+## PDFs
 
-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.
+Embed PDFs using the `<iframe>` element. Don't use the `<embed>` element, as it has inconsistent browser support.
 
-<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
-<video src="./path/to/asset.mp4" controls />
+<Tabs>
+<Tab title="Rendered video">
+<iframe src="./all-about-ferns.pdf" width="100%" height="500px" style={{ border: 'none', borderRadius: '0.5rem' }} />
+</Tab>
+<Tab title="HTML">
+```html
+<iframe src="./all-about-ferns.pdf" width="100%" height="500px" style={{ border: 'none', borderRadius: '0.5rem' }} />
 ```
+</Tab>
+</Tabs>
+
+## Videos
 
 ### 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.
+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. Don't use the `<embed>` element, as it has inconsistent browser support.
 
 <Markdown src="/snippets/html-video-syntax-callout.mdx" />
 
@@ -194,7 +194,7 @@ Common video attributes:
 For more details about the HTML video element and its attributes, see the [MDN documentation on the video element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video).
 </Note>
 
-## Embed YouTube or Loom videos
+### Embed YouTube or Loom videos
 
 You can embed videos from YouTube, Loom, Vimeo, and other streaming platforms using an `<iframe>` element.
 

From d954a43ebd9e552ffd9cedc4795d3520d97a1258 Mon Sep 17 00:00:00 2001
From: Devin Logan <devinannlogan@gmail.com>
Date: Wed, 5 Nov 2025 16:50:30 -0500
Subject: [PATCH 5/8] fix image path and redirect

---
 fern/docs.yml                                                 | 2 +-
 .../docs/pages/component-library/writing-content/markdown.mdx | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/fern/docs.yml b/fern/docs.yml
index a8e5d62c5..654163f44 100644
--- a/fern/docs.yml
+++ b/fern/docs.yml
@@ -303,7 +303,7 @@ redirects:
     destination: /learn/docs/writing-content/components/accordions
   - source: /learn/docs/writing-content/components/card-groups
     destination: /learn/docs/writing-content/components/cards
-  - source: /learn/docs/writing-content/components/embed
+  - source: /learn/docs/writing-content/components/download
     destination: /learn/docs/writing-content/components/download
   - source: /learn/docs/building-and-customizing-your-docs/navigation
     destination: /learn/docs/configuration/navigation
diff --git a/fern/products/docs/pages/component-library/writing-content/markdown.mdx b/fern/products/docs/pages/component-library/writing-content/markdown.mdx
index 5aaa32e5f..e0e8cd264 100644
--- a/fern/products/docs/pages/component-library/writing-content/markdown.mdx
+++ b/fern/products/docs/pages/component-library/writing-content/markdown.mdx
@@ -114,11 +114,11 @@ Embed PDFs using the `<iframe>` element. Don't use the `<embed>` element, as it
 
 <Tabs>
 <Tab title="Rendered video">
-<iframe src="./all-about-ferns.pdf" width="100%" height="500px" style={{ border: 'none', borderRadius: '0.5rem' }} />
+<iframe src="../default-components/all-about-ferns.pdf" width="100%" height="500px" style={{ border: 'none', borderRadius: '0.5rem' }} />
 </Tab>
 <Tab title="HTML">
 ```html
-<iframe src="./all-about-ferns.pdf" width="100%" height="500px" style={{ border: 'none', borderRadius: '0.5rem' }} />
+<iframe src="../default-components/all-about-ferns.pdf" width="100%" height="500px" style={{ border: 'none', borderRadius: '0.5rem' }} />
 ```
 </Tab>
 </Tabs>

From bc6725ae81ec1d1cd6d0ae2e40e2abd514b58a3d Mon Sep 17 00:00:00 2001
From: Devin Logan <devinannlogan@gmail.com>
Date: Wed, 5 Nov 2025 16:57:12 -0500
Subject: [PATCH 6/8] update component overview page

---
 .../component-library/default-components/overview.mdx     | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/fern/products/docs/pages/component-library/default-components/overview.mdx b/fern/products/docs/pages/component-library/default-components/overview.mdx
index b71c659fa..8e04b2f66 100644
--- a/fern/products/docs/pages/component-library/default-components/overview.mdx
+++ b/fern/products/docs/pages/component-library/default-components/overview.mdx
@@ -63,11 +63,11 @@ Fern includes 20 built-in components for creating interactive documentation. Sel
     Code examples with syntax highlighting and interactive features
   </Card>
   <Card
-    title="Embed"
-    icon="fa-duotone fa-window-restore"
-    href="/docs/writing-content/components/embed"
+    title="Download"
+    icon="fa-duotone fa-download"
+    href="/docs/writing-content/components/download"
   >
-    Embedded local assets like PDFs, videos, and other media
+    Download PDFs and other assets
   </Card>
   <Card
     title="Endpoint request snippet"

From de5d7c1f194aa08c23e1d6b7f529288e6621d2ce Mon Sep 17 00:00:00 2001
From: Devin Logan <devinannlogan@gmail.com>
Date: Wed, 5 Nov 2025 17:05:20 -0500
Subject: [PATCH 7/8] fix redirect

---
 fern/docs.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/fern/docs.yml b/fern/docs.yml
index 654163f44..a8e5d62c5 100644
--- a/fern/docs.yml
+++ b/fern/docs.yml
@@ -303,7 +303,7 @@ redirects:
     destination: /learn/docs/writing-content/components/accordions
   - source: /learn/docs/writing-content/components/card-groups
     destination: /learn/docs/writing-content/components/cards
-  - source: /learn/docs/writing-content/components/download
+  - source: /learn/docs/writing-content/components/embed
     destination: /learn/docs/writing-content/components/download
   - source: /learn/docs/building-and-customizing-your-docs/navigation
     destination: /learn/docs/configuration/navigation

From 069c4fb8a870b4fa2052a3524c86287a850775b0 Mon Sep 17 00:00:00 2001
From: Devin Logan <devinannlogan@gmail.com>
Date: Wed, 5 Nov 2025 17:23:53 -0500
Subject: [PATCH 8/8] add callout pointer to embed info

---
 .../pages/component-library/default-components/download.mdx   | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/fern/products/docs/pages/component-library/default-components/download.mdx b/fern/products/docs/pages/component-library/default-components/download.mdx
index 9a939f09f..bbd76590b 100644
--- a/fern/products/docs/pages/component-library/default-components/download.mdx
+++ b/fern/products/docs/pages/component-library/default-components/download.mdx
@@ -5,6 +5,10 @@ description: "Download assets like PDFs directly from your documentation"
 
 The `<Download>` component lets users download assets like PDFs directly from your documentation.
 
+<Info>
+For information on how to embed assets, check out the documentation on [Images](/learn/docs/writing-content/markdown#images), [PDFs](/learn/docs/writing-content/markdown#pdfs), and [Videos](/learn/docs/writing-content/markdown#videos).
+</Info>
+
 ## Usage
 
 <div className="highlight-frame">