feat: Implement Open Graph image resolution logic (#15335)

- 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

.gitignore

@@ -97,6 +97,8 @@ tsconfig.tsbuildinfo
 # Ignore generated files
 /public/md-exports/
 public/mdx-images/*
+public/og-images/*
+!public/og-images/README.md
 
 # yalc
 .yalc

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

@@ -194,6 +194,41 @@ function formatCanonicalTag(tag: string) {
   return tag;
 }
 
+// Helper function to resolve OG image URLs
+function resolveOgImageUrl(
+  imageUrl: string | undefined,
+  domain: string,
+  pagePath: string[]
+): 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)
+  if (cleanUrl.startsWith('/')) {
+    return `${domain}${cleanUrl}`;
+  }
+
+  // Relative paths - resolve based on page path
+  if (cleanUrl.startsWith('./')) {
+    const relativePath = cleanUrl.slice(2); // Remove './'
+    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 +243,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 +267,25 @@ export async function generateMetadata(props: MetadataProps): Promise<Metadata>
       }
 
       noindex = pageNode.frontmatter.noindex;
+
+      // Check for manual OG image override in frontmatter
+      if (pageNode.frontmatter.og_image) {
+        ogImageUrl = resolveOgImageUrl(
+          pageNode.frontmatter.og_image,
+          previewDomain ?? domain,
+          params.path
+        );
+      }
     }
   }
 
+  // Default fallback
+  if (!ogImageUrl) {
+    ogImageUrl = `${previewDomain ?? domain}/og.png`;
+  }
+
+  const images = [{url: ogImageUrl, width: 1200, height: 630}];
+
   const canonical = customCanonicalTag
     ? domain + customCanonicalTag
     : params.path

develop-docs/application-architecture/dynamic-sampling/architecture.mdx

@@ -1,6 +1,7 @@
 ---
 title: Architecture
 sidebar_order: 3
+og_image: /og-images/application-architecture-dynamic-sampling-architecture.png
 ---
 
 The architecture that powers Dynamic Sampling is composed of several components that work together to get the organization's sample rate closer to the target fidelity.

develop-docs/application-architecture/dynamic-sampling/fidelity-and-biases.mdx

@@ -1,6 +1,7 @@
 ---
 title: Fidelity and Biases
 sidebar_order: 2
+og_image: /og-images/application-architecture-dynamic-sampling-fidelity-and-biases.png
 ---
 
 Dynamic Sampling allows Sentry to automatically adjust the amount of data retained based on how valuable the data is to the user. This is technically achieved by applying a **sample rate** to every event, which is determined by a **set of rules** that are evaluated for each event.

develop-docs/application-architecture/dynamic-sampling/index.mdx

@@ -1,7 +1,11 @@
 ---
 title: Dynamic Sampling
-description: Dynamic Sampling is a feature of the ingestion pipeline that allows Sentry to automatically adjust the amount of data retained based on the value of the data.
+description: >-
+  Dynamic Sampling is a feature of the ingestion pipeline that allows Sentry to
+  automatically adjust the amount of data retained based on the value of the
+  data.
 sidebar_order: 50
+og_image: /og-images/application-architecture-dynamic-sampling.png
 ---
 
 From all the data received by the SDKs, Sentry is able to extract low-granularity information through metrics, while Dynamic Sampling makes the decision of whether to keep or drop data.

develop-docs/application-architecture/dynamic-sampling/the-big-picture.mdx

@@ -1,7 +1,11 @@
 ---
 title: The Big Picture
-description: The lifecycle of an event in Sentry is a complex process which involves many components. Dynamic Sampling is one of these components, and it is important to understand how it fits into the bigger picture.
+description: >-
+  The lifecycle of an event in Sentry is a complex process which involves many
+  components. Dynamic Sampling is one of these components, and it is important
+  to understand how it fits into the bigger picture.
 sidebar_order: 1
+og_image: /og-images/application-architecture-dynamic-sampling-the-big-picture.png
 ---
 
 ![Sequencing](./images/sequencing.png)

develop-docs/backend/application-domains/database-migrations/index.mdx

@@ -1,6 +1,7 @@
 ---
 title: Database Migrations
 sidebar_order: 20
+og_image: /og-images/backend-application-domains-database-migrations.png
 ---
 
 Django migrations are how we handle changes to the database in Sentry.

develop-docs/backend/application-domains/transaction-clustering/index.mdx

@@ -1,6 +1,7 @@
 ---
 title: Clustering URL Transactions
 sidebar_order: 90
+og_image: /og-images/backend-application-domains-transaction-clustering.png
 ---
 
 Sentry attempts to scrub high-cardinality identifiers from URL transactions

develop-docs/backend/issue-platform/index.mdx

@@ -1,6 +1,7 @@
 ---
 title: Issue Platform
 sidebar_order: 30
+og_image: /og-images/backend-issue-platform.jpg
 ---
 
 The Issue Platform allows developers to create new issue types from arbitrary data sources. If you have data about something that you want to track via an issue, you can build it on the issue platform. For example, building profiling issues on the issue platform allowed us to turn things like “JSON decoding on the main thread” into their own issue types.

develop-docs/backend/issue-platform/writing-detectors/index.mdx

@@ -1,6 +1,7 @@
 ---
 title: Writing Detectors
 sidebar_order: 10
+og_image: /og-images/backend-issue-platform-writing-detectors.png
 ---
 
 Issue detectors identify application issues by examining one or more datasets collected by Sentry, and report detected issue occurrences via the <Link to="/backend/issue-platform/">Issue Platform</Link>. Detectors must fingerprint issues accurately and provide actionable information to developers.