kGallery

A powerful Obsidian plugin for displaying images in beautiful masonry grid galleries with lightbox viewing. Create standalone gallery views or embed galleries directly in your markdown notes.

Features

• Masonry Grid Layout: Responsive grid that adapts to image aspect ratios
• Embedded Galleries: Use code blocks to embed galleries anywhere in your notes
• Lightbox Viewer: Full-screen or modal image viewing with zoom and pan
• Customizable: Control columns, gaps, borders, and more
• Recursive Search: Search folders and subfolders for images
• Lazy Loading: Optimized performance for large image collections

Usage

Gallery View

Access the gallery view in two ways:

1. Click the image icon in the left sidebar ribbon
2. Use Command Palette (Cmd/Ctrl+P) → "Open Image Gallery"

Configure the default folder and appearance in Settings → kGallery.

Embedded Galleries

Embed image galleries in your markdown notes using code blocks:

```kGallery
path: images/nature
recursive: true
columns: 3
width: page
gridGap: 15
borderRadius: 8
lightboxMode: fullscreen
```

Code Block Parameters

Optional Parameters

• path: Folder path to search for images (e.g., images/photos). If omitted, defaults to the folder containing the note. Leave empty (path:) for vault root.

• recursive: Search subdirectories (default: true)

  • Values: true, false, yes, no, 1, 0

• columns: Number of columns in the grid (default: global setting)

  • Range: 1-10

• width: Gallery width mode (default: page)

  • page: Constrained to reading width
  • full: Extends across full editor width

• gridGap: Space between images in pixels (default: global setting)

  • Range: 0-100

• borderRadius: Corner radius for images in pixels (default: global setting)

  • Range: 0-50

• lightboxMode: Lightbox display mode (default: fullscreen)

  • fullscreen: Full screen viewing
  • modal: Centered modal with borders

Examples

Basic Gallery

```kGallery
path: photos/2024
```

Customized Gallery

```kGallery
path: art/portfolio
recursive: false
columns: 4
width: full
gridGap: 20
borderRadius: 12
lightboxMode: modal
```

Vault Root Gallery

```kGallery
path:
columns: 2
width: page
```

Settings

Configure global defaults in Settings → kGallery:

• Attachment Folder: Default folder for gallery view
• Image Extensions: File types to include (jpg, png, gif, etc.)
• Grid Gap: Default spacing between images
• Column Count: Default number of columns
• Border Radius: Default corner radius for images
• Lightbox Mode: Default viewing mode (fullscreen or modal)
• Wide Image Threshold: Aspect ratio threshold for images to span 2 columns (0-1). Lower values = wider images needed. 0.5 means images wider than 2:1 span 2 columns. Set to 0 to disable wide spanning.

Lightbox Controls

When viewing images in the lightbox:

• Arrow Keys: Navigate between images (Left/Right)
• Mouse Wheel: Zoom in/out
• Click & Drag: Pan zoomed images
• Click Outside: Close lightbox
• Esc: Close lightbox
• Right Click: Context menu (reveal in navigator, show in system, copy to clipboard)

Tips

• Use width: page for galleries in reading notes to maintain focus
• Use width: full for photo showcases or visual portfolios
• Set recursive: false to show only images in a specific folder
• Combine with dataview or templater for dynamic gallery paths
• Adjust gridGap and borderRadius to match your note theme

Development

Built with:

• TypeScript
• Obsidian API
• esbuild

To build from source:

npm install
npm run build

Author

Kyle Youngblom

License

MIT