Skip to content

Image Galleries

Create beautiful, responsive image galleries with built-in lightbox functionality for an enhanced viewing experience.

Overview

Our image gallery features include:

  • Responsive Grid Layouts - Automatically adjust to screen size
  • Lightbox Viewing - Full-screen image viewing with navigation
  • Dark Mode Support - Galleries adapt to your theme
  • Lazy Loading - Improved performance for image-heavy pages
  • Captions - Add descriptions to your images
  • Touch Support - Swipe navigation on mobile devices

Create a simple image gallery using HTML:

<div class="image-gallery">
  <figure>
    <img loading="lazy" src="../assets/images/dashboard.svg" alt="Dashboard View">
    <figcaption>Main Dashboard</figcaption>
  </figure>
  <figure>
    <img loading="lazy" src="../assets/images/analytics.svg" alt="Analytics">
    <figcaption>Analytics Panel</figcaption>
  </figure>
  <figure>
    <img loading="lazy" src="../assets/images/settings.svg" alt="Settings">
    <figcaption>Settings Page</figcaption>
  </figure>
</div>

Markdown Images with Lightbox

All images automatically get lightbox functionality:

Sample Architecture Click the image above to view in lightbox

Image with Custom Caption

Use attributes to add captions:

Workflow Diagram{: caption="Complete workflow from start to finish"}

Sample 1
Grid Item 1
Sample 2
Grid Item 2
Sample 3
Grid Item 3
Sample 4
Grid Item 4

Combine diagrams with descriptions:

System Architecture

graph TB
    A[Load Balancer] --> B[Web Server 1]
    A --> C[Web Server 2]
    B --> D[Database]
    C --> D

User Flow

graph LR
    A[Login] --> B{Authenticated?}
    B -->|Yes| C[Dashboard]
    B -->|No| A

When viewing images in lightbox:

  • Next/Previous: Use arrow keys or swipe
  • Close: Press ESC or click outside
  • Zoom: Scroll or pinch to zoom
  • Download: Right-click to save

Excluding Images

Prevent specific images from opening in lightbox:

<img loading="lazy" src="../assets/logo.png" alt="Logo">{: .no-lightbox}

Group related images for sequential viewing:

<div class="gallery-group" data-gallery="screenshots">
  <img loading="lazy" src="screen1.png" alt="Screenshot 1">
  <img loading="lazy" src="screen2.png" alt="Screenshot 2">
  <img loading="lazy" src="screen3.png" alt="Screenshot 3">
</div>

Advanced Features

Lazy Loading

Improve performance with lazy loading:

<img loading="lazy" src="../assets/images/large-diagram.png" alt="Large Image">{: loading="lazy"}

Responsive Images

Provide different image sizes:

<picture>
  <source media="(max-width: 768px)" srcset="image-mobile.png">
  <source media="(max-width: 1200px)" srcset="image-tablet.png">
  <img loading="lazy" src="image-desktop.png" alt="Responsive Image">
</picture>

Zoom on Hover

Add zoom effect to gallery items:

<div class="image-gallery zoom-on-hover">
  <figure>
    <img loading="lazy" src="image.png" alt="Zoomable">
  </figure>
</div>

Configuration

GLightbox Options

The lightbox is configured in mkdocs.yml:

plugins:
  - glightbox:
      touchNavigation: true
      loop: false
      effect: zoom
      slide_effect: slide
      width: 100%
      height: auto
      zoomable: true
      draggable: true
      auto_theme: true

Custom Styling

Override gallery styles in your custom CSS:

/* Custom gallery spacing */
.image-gallery {
  gap: 2rem;
  margin: 3rem 0;
}

/* Custom caption style */
.image-gallery figcaption {
  font-weight: bold;
  color: var(--md-primary-fg-color);
}

Best Practices

1. Image Optimization

  • Use appropriate formats (WebP, JPEG, PNG)
  • Compress images without quality loss
  • Provide responsive sizes
  • Use lazy loading for large galleries

2. Accessibility

Always provide meaningful alt text:

<img loading="lazy" src="dashboard.png" alt="Dashboard showing user statistics and real-time data">

3. Performance

For many images:

<!-- Use lazy loading -->
<img src="image.png" loading="lazy" alt="Description">

<!-- Specify dimensions -->
<img loading="lazy" src="image.png" width="800" height="600" alt="Description">

4. Mobile Experience

  • Test swipe gestures
  • Ensure touch targets are large enough
  • Verify images scale properly
  • Check loading performance

Examples

Login
Login Screen
Dashboard
Dashboard View
Reports
Reports Section

Architecture Diagrams

Microservices Architecture

graph TB
    subgraph "Frontend"
        A[React App]
    end
    subgraph "API Gateway"
        B[Kong]
    end
    subgraph "Services"
        C[User Service]
        D[Order Service]
        E[Payment Service]
    end
    subgraph "Data"
        F[(User DB)]
        G[(Order DB)]
        H[(Payment DB)]
    end

    A --> B
    B --> C
    B --> D
    B --> E
    C --> F
    D --> G
    E --> H

Troubleshooting

Images Not Opening in Lightbox

  1. Check JavaScript console for errors
  2. Verify GLightbox plugin is enabled
  3. Ensure image has proper src attribute
  4. Check for no-lightbox class
  1. Verify CSS is loaded
  2. Check for conflicting styles
  3. Test in different browsers
  4. Validate HTML structure

Performance Problems

  1. Implement lazy loading
  2. Optimize image sizes
  3. Use appropriate formats
  4. Enable browser caching