[docs-infra] Remove redundant opengraph titles and descriptions (#953)

dav-is · web-flow · commit 1ff097fa93dd · 2025-12-12T18:01:38.000-05:00
diff --git a/packages/docs-infra/src/createSitemap/types.ts b/packages/docs-infra/src/createSitemap/types.ts
@@ -38,15 +38,9 @@ export interface SitemapPage {
   exports?: Record<string, SitemapExport>;
   tags?: string[];
   skipDetailSection?: boolean;
-  openGraph?: {
-    title?: string;
-    description?: string;
-    images?: Array<{
-      url: string;
-      width: number;
-      height: number;
-      alt: string;
-    }>;
+  image?: {
+    url: string;
+    alt?: string;
   };
 }
 
diff --git a/packages/docs-infra/src/pipeline/syncPageIndex/mergeMetadataMarkdown.test.ts b/packages/docs-infra/src/pipeline/syncPageIndex/mergeMetadataMarkdown.test.ts
@@ -413,20 +413,12 @@ Old description.
         {
           slug: 'button',
           path: './button/page.mdx',
-          title: 'Button',
-          description: 'New description with more details.',
+          title: 'Button Component',
+          description: 'A comprehensive button component.',
           keywords: ['interactive', 'input'],
-          openGraph: {
-            title: 'Button Component',
-            description: 'A comprehensive button component.',
-            images: [
-              {
-                url: 'https://example.com/button.png',
-                width: 800,
-                height: 600,
-                alt: 'Button preview',
-              },
-            ],
+          image: {
+            url: 'https://example.com/button.png',
+            alt: 'Button preview',
           },
         },
       ],
diff --git a/packages/docs-infra/src/pipeline/syncPageIndex/mergeMetadataMarkdown.ts b/packages/docs-infra/src/pipeline/syncPageIndex/mergeMetadataMarkdown.ts
@@ -130,12 +130,6 @@ export async function mergeMetadataMarkdown(
         skipDetailSection: existingPage.skipDetailSection,
         // Preserve sections from existing if new doesn't have them
         sections: newPage.sections || existingPage.sections,
-        // Merge openGraph, but ensure description comes from newPage if it has one
-        openGraph:
-          newPage.openGraph ??
-          (newPage.description
-            ? { ...existingPage.openGraph, description: newPage.description }
-            : existingPage.openGraph),
       };
       pages.push(merged);
       addedPaths.add(newPage.path);
diff --git a/packages/docs-infra/src/pipeline/syncPageIndex/metadataToMarkdown.test.ts b/packages/docs-infra/src/pipeline/syncPageIndex/metadataToMarkdown.test.ts
@@ -18,17 +18,9 @@ describe('metadataToMarkdown', () => {
           description: 'A button component.',
           keywords: ['interactive', 'input'],
           embeddings: [0.1, 0.2, 0.3],
-          openGraph: {
-            title: 'Button',
-            description: 'A button component.',
-            images: [
-              {
-                url: 'https://example.com/button.png',
-                width: 800,
-                height: 600,
-                alt: 'A simple button',
-              },
-            ],
+          image: {
+            url: 'https://example.com/button.png',
+            alt: 'A simple button',
           },
         },
       ],
@@ -155,31 +147,6 @@ describe('metadataToMarkdown', () => {
     expect(result).not.toContain('Keywords:');
   });
 
-  it('should prefer openGraph data over regular metadata', () => {
-    const data: PagesMetadata = {
-      title: 'Components',
-      pages: [
-        {
-          slug: 'button',
-          path: './button/page.mdx',
-          title: 'Regular Button',
-          description: 'Regular description',
-          openGraph: {
-            title: 'OpenGraph Button',
-            description: 'OpenGraph description',
-          },
-        },
-      ],
-    };
-
-    const result = metadataToMarkdown(data);
-
-    expect(result).toContain('- [OpenGraph Button](#button) - [Full Docs](./button/page.mdx)');
-    expect(result).toContain('## OpenGraph Button');
-    expect(result).not.toContain('Regular Button');
-    expect(result).not.toContain('Regular description');
-  });
-
   it('should include description below title', () => {
     const data: PagesMetadata = {
       title: 'Components',
@@ -353,15 +320,9 @@ describe('metadataToMarkdownAst', () => {
           path: './button/page.mdx',
           title: 'Button',
           description: 'A button component.',
-          openGraph: {
-            images: [
-              {
-                url: 'https://example.com/button.png',
-                width: 800,
-                height: 600,
-                alt: 'Button image',
-              },
-            ],
+          image: {
+            url: 'https://example.com/button.png',
+            alt: 'Button image',
           },
         },
       ],
@@ -458,8 +419,8 @@ A button component.
     expect(page?.description).toBe('A button component.');
     expect(page?.keywords).toEqual(['interactive', 'input']);
     expect(page?.embeddings).toEqual([0.1, 0.2, 0.3]);
-    expect(page?.openGraph?.images?.[0].url).toBe('https://example.com/button.png');
-    expect(page?.openGraph?.images?.[0].alt).toBe('A simple button');
+    expect(page?.image?.url).toBe('https://example.com/button.png');
+    expect(page?.image?.alt).toBe('A simple button');
   });
 
   it('should parse multiple pages', async () => {
@@ -510,7 +471,7 @@ A button component.
 
     const result = await markdownToMetadata(markdown);
 
-    expect(result?.pages[0].openGraph?.images).toBeUndefined();
+    expect(result?.pages[0]?.image).toBeUndefined();
   });
 
   it('should handle pages without keywords', async () => {
@@ -657,7 +618,7 @@ A more detailed button component description.
     // Detail section should override editable section
     expect(page?.description).toBe('A more detailed button component description.');
     expect(page?.keywords).toEqual(['interactive', 'clickable']);
-    expect(page?.openGraph?.images?.[0].url).toBe('https://example.com/button.png');
+    expect(page?.image?.url).toBe('https://example.com/button.png');
   });
 
   it('should correctly parse actual generated markdown format', async () => {
@@ -1059,17 +1020,9 @@ describe('round-trip conversion', () => {
           description: 'A button component.',
           keywords: ['interactive', 'input'],
           embeddings: [0.1, 0.2, 0.3, 0.4, 0.5],
-          openGraph: {
-            title: 'Button',
-            description: 'A button component.',
-            images: [
-              {
-                url: 'https://example.com/button.png',
-                width: 800,
-                height: 600,
-                alt: 'Button image',
-              },
-            ],
+          image: {
+            url: 'https://example.com/button.png',
+            alt: 'Button image',
           },
         },
         {
@@ -1098,9 +1051,7 @@ describe('round-trip conversion', () => {
     expect(parsed?.pages[0].description).toBe(original.pages[0].description);
     expect(parsed?.pages[0].keywords).toEqual(original.pages[0].keywords);
     expect(parsed?.pages[0].embeddings).toEqual(original.pages[0].embeddings);
-    expect(parsed?.pages[0].openGraph?.images?.[0].url).toBe(
-      original.pages[0].openGraph?.images?.[0].url,
-    );
+    expect(parsed?.pages[0].image?.url).toBe(original.pages[0].image?.url);
 
     // Check second component
     expect(parsed?.pages[1].slug).toBe(original.pages[1].slug);
diff --git a/packages/docs-infra/src/pipeline/syncPageIndex/metadataToMarkdown.ts b/packages/docs-infra/src/pipeline/syncPageIndex/metadataToMarkdown.ts
@@ -458,7 +458,7 @@ export function metadataToMarkdownAst(
   // Add page list (editable section) as proper list items
   const listItems: any[] = [];
   for (const page of pages) {
-    const pageTitle = page.openGraph?.title || page.title || page.slug;
+    const pageTitle = page.title || page.slug;
 
     // Check if this is a single-link entry (external link or no detail section)
     const isSingleLink = page.skipDetailSection || false;
@@ -516,12 +516,11 @@ export function metadataToMarkdownAst(
 
   // Add detailed page sections (non-editable)
   for (const page of pages) {
-    const pageTitle = page.openGraph?.title || page.title || page.slug;
+    const pageTitle = page.title || page.slug;
     // Note: We don't replace newlines here to allow natural line breaks in detailed sections
-    const description =
-      page.openGraph?.description || page.description || 'No description available';
+    const description = page.description || 'No description available';
     const keywords = page.keywords || [];
-    const image = page.openGraph?.images?.[0];
+    const image = page.image;
 
     // Add page heading
     children.push(heading(2, pageTitle));
@@ -816,7 +815,7 @@ export function metadataToMarkdown(
 
   // Add page list (editable section)
   for (const page of pages) {
-    const pageTitle = page.openGraph?.title || page.title || page.slug;
+    const pageTitle = page.title || page.slug;
 
     // Check if this is a single-link entry (external link or no detail section)
     const isSingleLink = page.skipDetailSection || false;
@@ -869,18 +868,17 @@ export function metadataToMarkdown(
       continue;
     }
 
-    const pageTitle = page.openGraph?.title || page.title || page.slug;
+    const pageTitle = page.title || page.slug;
     // Use descriptionMarkdown to preserve formatting if available
     // Note: We don't replace newlines here to allow natural line breaks in detailed sections
     let pageDescription: string;
     if (page.descriptionMarkdown && page.descriptionMarkdown.length > 0) {
       pageDescription = astNodesToMarkdown(page.descriptionMarkdown);
     } else {
-      pageDescription =
-        page.openGraph?.description || page.description || 'No description available';
+      pageDescription = page.description || 'No description available';
     }
     const keywords = page.keywords || [];
-    const image = page.openGraph?.images?.[0];
+    const image = page.image;
 
     // Add page heading
     lines.push(`## ${pageTitle}`);
@@ -1144,10 +1142,6 @@ export async function markdownToMetadata(markdown: string): Promise<PagesMetadat
             description: 'No description available',
             tags: tags.length > 0 ? tags : undefined,
             skipDetailSection: true, // Mark as external/single-link entry
-            openGraph: {
-              title: pageTitle,
-              description: 'No description available',
-            },
           });
         } else if (links.length >= 2) {
           // Two-link format: - [Title](#slug) [Tag1] [Tag2] - [Full Docs](./path/page.mdx)
@@ -1191,10 +1185,6 @@ export async function markdownToMetadata(markdown: string): Promise<PagesMetadat
             title: pageTitle,
             description: 'No description available', // Will be updated from details section
             tags: tags.length > 0 ? tags : undefined,
-            openGraph: {
-              title: pageTitle,
-              description: 'No description available', // Will be updated from details section
-            },
           });
         }
       }
@@ -1287,28 +1277,17 @@ export async function markdownToMetadata(markdown: string): Promise<PagesMetadat
           if (paragraphNode.children) {
             currentPage.descriptionMarkdown = stripPositions(paragraphNode.children);
           }
-          if (!currentPage.openGraph) {
-            currentPage.openGraph = {};
-          }
-          currentPage.openGraph.description = paragraphText;
           return;
         }
       }
 
       // Parse image
       if (currentPage && node.type === 'image') {
         const imageNode = node as ImageNode;
-        if (!currentPage.openGraph) {
-          currentPage.openGraph = {};
-        }
-        currentPage.openGraph.images = [
-          {
-            url: imageNode.url,
-            width: 800,
-            height: 600,
-            alt: imageNode.alt || currentPage.title || currentPage.slug || '',
-          },
-        ];
+        currentPage.image = {
+          url: imageNode.url,
+          alt: imageNode.alt || currentPage.title || currentPage.slug || '',
+        };
         return;
       }
     }
diff --git a/packages/docs-infra/src/pipeline/syncPageIndex/syncPageIndex.test.ts b/packages/docs-infra/src/pipeline/syncPageIndex/syncPageIndex.test.ts
@@ -221,24 +221,16 @@ Old description.
     `);
   });
 
-  it('should handle metadata with openGraph', async () => {
+  it('should handle metadata with image', async () => {
     const metadata: PageMetadata = {
       slug: 'button',
       path: './button/page.mdx',
       title: 'Button',
       description: 'A button component.',
       keywords: ['interactive', 'input'],
-      openGraph: {
-        title: 'Button Component',
-        description: 'A comprehensive button component.',
-        images: [
-          {
-            url: 'https://example.com/button.png',
-            width: 800,
-            height: 600,
-            alt: 'Button preview',
-          },
-        ],
+      image: {
+        url: 'https://example.com/button.png',
+        alt: 'Button preview',
       },
     };
 
@@ -256,13 +248,13 @@ Old description.
 
       [//]: # 'This file is autogenerated, but the following list can be modified.'
 
-      - [Button Component](#button) - [Full Docs](./button/page.mdx)
+      - [Button](#button) - [Full Docs](./button/page.mdx)
 
       [//]: # 'This file is autogenerated, DO NOT EDIT AFTER THIS LINE'
 
-      ## Button Component
+      ## Button
 
-      A comprehensive button component.
+      A button component.
 
       ![Button preview](https://example.com/button.png)
 
diff --git a/packages/docs-infra/src/pipeline/transformMarkdownMetadata/transformMarkdownMetadata.integration.test.ts b/packages/docs-infra/src/pipeline/transformMarkdownMetadata/transformMarkdownMetadata.integration.test.ts
diff --git a/packages/docs-infra/src/pipeline/transformMarkdownMetadata/transformMarkdownMetadata.ts b/packages/docs-infra/src/pipeline/transformMarkdownMetadata/transformMarkdownMetadata.ts
diff --git a/packages/docs-infra/src/pipeline/transformMarkdownMetadata/types.ts b/packages/docs-infra/src/pipeline/transformMarkdownMetadata/types.ts
