Image Gallery & Lightbox

Create clickable image galleries with zoom lightbox overlay

Image Gallery & Lightbox

The gallery extension creates interactive image galleries with click-to-zoom lightbox functionality. Perfect for showcasing multiple images, photo collections, screenshots, or visual demonstrations.

Basic Syntax

Use :::gallery to create an image gallery:

With Custom Title

Add a descriptive title to your gallery:

Features

Click to Zoom

  • Click any image to open it in full-screen lightbox
  • Navigate between images with arrow buttons
  • Close with X button or Escape key
  • Click outside image to close

Keyboard Navigation

  • Left Arrow - Previous image
  • Right Arrow - Next image
  • Escape - Close lightbox

Touch Support

  • Swipe left/right to navigate on touch devices
  • Pinch to zoom (browser native)
  • Tap outside to close

Responsive Grid

Images automatically arrange in a responsive grid that adapts to screen size.

Common Use Cases

1. Photo Galleries

Showcase photo collections:

2. Product Showcase

Display product images from different angles:

3. Before/After Series

Show progressive changes or transformations:

4. Screenshot Documentation

Document UI flows or software features:

5. Tutorial Steps

Visual step-by-step guides:

Compare different options or variations:

7. Portfolio Work

Showcase creative work or projects:

Layout Patterns

Great for extensive collections - the grid adapts automatically.

Best Practices

Image Optimization

✅ Good:

  • Use optimized web formats (WebP, AVIF, or JPEG)
  • Keep image file sizes under 500KB
  • Use appropriate dimensions (800-1200px wide)
  • Provide meaningful alt text

❌ Poor:

  • Uncompressed RAW files
  • Unnecessarily large dimensions
  • Missing alt text
  • Generic filenames

Alt Text

✅ Good: Descriptive alt text

:::gallery
![Sunset over calm ocean with orange sky reflecting on water](sunset.jpg)
![Dense forest with sunlight filtering through tall pine trees](forest.jpg)
:::
Markdown

❌ Poor: Generic or missing alt text

:::gallery
![Image 1](img1.jpg)
![](img2.jpg)
:::
Markdown

✅ Good: Logical grouping and ordering

:::gallery[User Journey]
![Homepage landing](step1.jpg)
![Sign up form](step2.jpg)
![Welcome dashboard](step3.jpg)
![First action](step4.jpg)
:::
Markdown

❌ Poor: Random order

:::gallery
![Random image](img3.jpg)
![Unrelated image](img1.jpg)
![Another one](img2.jpg)
:::
Markdown

✅ Good: Clear, descriptive titles

  • "Product Features Overview"
  • "Installation Step-by-Step"
  • "Summer Collection 2024"

❌ Poor: Vague titles

  • "Images"
  • "Gallery"
  • "Photos"

Technical Details

HTML Structure

The extension generates:

<div class="markdown-gallery" id="gallery-1">
  <h3 class="gallery-title">Gallery Title</h3>
  <div class="gallery-grid">
    <div class="gallery-item" data-index="0">
      <img src="image1.jpg" alt="Description" loading="lazy" />
      <div class="gallery-item-overlay">
        <!-- Zoom icon SVG -->
      </div>
    </div>
    <!-- More items... -->
  </div>
</div>

<!-- Lightbox overlay -->
<div class="gallery-lightbox" id="lightbox-1">
  <button class="lightbox-close">×</button>
  <button class="lightbox-prev">‹</button>
  <button class="lightbox-next">›</button>
  <div class="lightbox-content">
    <img class="lightbox-image" src="" alt="" />
    <div class="lightbox-caption"></div>
    <div class="lightbox-counter">1 / 5</div>
  </div>
</div>
HTML

Grid Layout

Uses CSS Grid for responsive layouts:

.gallery-grid {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
  gap: 1rem;
}
CSS

Breakpoints:

  • Mobile: 150px minimum column width
  • Desktop: 200px minimum column width
  • Auto-fills available space

Performance

  • Lazy Loading: Images use loading="lazy" attribute
  • Single Styles: CSS included once per page
  • Scoped Scripts: JavaScript scoped per gallery
  • Optimized Events: Efficient event delegation

Accessibility

  • Semantic HTML structure
  • ARIA labels on buttons
  • Keyboard navigation support
  • Screen reader compatible
  • Focus management in lightbox

Browser Compatibility

Fully supported in:

  • Chrome/Edge (all modern versions)
  • Firefox (all modern versions)
  • Safari (all modern versions)
  • Mobile browsers (iOS/Android)

Styling

Customize gallery appearance with CSS:

/* Grid spacing */
.gallery-grid {
  gap: 0.5rem; /* Tighter spacing */
}

/* Item border radius */
.gallery-item {
  border-radius: 12px; /* Rounder corners */
}

/* Hover effect */
.gallery-item:hover img {
  transform: scale(1.1); /* More zoom on hover */
}

/* Title styling */
.gallery-title {
  font-size: 2rem;
  color: #2563eb;
  text-align: center;
}

/* Lightbox background */
.gallery-lightbox {
  background: rgba(0, 0, 0, 0.98); /* Darker overlay */
}

/* Navigation buttons */
.lightbox-prev,
.lightbox-next {
  width: 60px;
  height: 60px;
  font-size: 2.5rem;
}
CSS

Dark Mode Support

@media (prefers-color-scheme: dark) {
  .gallery-title {
    color: #e5e7eb;
  }

  .gallery-item {
    background: #374151;
  }
}
CSS

JavaScript API

Access gallery functionality programmatically:

// Get gallery element
const gallery = document.getElementById('gallery-1');

// Programmatically open lightbox
const firstItem = gallery.querySelector('.gallery-item');
firstItem.click();

// Listen for lightbox events
const lightbox = document.getElementById('lightbox-1');
lightbox.addEventListener('click', (e) => {
  if (e.target.classList.contains('lightbox-close')) {
    console.log('Lightbox closed');
  }
});
JAVASCRIPT

Integration Examples

With Cards

Combine galleries with card layouts:

Project Showcase

Check out our latest project:

The project features a modern, clean design with responsive layouts.

With Tabs

Organize galleries by category:

With Steps

Add visual context to tutorials:

steps

Step 1: Open the application

Launch the app from your desktop.

Step 2: Configure settings

Navigate to the settings panel.

Troubleshooting

Images Not Displaying

Issue: Gallery shows but images don't load

Solutions:

  • Check image paths are correct
  • Verify image URLs are accessible
  • Check browser console for errors
  • Ensure images have proper CORS headers (if external)

Issue: Clicking images doesn't open lightbox

Solutions:

  • Check JavaScript console for errors
  • Verify no conflicting event handlers
  • Check browser JavaScript is enabled
  • Try different browser

Layout Issues

Issue: Gallery grid doesn't display correctly

Solutions:

  • Check parent container width
  • Verify CSS isn't being overridden
  • Inspect element in browser DevTools
  • Check for conflicting CSS Grid styles

Performance Issues

Issue: Page loads slowly with large galleries

Solutions:

  • Optimize image file sizes
  • Use WebP format
  • Implement image CDN
  • Reduce image dimensions
  • Consider pagination for 20+ images

Comparison with Other Components

Gallery - Multiple images with lightbox:

:::gallery
![Image 1](img1.jpg)
![Image 2](img2.jpg)
![Image 3](img3.jpg)
:::
Markdown

Figure - Single image with caption:

:::figure
![Single image](img.jpg)

Detailed caption for this specific image.
:::
Markdown

Gallery - Collection of separate images:

  • Multiple independent images
  • Click to zoom
  • Navigate between images

Image Compare - Before/after slider:

  • Exactly two related images
  • Drag slider to compare
  • Shows transformation/difference

Real-World Examples

Documentation Screenshots

Product Photography

Event Photography

Syntax Reference

:::gallery
![Alt text](image-url.jpg)
![Another image](image2.jpg)
:::
Markdown

With title:

:::gallery[Gallery Title]
![Image 1](img1.jpg)
![Image 2](img2.jpg)
:::
Markdown

Parameters:

  • title (optional) - Gallery heading displayed above grid
  • Images - Standard markdown image syntax ![alt](src)

Features:

  • Responsive grid layout
  • Click-to-zoom lightbox
  • Keyboard navigation (arrows, escape)
  • Touch/swipe support
  • Image counter in lightbox
  • Loading lazy for performance
  • Figure/Caption - Single images with semantic captions
  • Image Compare - Before/after slider comparison
  • Cards - Content containers for organization
  • Tabs - Alternative content views
Back to Markdown Features