feat(richtext-lexical): add markdown transformer for upload nodes (#15630)

## Problem

When converting Lexical rich text content to markdown using
`convertLexicalToMarkdown`, upload nodes (images and files) are
completely stripped from the output. There's no markdown transformer
registered for the upload feature, so the converter silently drops them.

This means any content that includes uploaded images loses those images
entirely when exported to markdown - which is unexpected since other
node types like links, headings, and horizontal rules all have proper
markdown transformers.

## Fix

Added an `ElementTransformer` for upload nodes that handles three cases:

1. **Populated image uploads** - outputs standard markdown image syntax:
   ```
   ![alt text](/uploads/image.jpg)
   ```

2. **Populated non-image uploads** (PDFs, docs, etc.) - outputs a link:
   ```
   [document.pdf](/uploads/document.pdf)
   ```

3. **Non-populated uploads** (value is just an ID) - outputs a reference
placeholder so the data isn't silently lost:
   ```
   ![media:abc123]()
   ```

The transformer is registered in the `UploadFeature` server
configuration alongside the existing HTML converter.

The import side (markdown -> Lexical) uses a never-matching regex
because upload nodes should be created through the upload UI/drawer, not
parsed from markdown text.

## Test plan

- Verified that upload nodes with populated data (containing `url`,
`alt`, `filename`) produce valid markdown image syntax
- Verified that non-image uploads produce link syntax
- Verified that non-populated uploads produce a reference placeholder
instead of being dropped

Fixes #13086

---------

Co-authored-by: German Jablonski <43938777+GermanJablo@users.noreply.github.com>

Author: veeceey

packages/richtext-lexical/src/features/upload/server/index.ts

@@ -18,6 +18,7 @@ import { createServerFeature } from '../../../utilities/createServerFeature.js'
 import { createNode } from '../../typeUtilities.js'
 import { uploadPopulationPromiseHOC } from './graphQLPopulationPromise.js'
 import { i18n } from './i18n.js'
+import { UploadMarkdownTransformer } from './markdownTransformer.js'
 import { UploadServerNode } from './nodes/UploadNode.js'
 import { uploadValidation } from './validate.js'
 
@@ -130,6 +131,7 @@ export const UploadFeature = createServerFeature<
         return schemaMap
       },
       i18n,
+      markdownTransformers: [UploadMarkdownTransformer],
       nodes: [
         createNode({
           converters: {

packages/richtext-lexical/src/features/upload/server/markdownTransformer.ts

@@ -0,0 +1,68 @@
+import type { ElementTransformer } from '../../../packages/@lexical/markdown/MarkdownTransformers.js'
+
+import {
+  $createUploadServerNode,
+  $isUploadServerNode,
+  UploadServerNode,
+} from './nodes/UploadNode.js'
+
+/** Matches upload placeholder written by export: ![relationTo:id]() */
+const UPLOAD_PLACEHOLDER_REGEX = /!\[([^\]:]+):([^\]]+)\]\(\)/
+
+export const UploadMarkdownTransformer: ElementTransformer = {
+  type: 'element',
+  dependencies: [UploadServerNode],
+  export: (node) => {
+    if (!$isUploadServerNode(node)) {
+      return null
+    }
+
+    const data = node.getData()
+    const value = data?.value
+
+    // When the value is a populated document object (not just an ID),
+    // we can extract the URL and alt text
+    if (value && typeof value === 'object' && 'url' in value) {
+      const url = (value as Record<string, unknown>).url as string
+      const alt =
+        (data.fields as Record<string, unknown>)?.alt ||
+        (value as Record<string, unknown>).alt ||
+        (value as Record<string, unknown>).filename ||
+        ''
+
+      if ((value as Record<string, unknown>).mimeType) {
+        const mimeType = (value as Record<string, unknown>).mimeType as string
+        // For non-image uploads, output a link instead of an image
+        if (!mimeType.startsWith('image')) {
+          const filename = ((value as Record<string, unknown>).filename as string) || url
+          return `[${filename}](${url})`
+        }
+      }
+
+      return `![${alt}](${url})`
+    }
+
+    // When value is just an ID (not populated), output a reference placeholder
+    // so the upload is not silently dropped from the markdown output
+    const id = typeof value === 'object' ? (value as Record<string, string>)?.id : value
+    return `![${data.relationTo}:${id}]()`
+  },
+  regExp: UPLOAD_PLACEHOLDER_REGEX,
+  replace: (parentNode, _children, match, isImport) => {
+    if (!isImport || !match[1] || !match[2]) {
+      return false
+    }
+    const relationTo = match[1]
+    const value = match[2]
+    const id = /^\d+$/.test(value) ? Number(value) : value
+    const node = $createUploadServerNode({
+      data: {
+        fields: {},
+        relationTo,
+        value: id,
+      },
+    })
+    parentNode.replace(node)
+    return true
+  },
+}

test/lexical-mdx/int.spec.ts

@@ -177,6 +177,77 @@ describe('Lexical MDX', () => {
       })
     }
   }
+
+  describe('upload markdown: Markdown → Lexical (import)', () => {
+    function countUploadNodes(node: {
+      type?: string
+      children?: unknown[]
+      [key: string]: unknown
+    }): number {
+      let n = node.type === 'upload' ? 1 : 0
+      const children =
+        node.children ?? (node.fields as { root?: { children?: unknown[] } })?.root?.children
+      if (Array.isArray(children)) {
+        for (const c of children) {
+          n += countUploadNodes(c as typeof node)
+        }
+      }
+      return n
+    }
+
+    function collectUploadNodes(node: {
+      type?: string
+      relationTo?: string
+      value?: unknown
+      children?: unknown[]
+      [key: string]: unknown
+    }): { relationTo: string; value: unknown }[] {
+      const out: { relationTo: string; value: unknown }[] = []
+      if (node.type === 'upload' && node.relationTo != null) {
+        out.push({ relationTo: node.relationTo, value: node.value })
+      }
+      const children =
+        node.children ?? (node.fields as { root?: { children?: unknown[] } })?.root?.children
+      if (Array.isArray(children)) {
+        for (const c of children) {
+          out.push(...collectUploadNodes(c as typeof node))
+        }
+      }
+      return out
+    }
+
+    it('imports upload placeholder as upload node and verifies it is there', () => {
+      const markdown = '![uploads:123]()'
+      const result = mdxToEditorJSON({ mdxWithFrontmatter: markdown, editorConfig })
+      const rootChildren = result.editorState.root?.children ?? []
+      const uploads = rootChildren.flatMap((child) =>
+        collectUploadNodes(
+          child as { type?: string; relationTo?: string; value?: unknown; [key: string]: unknown },
+        ),
+      )
+      expect(uploads).toHaveLength(1)
+      expect(uploads[0].relationTo).toBe('uploads')
+      expect(uploads[0].value).toBe(123)
+    })
+
+    it('imports image markdown without creating upload node and preserves content', () => {
+      const markdown = '![alt](/uploads/image.jpg)'
+      const result = mdxToEditorJSON({ mdxWithFrontmatter: markdown, editorConfig })
+      const rootChildren = result.editorState.root?.children ?? []
+      expect(rootChildren.length).toBeGreaterThanOrEqual(1)
+      const uploadCount = rootChildren.reduce(
+        (sum, child) =>
+          sum +
+          countUploadNodes(
+            child as { type?: string; children?: unknown[]; [key: string]: unknown },
+          ),
+        0,
+      )
+      expect(uploadCount).toBe(0)
+      const text = JSON.stringify(result.editorState)
+      expect(text).toMatch(/alt|image\.jpg|\/uploads\//)
+    })
+  })
 })
 
 function removeUndefinedAndIDRecursively(obj: object) {

test/lexical/lexical.int.spec.ts

@@ -293,6 +293,51 @@ describe('Lexical', () => {
     )
   })
 
+  describe('upload markdown: Lexical → Markdown (export)', () => {
+    it('exports upload node to markdown placeholder when unpopulated', async () => {
+      const newLexicalDoc = await payload.create({
+        collection: lexicalFieldsSlug,
+        depth: 0,
+        data: {
+          title: 'Lexical Upload Markdown Unpopulated',
+          lexicalWithBlocks: {
+            root: {
+              type: 'root',
+              format: '',
+              indent: 0,
+              version: 1,
+              children: [
+                {
+                  format: '',
+                  type: 'upload',
+                  version: 2,
+                  relationTo: 'uploads',
+                  value: createdJPGDocID,
+                  fields: {},
+                },
+              ],
+              direction: 'ltr',
+            },
+          },
+        },
+      })
+
+      expect(newLexicalDoc.lexicalWithBlocks_markdown).toEqual(`![uploads:${createdJPGDocID}]()`)
+    })
+
+    it('exported markdown contains upload placeholder in seeded doc', async () => {
+      const lexicalDoc = await payload.find({
+        collection: lexicalFieldsSlug,
+        depth: 0,
+        where: { title: { equals: lexicalDocData.title } },
+      })
+
+      const markdown = lexicalDoc.docs[0]?.lexicalWithBlocks_markdown as string
+      expect(markdown).toBeDefined()
+      expect(markdown).toContain(`![uploads:${createdJPGDocID}]()`)
+    })
+  })
+
   describe('converters and migrations', () => {
     it('htmlConverter: should output correct HTML for top-level lexical field', async () => {
       const lexicalDoc: LexicalMigrateField = (