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

.github/scripts/fern-scribe.js

@@ -1045,7 +1045,7 @@ Analyze this issue and discussion to:
 3. Suggest additional search terms that would find the right pages
 
 Be specific about page paths. For example:
-- If it's about images, suggest "/learn/docs/writing-content/markdown" (which covers images)
+- If it's about images, suggest "/learn/docs/writing-content/markdown-media" (which covers images)
 - If it's about API configuration, suggest specific product pages like "/learn/sdks/generators/[language]/configuration"
 - If it's about navigation features, suggest "/learn/docs/navigation/*" pages
 

.github/scripts/fern-url-mapper.js

@@ -396,7 +396,7 @@ class FernUrlMapper {
     if (testUrls.length === 0) {
       // Default test URLs
       testUrls = [
-        '/learn/docs/writing-content/markdown',
+        '/learn/docs/writing-content/markdown-basics',
         '/learn/sdks/generators/python/configuration',
         '/learn/openapi-definition/overlay-customizations'
       ];

.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

README.md

@@ -56,7 +56,7 @@ Keep the following principles in mind:
 - **Write in clear, concise language**, using [active voice](https://developers.google.com/style/voice) whenever possible. Keep sentences and paragraphs short and to the point. Be conversational and friendly tone. Stay away from jargon as much as you can.
 - **Use [Fern’s documentation components](https://buildwithfern.com/learn/docs/writing-content/components/overview)** whenever you can.
 - **When editing an existing page** - Match the existing heading structure, tone, and level of detail to ensure your changes integrate as seamlessly as possible.
-- **Use diagrams when it makes sense** – Show, don't tell! Use [Mermaid](https://buildwithfern.com/learn/docs/writing-content/markdown#diagrams), a Markdown-like diagramming syntax, to illustrate a workflow. 
+- **Use diagrams when it makes sense** – Show, don't tell! Use [Mermaid](https://buildwithfern.com/learn/docs/writing-content/markdown-media#diagrams), a Markdown-like diagramming syntax, to illustrate a workflow. 
 - [**Use sentence case**](https://developers.google.com/style/capitalization) for page and section headings. 
 
 > "Break any of these rules sooner than say anything outright barbarous."

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/changelog/2025-11-09.mdx

@@ -12,7 +12,7 @@ The new `<Files>` component creates visual file tree structures with expandable
   <Folder name="assets">
     <File name="styles.css" />
   </Folder>
-  <File name="markdown.mdx" href="/learn/docs/writing-content/markdown" />
+  <File name="markdown.mdx" href="/learn/docs/writing-content/markdown-basics" />
   <File name="README.md" />
 </Files>
 
@@ -29,7 +29,7 @@ The component consists of three parts: `<Files>` as the container, `<Folder>` fo
   <Folder name="assets">
     <File name="styles.css" />
   </Folder>
-  <File name="markdown.mdx" href="/learn/docs/writing-content/markdown" />
+  <File name="markdown.mdx" href="/learn/docs/writing-content/markdown-basics" />
   <File name="README.md" />
 </Files>
 ```

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/default-components/files.mdx

@@ -20,7 +20,7 @@ The component consists of three parts: `<Files>` as the container, `<Folder>` fo
   <Folder name="assets">
     <File name="styles.css" />
   </Folder>
-  <File name="markdown.mdx" href="/learn/docs/writing-content/markdown" />
+  <File name="markdown-basics.mdx" href="/learn/docs/writing-content/markdown-basics" />
   <File name="README.md" />
 </Files>
 </div>
@@ -36,7 +36,7 @@ The component consists of three parts: `<Files>` as the container, `<Folder>` fo
   <Folder name="assets">
     <File name="styles.css" />
   </Folder>
-  <File name="markdown.mdx" href="/learn/docs/writing-content/markdown" />
+  <File name="markdown-basics.mdx" href="/learn/docs/writing-content/markdown-basics" />
   <File name="README.md" />
 </Files>
 ```
@@ -65,7 +65,7 @@ You can nest folders within folders to create deep directory structures. The com
   <Folder name="assets">
     <File name="styles.css" />
   </Folder>
-  <File name="markdown.mdx" href="/learn/docs/writing-content/markdown" />
+  <File name="markdown-basics.mdx" href="/learn/docs/writing-content/markdown-basics" />
   <File name="README.md" />
 </Files>
 </div>
@@ -88,7 +88,7 @@ You can nest folders within folders to create deep directory structures. The com
   <Folder name="assets">
     <File name="styles.css" />
   </Folder>
-  <File name="markdown.mdx" href="/learn/docs/writing-content/markdown" />
+  <File name="markdown-basics.mdx" href="/learn/docs/writing-content/markdown-basics" />
   <File name="README.md" />
 </Files>
 ```
@@ -108,7 +108,7 @@ Add the `href` property to make files or folders clickable. This is useful for l
   <Folder name="assets">
     <File name="styles.css" href="https://github.com/fern-api/docs/blob/main/fern/assets/styles.css" />
   </Folder>
-  <File name="markdown.mdx" href="/learn/docs/writing-content/markdown" />
+  <File name="markdown-basics.mdx" href="/learn/docs/writing-content/markdown-basics" />
   <File name="README.md" href="https://github.com/fern-api/docs/blob/main/README.md" />
 </Files>
 </div>
@@ -124,7 +124,7 @@ Add the `href` property to make files or folders clickable. This is useful for l
   <Folder name="assets">
     <File name="styles.css" href="https://github.com/fern-api/docs/blob/main/fern/assets/styles.css" />
   </Folder>
-  <File name="markdown.mdx" href="/learn/docs/writing-content/markdown" />
+  <File name="markdown-basics.mdx" href="/learn/docs/writing-content/markdown-basics" />
   <File name="README.md" href="https://github.com/fern-api/docs/blob/main/README.md" />
 </Files>
 ```
@@ -144,7 +144,7 @@ Use the `defaultOpen` property to have specific folders expanded when the page l
   <Folder name="assets">
     <File name="styles.css" />
   </Folder>
-  <File name="markdown.mdx" href="/learn/docs/writing-content/markdown" />
+  <File name="markdown-basics.mdx" href="/learn/docs/writing-content/markdown-basics" />
   <File name="README.md" />
 </Files>
 </div>
@@ -160,7 +160,7 @@ Use the `defaultOpen` property to have specific folders expanded when the page l
   <Folder name="assets">
     <File name="styles.css" />
   </Folder>
-  <File name="markdown.mdx" href="/learn/docs/writing-content/markdown" />
+  <File name="markdown-basics.mdx" href="/learn/docs/writing-content/markdown-basics" />
   <File name="README.md" />
 </Files>
 ```

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

fern/products/docs/pages/resources/stainless-comparison.mdx

@@ -39,7 +39,7 @@ Stainless uses Git-based workflows for all content authoring. Fern supports both
 | Feature | Fern Docs | Stainless Docs |
 |---------|-----------|----------------|
 | **Visual editor** | ✅ [Fern Editor](/learn/docs/writing-content/fern-editor) with GitHub App integration | ❌ None |
-| **Content format** | ✅ [MDX](/learn/docs/writing-content/markdown) with React components | ✅ MDX/Markdoc |
+| **Content format** | ✅ [MDX](/learn/docs/writing-content/markdown-basics) with React components | ✅ MDX/Markdoc |
 | **Reusable content** | ✅ [Snippets system](/learn/docs/writing-content/reusable-snippets) | ✅ Markdown partials |
 <br/>
 </Accordion>