feat: Implement Open Graph image resolution logic

- Added a helper function to resolve Open Graph image URLs based on various conditions, including manual overrides and fallback mechanisms.
- Integrated the new function into the metadata generation process to prioritize custom images, the first image from content, or a default image.
- Introduced a new remark plugin to extract the first image from markdown content for use in Open Graph metadata.
- Updated frontmatter type definitions to include an optional `og_image` field for custom Open Graph images.

Author: HazAT

app/[[...path]]/page.tsx

@@ -194,6 +194,65 @@ function formatCanonicalTag(tag: string) {
   return tag;
 }
 
+// Helper function to resolve OG image URLs
+async function resolveOgImageUrl(
+  imageUrl: string | undefined,
+  domain: string,
+  pagePath: string[]
+): Promise<string | null> {
+  if (!imageUrl) {
+    return null;
+  }
+
+  // Remove hash fragments (e.g., #600x400 from remark-image-size)
+  const cleanUrl = imageUrl.split('#')[0];
+
+  // External URLs - return as is
+  if (cleanUrl.startsWith('http://') || cleanUrl.startsWith('https://')) {
+    return cleanUrl;
+  }
+
+  // Absolute paths (public folder or already processed mdx-images)
+  if (cleanUrl.startsWith('/')) {
+    return `${domain}${cleanUrl}`;
+  }
+
+  // For relative paths, try to find the processed image in /mdx-images/
+  // Images get hashed during build, so we need to find the hashed version
+  if (cleanUrl.startsWith('./')) {
+    const {readdir} = await import('fs/promises');
+    const path = await import('path');
+
+    // Extract the base filename without path
+    const filename = path.basename(cleanUrl);
+    const nameWithoutExt = filename.replace(path.extname(filename), '');
+
+    try {
+      // Look for the hashed version in public/mdx-images/
+      const mdxImagesDir = path.join(process.cwd(), 'public', 'mdx-images');
+      const files = await readdir(mdxImagesDir);
+
+      // Find a file that starts with the same base name
+      const hashedFile = files.find(f => f.startsWith(nameWithoutExt + '-'));
+
+      if (hashedFile) {
+        return `${domain}/mdx-images/${hashedFile}`;
+      }
+    } catch (e) {
+      // If we can't find the hashed version, fall through to default behavior
+    }
+
+    // Fallback: resolve relative to page directory
+    const relativePath = cleanUrl.slice(2);
+    const pageDir = pagePath.join('/');
+    return `${domain}/${pageDir}/${relativePath}`;
+  }
+
+  // Default case: treat as relative to page
+  const pageDir = pagePath.join('/');
+  return `${domain}/${pageDir}/${cleanUrl}`;
+}
+
 export async function generateMetadata(props: MetadataProps): Promise<Metadata> {
   const params = await props.params;
   const domain = isDeveloperDocs
@@ -208,12 +267,8 @@ export async function generateMetadata(props: MetadataProps): Promise<Metadata>
   let customCanonicalTag: string = '';
   let description =
     'Self-hosted and cloud-based application performance monitoring & error tracking that helps software teams see clearer, solve quicker, and learn continuously.';
-  // show og image on the home page only
-  const images =
-    ((await props.params).path ?? []).length === 0
-      ? [{url: `${previewDomain ?? domain}/og.png`, width: 1200, height: 630}]
-      : [];
 
+  let ogImageUrl: string | null = null;
   let noindex: undefined | boolean = undefined;
 
   const rootNode = await getDocsRootNode();
@@ -236,9 +291,46 @@ export async function generateMetadata(props: MetadataProps): Promise<Metadata>
       }
 
       noindex = pageNode.frontmatter.noindex;
+
+      // Three-tier OG image priority:
+      // 1. Manual override via og_image frontmatter
+      if (pageNode.frontmatter.og_image) {
+        ogImageUrl = await resolveOgImageUrl(
+          pageNode.frontmatter.og_image,
+          previewDomain ?? domain,
+          params.path
+        );
+      }
+
+      // 2. First image from page content (if no manual override)
+      if (!ogImageUrl) {
+        try {
+          const doc = await getFileBySlugWithCache(
+            isDeveloperDocs
+              ? `develop-docs/${params.path.join('/')}`
+              : `docs/${pageNode.path}`
+          );
+          if (doc.firstImage) {
+            ogImageUrl = await resolveOgImageUrl(
+              doc.firstImage,
+              previewDomain ?? domain,
+              params.path
+            );
+          }
+        } catch (e) {
+          // If we can't load the doc, just continue without the first image
+        }
+      }
     }
   }
 
+  // 3. Default fallback
+  if (!ogImageUrl) {
+    ogImageUrl = `${previewDomain ?? domain}/og.png`;
+  }
+
+  const images = [{url: ogImageUrl, width: 1200, height: 630}];
+
   const canonical = customCanonicalTag
     ? domain + customCanonicalTag
     : params.path

src/mdx.ts

@@ -33,6 +33,7 @@ import rehypeSlug from './rehype-slug.js';
 import remarkCodeTabs from './remark-code-tabs';
 import remarkCodeTitles from './remark-code-title';
 import remarkComponentSpacing from './remark-component-spacing';
+import remarkExtractFirstImage from './remark-extract-first-image';
 import remarkExtractFrontmatter from './remark-extract-frontmatter';
 import remarkFormatCodeBlocks from './remark-format-code';
 import remarkImageResize from './remark-image-resize';
@@ -44,6 +45,7 @@ import {isNotNil} from './utils';
 import {isVersioned, VERSION_INDICATOR} from './versioning';
 
 type SlugFile = {
+  firstImage?: string;
   frontMatter: Platform & {slug: string};
   matter: Omit<matter.GrayMatterFile<string>, 'data'> & {
     data: Platform;
@@ -579,6 +581,7 @@ export async function getFileBySlug(slug: string): Promise<SlugFile> {
   );
 
   const toc: TocNode[] = [];
+  const firstImageRef: string[] = [];
 
   // cwd is how mdx-bundler knows how to resolve relative paths
   const cwd = path.dirname(sourcePath);
@@ -598,6 +601,7 @@ export async function getFileBySlug(slug: string): Promise<SlugFile> {
         remarkDefList,
         remarkFormatCodeBlocks,
         [remarkImageSize, {sourceFolder: cwd, publicFolder: path.join(root, 'public')}],
+        [remarkExtractFirstImage, {exportRef: firstImageRef}],
         remarkMdxImages,
         remarkImageResize,
         remarkCodeTitles,
@@ -694,6 +698,7 @@ export async function getFileBySlug(slug: string): Promise<SlugFile> {
     matter: result.matter,
     mdxSource: code,
     toc,
+    firstImage: firstImageRef[0],
     frontMatter: {
       ...mergedFrontmatter,
       slug,

src/remark-extract-first-image.ts

@@ -0,0 +1,35 @@
+import {visit} from 'unist-util-visit';
+
+/**
+ * Remark plugin to extract the first image URL from markdown content.
+ * This extracts the first image found in the document to be used as the
+ * Open Graph image for social sharing.
+ *
+ * IMPORTANT: This plugin must run BEFORE remarkMdxImages so it can capture
+ * standard markdown image nodes before they are transformed to JSX.
+ *
+ * The extracted image URL is exported via the exportRef option and can be
+ * accessed after processing to set in frontmatter or metadata.
+ *
+ * @param options - Plugin options
+ * @param options.exportRef - Array to store the extracted first image URL
+ */
+export default function remarkExtractFirstImage(options: {exportRef: string[]}) {
+  return (tree: any) => {
+    let firstImage: string | null = null;
+
+    // Visit standard markdown image nodes
+    // This runs before remarkMdxImages transforms them to JSX
+    visit(tree, 'image', (node: any) => {
+      if (!firstImage && node.url) {
+        firstImage = node.url;
+        return false; // Stop visiting once we find the first image
+      }
+    });
+
+    // Export the first image URL if found
+    if (firstImage) {
+      options.exportRef.push(firstImage);
+    }
+  };
+}

src/types/frontmatter.ts

@@ -56,6 +56,14 @@ export interface FrontMatter {
    */
   notoc?: boolean;
 
+  /**
+   * Custom Open Graph image for social sharing.
+   * Can be a relative path (e.g., './img/my-image.png'), absolute path (e.g., '/images/og.png'),
+   * or external URL. If not specified, the first image in the page content will be used,
+   * or falls back to the default OG image.
+   */
+  og_image?: string;
+
   /**
    * The previous page in the bottom pagination navigation.
    */