diff --git a/clis/docs-migrator/package.json b/clis/docs-migrator/package.json
index bb16358155..82f3517a2a 100644
--- a/clis/docs-migrator/package.json
+++ b/clis/docs-migrator/package.json
@@ -30,6 +30,7 @@
   "dependencies": {
     "@fern-fern/docs-config": "^0.22.0",
     "@fern-ui/core-utils": "workspace:*",
+    "@fern-api/fdr-sdk": "workspace:*",
     "execa": "^5.1.1",
     "gray-matter": "^4.0.3",
     "lodash-es": "^4.17.21",
diff --git a/clis/docs-migrator/src/fern.ts b/clis/docs-migrator/src/fern.ts
index bcb1d4d67e..9193527ccd 100644
--- a/clis/docs-migrator/src/fern.ts
+++ b/clis/docs-migrator/src/fern.ts
@@ -1,3 +1,5 @@
+import { DocsV1Read } from "@fern-api/fdr-sdk";
+
 /**
  * The layout used for guides. This is the default layout.
  * Guides are typically long-form content that is meant to be read from start to finish.
@@ -47,7 +49,7 @@ export interface FernDocsFrontmatter {
     /**
      * The URL to the page's image. This is used for the <meta property="og:image"> tag in the HTML.
      */
-    image?: string;
+    image?: string | DocsV1Read.FileIdOrUrl;
 
     /**
      * Full slug of the page.
diff --git a/clis/docs-migrator/src/index.ts b/clis/docs-migrator/src/index.ts
index a2fe763fa6..60eb5a2684 100644
--- a/clis/docs-migrator/src/index.ts
+++ b/clis/docs-migrator/src/index.ts
@@ -243,12 +243,14 @@ export class MigrateFromMintlify {
                 content,
             };
         }
+
         return {
             path: mintlify.path,
             data: {
                 title: data.title,
                 subtitle: data.description,
                 layout: data.mode != null ? "reference" : undefined,
+                // TODO: (rohin) investigate this more; it seems like mintlify isn't reliant on fdr, so not sure if there's a transformation here.
                 image: data["og:image"],
                 slug,
             },
diff --git a/packages/ui/app/src/mdx/frontmatter.ts b/packages/ui/app/src/mdx/frontmatter.ts
index bdee655378..a594acd1f3 100644
--- a/packages/ui/app/src/mdx/frontmatter.ts
+++ b/packages/ui/app/src/mdx/frontmatter.ts
@@ -72,7 +72,7 @@ export interface FernDocsFrontmatter extends DocsV1Read.MetadataConfig {
     /**
      * The URL to the page's image. This is used for the <meta property="og:image"> tag in the HTML.
      */
-    image?: string;
+    image?: string | DocsV1Read.FileIdOrUrl;
 
     /**
      * Renders an "Edit this page" link at the bottom of the page.
diff --git a/packages/ui/app/src/next-app/utils/getSeoProp.ts b/packages/ui/app/src/next-app/utils/getSeoProp.ts
index 396cbdc7ab..9824114b95 100644
--- a/packages/ui/app/src/next-app/utils/getSeoProp.ts
+++ b/packages/ui/app/src/next-app/utils/getSeoProp.ts
@@ -64,9 +64,32 @@ export function getSeoProps(
             const { data: frontmatter } = getFrontmatter(page.markdown);
             ogMetadata = { ...ogMetadata, ...frontmatter };
 
-            // retrofit og:image
-            if (frontmatter.image != null) {
-                ogMetadata["og:image"] ??= { type: "url", value: frontmatter.image };
+            // retrofit og:image, preferring og:image
+            // TODO: (rohin) Come back here and support more image transformations (twitter, logo, etc)
+            for (const frontmatterImageVar of [frontmatter.image, frontmatter["og:image"]]) {
+                if (frontmatterImageVar != null) {
+                    // TODO: (rohin) remove string check when fully migrated, but keeping for back compat
+                    if (typeof frontmatterImageVar === "string") {
+                        ogMetadata["og:image"] ??= {
+                            type: "url",
+                            value: frontmatterImageVar,
+                        };
+                    } else {
+                        visitDiscriminatedUnion(frontmatterImageVar, "type")._visit({
+                            fileId: (fileId) => {
+                                const realId = fileId.value.split(":")[1];
+                                if (realId != null) {
+                                    fileId.value = realId;
+                                    ogMetadata["og:image"] = fileId;
+                                }
+                            },
+                            url: (url) => {
+                                ogMetadata["og:image"] = url;
+                            },
+                            _other: undefined,
+                        });
+                    }
+                }
             }
 
             seo.title ??= frontmatter.title;
diff --git a/packages/ui/docs-bundle/src/pages/api/fern-docs/changelog.ts b/packages/ui/docs-bundle/src/pages/api/fern-docs/changelog.ts
index beb648917e..e9bac05682 100644
--- a/packages/ui/docs-bundle/src/pages/api/fern-docs/changelog.ts
+++ b/packages/ui/docs-bundle/src/pages/api/fern-docs/changelog.ts
@@ -112,7 +112,8 @@ function toFeedItem(
         try {
             let image: string | undefined;
 
-            if (frontmatter.image != null) {
+            // TODO: (rohin) Clean up after safe deploy, but include for back compat
+            if (frontmatter.image != null && typeof frontmatter.image === "string") {
                 image = frontmatter.image;
             } else if (frontmatter["og:image"] != null) {
                 image = toUrl(frontmatter["og:image"], files);
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index ea523a35d2..fd747055c6 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -175,6 +175,9 @@ importers:
 
   clis/docs-migrator:
     dependencies:
+      '@fern-api/fdr-sdk':
+        specifier: workspace:*
+        version: link:../../packages/fdr-sdk
       '@fern-fern/docs-config':
         specifier: ^0.22.0
         version: 0.22.0