Discourage embed component usage for all asset types (#1721)

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: Colton Berry <coltonsberry@gmail.com>
Co-authored-by: Devin Logan <devinannlogan@gmail.com>

Author: 3 people

fern/docs.yml

@@ -303,6 +303,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

fern/products/docs/docs.yml

@@ -67,9 +67,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

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

@@ -0,0 +1,38 @@
+---
+title: "Download"
+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">
+<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>

fern/products/docs/pages/component-library/default-components/embed.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"

fern/products/docs/pages/component-library/default-components/overview.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,21 +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/content/components/embed). This is useful for displaying PDFs, images, videos, OpenAPI files, and other assets into your docs.
+Embed PDFs using the `<iframe>` element. Don't use the `<embed>` element, as it has inconsistent browser support.
 
-For example, to embed a video, use the following Markdown:
-
-```mdx
-<embed src="./path/to/asset.mp4" type="video/mp4" />
+<Tabs>
+<Tab title="Rendered video">
+<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="../default-components/all-about-ferns.pdf" width="100%" height="500px" style={{ border: 'none', borderRadius: '0.5rem' }} />
 ```
+</Tab>
+</Tabs>
 
-<embed src="./embed-fern-waving.mp4" type="video/mp4" width="640px" height="360px" />
+## 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" />
 
@@ -189,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.