(docs) Split Markdown page into separate basics and rich media guides

.vale/styles/FernStyles/Acronyms.yml

@@ -101,3 +101,4 @@ exceptions:
   - SSR
   - SSG
   - REST
+  - MDN

.vale/styles/FernStyles/Headings.yml

@@ -80,3 +80,5 @@ exceptions:
   - fern.config.json
   - Font Awesome
   - MCP
+  - LaTeX
+  - MDN

fern/docs.yml

@@ -343,7 +343,9 @@ redirects:
     destination: /learn/docs/customization/search
 
   - source: /learn/docs/content/write-markdown
-    destination: /learn/docs/writing-content/markdown
+    destination: /learn/docs/writing-content/markdown-basics
+  - source: /learn/docs/writing-content/markdown
+    destination: /learn/docs/writing-content/markdown-basics
   - source: /learn/docs/content/components/:slug*
     destination: /learn/docs/writing-content/components/:slug*
   - source: /learn/docs/content/custom-react-components
@@ -566,7 +568,7 @@ redirects:
   - source: /learn/docs/content/visual-editor
     destination: /learn/docs/writing-content/fern-editor
   - source: /learn/docs/content
-    destination: /learn/docs/writing-content/markdown
+    destination: /learn/docs/writing-content/markdown-basics
   - source: /learn/docs/config/overview
     destination: /learn/docs/configuration/site-level-settings
   - source: /learn/docs/llms.txt8

fern/products/docs/docs.yml

@@ -30,9 +30,12 @@ navigation:
         path: ./pages/customization/frontmatter.mdx
   - section: Writing content
     contents:
-      - page: Markdown pages
-        path: ./pages/component-library/writing-content/markdown.mdx
-        slug: markdown
+      - page: Markdown basics
+        path: ./pages/component-library/writing-content/markdown-basics.mdx
+        slug: markdown-basics
+      - page: Rich media in Markdown
+        path: ./pages/component-library/writing-content/markdown-media.mdx
+        slug: markdown-media
       - section: Components
         contents:
           - page: Overview

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

@@ -6,7 +6,7 @@ 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).
+For information on how to embed images, PDFs, and other assets, check out the documentation on [Rich media in Markdown](/learn/docs/writing-content/markdown-media).
 </Info>
 
 ## Usage

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

@@ -0,0 +1,68 @@
+---
+title: Markdown basics
+description: Use Markdown and MDX to add content to your Fern documentation site, including headers, components, and links.
+---
+
+Learn how to use Markdown and MDX to add content to your documentation, including headers, components, and links.
+
+<Note title="Terminology">
+Throughout this documentation, "Markdown" refers to both Markdown and MDX. [MDX](https://mdxjs.com/) is a version of Markdown, extended to allow the use of JSX components.
+</Note>
+
+## Add Markdown or MDX pages
+
+Add pages manually to your documentation by creating Markdown (`.md`) or MDX (`.mdx`) files. New to Markdown? See [Markdown Guide: Getting started](https://www.markdownguide.org/getting-started/).
+
+Place your pages inside your `fern/` folder and link to them from your [navigation settings](/learn/docs/building-your-docs/navigation) in the `docs.yml` file.
+
+In the example below, the MDX files are inside a folder named `pages/`.
+
+<CodeBlock title='Example folder structure'>
+```bash
+fern/
+├─ fern.config.json
+├─ docs.yml
+└─ pages/
+  ├─ welcome.mdx
+  └─ quickstart.mdx
+```
+</CodeBlock>
+
+<CodeBlock title='docs.yml'>
+```yml
+navigation:
+  - section: Overview
+    contents:
+      - page: Welcome
+        path: ./pages/welcome.mdx
+      - page: Quickstart
+        path: ./pages/quickstart.mdx
+```
+</CodeBlock>
+
+## Page header
+
+Fern automatically generates the `<h1>` page header for each page from `docs.yml`. For example, here's the `docs.yml` entry that maps the page you are reading now:
+```yml
+          - page: Write Markdown content
+            path: ./docs/pages/fern-docs/content/write-markdown.mdx
+```
+The value for `page` is used as the content of the top `<h1>` element of this page. Thus, when adding content to your Markdown pages, begin with `<h2>` instead of `<h1>`.
+
+## Fern components
+
+Fern has a built-in component library you can use in Markdown. [Explore the components.](/learn/docs/content/components/overview)
+
+## Links in Markdown
+
+### Link target
+When clicked, links to relative URLs open in the same tab, whereas links to absolute URLs open in a new browser tab.
+
+### Link format
+Use a `/` character to begin a relative URL to another page on your docs site. This routes to the `url` defined in your `docs.yml` file, such as `example-docs.buildwithfern.com`. For example, if you want to link to `https://example-docs.buildwithfern.com/overview/introduction`, you can write the link in Markdown as follows:
+
+<CodeBlock title='Relative link example'>
+```mdx
+Read the [Introduction](/learn/overview/introduction).
+```
+</CodeBlock>

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

@@ -1,69 +1,9 @@
 ---
-title: Write docs content using Markdown
-description: Use Markdown and MDX to add content to your Fern documentation site, including Fern's built-in component library.
+title: Rich media in Markdown
+description: Embed images, videos, PDFs, LaTeX equations, and diagrams in your Fern documentation.
 ---
 
-## Add Markdown or MDX pages
-
-Add pages manually to your documentation by creating Markdown (`.md`) or MDX (`.mdx`) files.New to Markdown? See [Markdown Guide: Getting started](https://www.markdownguide.org/getting-started/). 
-
-<Note>
-NOTE: Throughout our documentation, we refer to both Markdown and MDX as Markdown. [MDX](https://mdxjs.com/) is a version of Markdown, extended to allow the use of JSX components.
-</Note>
-
-Place your pages inside your `fern/` folder and link to them from your [navigation settings](/learn/docs/building-your-docs/navigation) in the `docs.yml` file.
-
-In the example below, the MDX files are inside a folder named `pages/`.
-
-<CodeBlock title='Example folder structure'>
-```bash
-fern/
-├─ fern.config.json
-├─ docs.yml
-└─ pages/
-  ├─ welcome.mdx
-  └─ quickstart.mdx
-```
-</CodeBlock>
-
-<CodeBlock title='docs.yml'>
-```yml
-navigation:
-  - section: Overview
-    contents: 
-      - page: Welcome 
-        path: ./pages/welcome.mdx
-      - page: Quickstart
-        path: ./pages/quickstart.mdx
-```
-</CodeBlock>
-
-## Page header
-
-Fern automatically generates the `<h1>` page header for each page from `docs.yml`. For example, here's the `docs.yml` entry that maps the page you are reading now:
-```yml
-          - page: Write Markdown content
-            path: ./docs/pages/fern-docs/content/write-markdown.mdx
-```
-The value for `page` is used as the content of the top `<h1>` element of this page. Thus, when adding content to your Markdown pages, begin with `<h2>` instead of `<h1>`.
-
-## Fern components
-
-Fern has a built-in component library you can use in Markdown. [Explore the components.](/learn/docs/content/components/overview)
-
-## Links in Markdown
-
-### Link target
-When clicked, links to relative URLs open in the same tab, whereas links to absolute URLs open in a new browser tab. 
-
-### Link format
-Use a `/` character to begin a relative URL to another page on your docs site. This routes to the `url` defined in your `docs.yml` file, such as `example-docs.buildwithfern.com`. For example, if you want to link to `https://example-docs.buildwithfern.com/overview/introduction`, you can write the link in Markdown as follows:
-
-<CodeBlock title='Relative link example'>
-```mdx
-Read the [Introduction](/learn/overview/introduction).
-```
-</CodeBlock>
+Enhance your documentation with rich media content including images, videos, PDFs, mathematical equations, and diagrams.
 
 ## Images
 
@@ -101,7 +41,7 @@ Common image attributes:
 | `src` | URL or path to the image file |
 | `alt` | Alternative text for accessibility |
 | `title` | Tooltip text shown on hover |
-| `width` and `height` | Dimensions of the image in pixels |
+| `width` and `height` | Dimensions of the image (px) |
 | `noZoom` | Disables image zoom functionality |
 
 <Note>
@@ -133,7 +73,7 @@ You can embed videos in your documentation using the HTML `<video>` tag. This gi
 
 <Tabs>
 <Tab title="Rendered video">
-<video 
+<video
     src="./embed-fern-waving.mp4"
     width="854"
     height="480"
@@ -146,7 +86,7 @@ You can embed videos in your documentation using the HTML `<video>` tag. This gi
 </Tab>
 <Tab title="HTML">
 ```html
-<video 
+<video
     src="path/to/your/video.mp4"
     width="854"
     height="480"
@@ -165,7 +105,7 @@ You can also wrap the video in a container div for additional styling:
 
 ```html
 <div class="card-video">
-    <video 
+    <video
         src="path/to/your/video.mp4"
         width="854"
         height="480"
@@ -248,7 +188,7 @@ $$
 $$
 
 ## Diagrams
-Fern supports creating diagrams within your Markdown using [Mermaid](https://mermaid.js.org/). Mermaid offers a variety of diagrams, including flowcharts, entity-relationship models, and Gantt charts. To include a Mermaid diagram in your Markdown file, create a codeblock marked with `mermaid`. 
+Fern supports creating diagrams within your Markdown using [Mermaid](https://mermaid.js.org/). Mermaid offers a variety of diagrams, including flowcharts, entity-relationship models, and Gantt charts. To include a Mermaid diagram in your Markdown file, create a codeblock marked with `mermaid`.
 
 ````markdown
 ```mermaid