Update image handling (#14564)

## DESCRIBE YOUR PR
This PR implements a modern image lightbox for all documentation images,
enhancing the user experience.

Previously, clicking an image would open the raw image file in a new
browser tab. This change introduces an in-page modal overlay for images,
leveraging Radix UI Dialog for accessibility and a smooth user
experience.

Key features:
- Images now open in a responsive lightbox overlay on click.
- Preserves existing functionality: right-click or Ctrl/Cmd+click still
opens the image in a new tab.
- Includes accessibility features (keyboard navigation, ARIA labels).
- Adds subtle CSS animations for opening/closing the lightbox.

## IS YOUR CHANGE URGENT?  

Help us prioritize incoming PRs by letting us know when the change needs
to go live.
- [ ] Urgent deadline (GA date, etc.): 
- [ ] Other deadline: 
- [x] None: Not urgent, can wait up to 1 week+

## SLA

- Teamwork makes the dream work, so please add a reviewer to your PRs.
- Please give the docs team up to 1 week to review your PR unless you've
added an urgent due date to it.
Thanks in advance for your help!

## PRE-MERGE CHECKLIST

*Make sure you've checked the following before merging your changes:*

- [ ] Checked Vercel preview for correctness, including links
- [ ] PR was reviewed and approved by any necessary SMEs (subject matter
experts)
- [ ] PR was reviewed and approved by a member of the [Sentry docs
team](https://github.com/orgs/getsentry/teams/docs)

## LEGAL BOILERPLATE

Look, I get it. The entity doing business as "Sentry" was incorporated
in the State of Delaware in 2015 as Functional Software, Inc. and is
gonna need some rights from me in order to utilize my contributions in
this here PR. So here's the deal: I retain all rights, title and
interest in and to my contributions, and by keeping this boilerplate
intact I confirm that Sentry can use, modify, copy, and redistribute my
contributions, under Sentry's choice of terms.

## EXTRA RESOURCES

- [Sentry Doc

---------

Co-authored-by: Cursor Agent <[email protected]>
Co-authored-by: getsantry[bot] <66042841+getsantry[bot]@users.noreply.github.com>
Co-authored-by: Sergiy Dybskiy <[email protected]>

Author: 4 people

app/globals.css

@@ -177,6 +177,6 @@ body {
 
 .onboarding-step .step-heading::before,
 .onboarding-step h2::before {
-  content: "Step " counter(onboarding-step) ": ";
+  content: 'Step ' counter(onboarding-step) ': ';
   font-weight: inherit;
 }

next.config.ts

@@ -2,6 +2,7 @@ import {codecovNextJSWebpackPlugin} from '@codecov/nextjs-webpack-plugin';
 import {withSentryConfig} from '@sentry/nextjs';
 
 import {redirects} from './redirects.js';
+import {REMOTE_IMAGE_PATTERNS} from './src/config/images';
 
 const outputFileTracingExcludes = process.env.NEXT_PUBLIC_DEVELOPER_DOCS
   ? {
@@ -54,6 +55,10 @@ const nextConfig = {
   trailingSlash: true,
   serverExternalPackages: ['rehype-preset-minify'],
   outputFileTracingExcludes,
+  images: {
+    contentDispositionType: 'inline', // "open image in new tab" instead of downloading
+    remotePatterns: REMOTE_IMAGE_PATTERNS,
+  },
   webpack: (config, options) => {
     config.plugins.push(
       codecovNextJSWebpackPlugin({
@@ -71,7 +76,7 @@ const nextConfig = {
     DEVELOPER_DOCS_: process.env.NEXT_PUBLIC_DEVELOPER_DOCS,
   },
   redirects,
-  rewrites: async () => [
+  rewrites: () => [
     {
       source: '/:path*.md',
       destination: '/md-exports/:path*.md',

package.json

@@ -47,6 +47,7 @@
     "@prettier/plugin-xml": "^3.3.1",
     "@radix-ui/colors": "^3.0.0",
     "@radix-ui/react-collapsible": "^1.1.1",
+    "@radix-ui/react-dialog": "^1.1.14",
     "@radix-ui/react-dropdown-menu": "^2.1.2",
     "@radix-ui/react-icons": "^1.3.2",
     "@radix-ui/react-tabs": "^1.1.1",

src/components/docImage.tsx

@@ -1,11 +1,68 @@
 import path from 'path';
 
-import Image from 'next/image';
-
+import {isExternalImage} from 'sentry-docs/config/images';
 import {serverContext} from 'sentry-docs/serverContext';
 
+import {ImageLightbox} from './imageLightbox';
+
+// Helper function to safely parse dimension values
+const parseDimension = (value: string | number | undefined): number | undefined => {
+  if (typeof value === 'number' && value > 0 && value <= 10000) return value;
+  if (typeof value === 'string') {
+    const parsed = parseInt(value, 10);
+    return parsed > 0 && parsed <= 10000 ? parsed : undefined;
+  }
+  return undefined;
+};
+
+// Dimension pattern regex - used to identify dimension hashes like "800x600"
+const DIMENSION_PATTERN = /^(\d+)x(\d+)$/;
+
+// Helper function to extract hash from URL string (works with both relative and absolute URLs)
+const extractHash = (url: string): string => {
+  const hashIndex = url.indexOf('#');
+  return hashIndex !== -1 ? url.slice(hashIndex + 1) : '';
+};
+
+// Helper function to check if a hash contains dimension information
+const isDimensionHash = (hash: string): boolean => {
+  return DIMENSION_PATTERN.test(hash);
+};
+
+// Helper function to parse dimensions from URL hash
+const parseDimensionsFromHash = (url: string): number[] => {
+  const hash = extractHash(url);
+  const match = hash.match(DIMENSION_PATTERN);
+
+  if (match) {
+    const width = parseInt(match[1], 10);
+    const height = parseInt(match[2], 10);
+    return width > 0 && width <= 10000 && height > 0 && height <= 10000
+      ? [width, height]
+      : [];
+  }
+
+  return [];
+};
+
+// Helper function to remove dimension hash from URL while preserving fragment identifiers
+const cleanUrl = (url: string): string => {
+  const hash = extractHash(url);
+
+  // If no hash or hash is not a dimension pattern, return original URL
+  if (!hash || !isDimensionHash(hash)) {
+    return url;
+  }
+
+  // Remove dimension hash
+  const hashIndex = url.indexOf('#');
+  return url.slice(0, hashIndex);
+};
+
 export default function DocImage({
   src,
+  width: propsWidth,
+  height: propsHeight,
   ...props
 }: Omit<React.HTMLProps<HTMLImageElement>, 'ref' | 'placeholder'>) {
   const {path: pagePath} = serverContext();
@@ -14,44 +71,46 @@ export default function DocImage({
     return null;
   }
 
-  // Next.js Image component only supports images from the public folder
-  // or from a remote server with properly configured domain
-  if (src.startsWith('http')) {
-    // eslint-disable-next-line @next/next/no-img-element
-    return <img src={src} {...props} />;
-  }
+  const isExternal = isExternalImage(src);
+  let finalSrc = src;
+  let imgPath = src;
 
-  // If the image src is not an absolute URL, we assume it's a relative path
-  // and we prepend /mdx-images/ to it.
-  if (src.startsWith('./')) {
-    src = path.join('/mdx-images', src);
-  }
-  // account for the old way of doing things where the public folder structure mirrored the docs folder
-  else if (!src?.startsWith('/') && !src?.includes('://')) {
-    src = `/${pagePath.join('/')}/${src}`;
+  // For internal images, process the path
+  if (!isExternal) {
+    if (src.startsWith('./')) {
+      finalSrc = path.join('/mdx-images', src);
+    } else if (!src?.startsWith('/') && !src?.includes('://')) {
+      finalSrc = `/${pagePath.join('/')}/${src}`;
+    }
+
+    // For internal images, imgPath should be the pathname only
+    try {
+      const srcURL = new URL(finalSrc, 'https://example.com');
+      imgPath = srcURL.pathname;
+    } catch (_error) {
+      imgPath = finalSrc;
+    }
+  } else {
+    // For external images, clean URL by removing only dimension hashes, preserving fragment identifiers
+    finalSrc = cleanUrl(src);
+    imgPath = finalSrc;
   }
 
-  // parse the size from the URL hash (set by remark-image-size.js)
-  const srcURL = new URL(src, 'https://example.com');
-  const imgPath = srcURL.pathname;
-  const [width, height] = srcURL.hash // #wxh
-    .slice(1)
-    .split('x')
-    .map(s => parseInt(s, 10));
+  // Parse dimensions from URL hash (works for both internal and external)
+  const hashDimensions = parseDimensionsFromHash(src);
+
+  // Use hash dimensions first, fallback to props
+  const width = hashDimensions[0] > 0 ? hashDimensions[0] : parseDimension(propsWidth);
+  const height = hashDimensions[1] > 0 ? hashDimensions[1] : parseDimension(propsHeight);
 
   return (
-    <a href={imgPath} target="_blank" rel="noreferrer">
-      <Image
-        {...props}
-        src={src}
-        width={width}
-        height={height}
-        style={{
-          width: '100%',
-          height: 'auto',
-        }}
-        alt={props.alt ?? ''}
-      />
-    </a>
+    <ImageLightbox
+      src={finalSrc}
+      imgPath={imgPath}
+      width={width}
+      height={height}
+      alt={props.alt ?? ''}
+      {...props}
+    />
   );
 }

src/components/imageLightbox/index.tsx

@@ -0,0 +1,142 @@
+'use client';
+
+import {useState} from 'react';
+import Image from 'next/image';
+
+import {Lightbox} from 'sentry-docs/components/lightbox';
+import {isAllowedRemoteImage, isExternalImage} from 'sentry-docs/config/images';
+
+interface ImageLightboxProps
+  extends Omit<
+    React.HTMLProps<HTMLImageElement>,
+    'ref' | 'src' | 'width' | 'height' | 'alt'
+  > {
+  alt: string;
+  imgPath: string;
+  src: string;
+  height?: number;
+  width?: number;
+}
+
+const getImageUrl = (src: string, imgPath: string): string => {
+  if (isExternalImage(src)) {
+    // Normalize protocol-relative URLs to use https:
+    return src.startsWith('//') ? `https:${src}` : src;
+  }
+  return imgPath;
+};
+
+type ValidDimensions = {
+  height: number;
+  width: number;
+};
+
+const getValidDimensions = (width?: number, height?: number): ValidDimensions | null => {
+  if (
+    width != null &&
+    height != null &&
+    !isNaN(width) &&
+    !isNaN(height) &&
+    width > 0 &&
+    height > 0
+  ) {
+    return {width, height};
+  }
+  return null;
+};
+
+export function ImageLightbox({
+  src,
+  alt,
+  width,
+  height,
+  imgPath,
+  style,
+  className,
+  ...props
+}: ImageLightboxProps) {
+  const [open, setOpen] = useState(false);
+
+  const dimensions = getValidDimensions(width, height);
+  const shouldUseNextImage =
+    !!dimensions && (!isExternalImage(src) || isAllowedRemoteImage(src));
+
+  const openInNewTab = () => {
+    window.open(getImageUrl(src, imgPath), '_blank', 'noopener,noreferrer');
+  };
+
+  const handleClick = (e: React.MouseEvent) => {
+    // Middle-click or Ctrl/Cmd+click opens in new tab
+    if (e.button === 1 || e.ctrlKey || e.metaKey) {
+      e.preventDefault();
+      e.stopPropagation();
+      openInNewTab();
+    }
+    // Regular click is handled by Dialog.Trigger
+  };
+
+  const handleKeyDown = (e: React.KeyboardEvent) => {
+    // Ctrl/Cmd+Enter/Space opens in new tab
+    // Regular Enter/Space is handled by Dialog.Trigger
+    if ((e.key === 'Enter' || e.key === ' ') && (e.ctrlKey || e.metaKey)) {
+      e.preventDefault();
+      e.stopPropagation();
+      openInNewTab();
+    }
+  };
+
+  // Filter out props that are incompatible with Next.js Image component
+  // Next.js Image has stricter typing for certain props like 'placeholder'
+  const {placeholder: _placeholder, ...imageCompatibleProps} = props;
+
+  const renderImage = (isInline: boolean = true) => {
+    const renderedSrc = getImageUrl(src, imgPath);
+    const imageClassName = isInline
+      ? className
+      : 'max-h-[90vh] max-w-[90vw] object-contain';
+    const imageStyle = isInline
+      ? {width: '100%', height: 'auto', ...style}
+      : {width: 'auto', height: 'auto'};
+
+    if (shouldUseNextImage && dimensions) {
+      return (
+        <Image
+          src={renderedSrc}
+          width={dimensions.width}
+          height={dimensions.height}
+          style={imageStyle}
+          className={imageClassName}
+          alt={alt}
+          priority={!isInline}
+          {...imageCompatibleProps}
+        />
+      );
+    }
+    return (
+      /* eslint-disable-next-line @next/next/no-img-element */
+      <img
+        src={renderedSrc}
+        alt={alt}
+        loading={isInline ? 'lazy' : 'eager'}
+        decoding="async"
+        style={imageStyle}
+        className={imageClassName}
+        {...imageCompatibleProps}
+      />
+    );
+  };
+
+  return (
+    <Lightbox.Root open={open} onOpenChange={setOpen} content={renderImage(false)}>
+      <Lightbox.Trigger
+        onClick={handleClick}
+        onAuxClick={handleClick}
+        onKeyDown={handleKeyDown}
+        className="cursor-pointer border-none bg-transparent p-0 block w-full no-underline"
+        aria-label={`View image: ${alt}`}
+      >
+        {renderImage()}
+      </Lightbox.Trigger>
+    </Lightbox.Root>
+  );
+}