Gallery View

Create interactive image galleries in your Obsidian notes using simple code blocks. Display images from your vault folders with thumbnail grids and click-to-expand modal viewing.

Features

• Thumbnail galleries — Display images in responsive grid layouts
• Modal viewer — Click thumbnails to view full-size images
• Folder support — Scan entire folders or individual files
• Simple syntax — Easy obs-gallery code blocks
• Responsive design — Works on desktop and mobile
• Performance — Lazy loading for large image collections
• Clean styling — Integrates seamlessly with Obsidian themes
• Error handling — Graceful fallbacks for missing paths

Quick start

Installation

1. Download the plugin files (main.js, manifest.json, styles.css)
2. Create folder: YourVault/.obsidian/plugins/gallery-view/
3. Copy files to the plugin folder
4. Enable "Gallery View" in Obsidian Settings → Community Plugins

Basic Usage

Create galleries in your notes using code blocks:

```obs-gallery
path: Images/Screenshots
view: thumbnail
```

Usage examples

Folder Gallery

Display all images from a folder:

```obs-gallery
path: Photos/Vacation2024
view: thumbnail
```

Carousel View

Horizontal scrolling carousel with controls:

```obs-gallery
path: Images/Screenshots
view: carousel
```

Masonry Grid

Pinterest-style layout with variable heights:

```obs-gallery
path: Projects/WebDev
view: grid
recursive: true
```

With External Images (Beta)

Include remote images (requires enabling in settings):

```obs-gallery
urls:
  - https://picsum.photos/800/600?random=1
  - https://picsum.photos/800/600?random=2
  - https://picsum.photos/800/600?random=3
  - https://picsum.photos/800/600?random=4
view: grid
```

Configuration options

Remote images (opt-in)

You can reference externally hosted images using the urls: YAML list in your obs-gallery code block. Remote images are disabled by default to preserve privacy. The plugin exposes these related settings in the Gallery Plugin settings panel:

• Allow remote images (boolean) — enable loading images from external URLs.
• Remote load timeout (ms) — how long the plugin waits for remote images before giving up.
• Validate remote content type (optional) — when enabled the plugin will perform a lightweight HEAD request to verify the remote resource's Content-Type header looks like an image (e.g., image/jpeg) before attempting to load it. This can reduce accidental attempts to load non-image resources, at the cost of one extra small network request per URL.

Example urls: usage:

```obs-gallery
view: thumbnail
urls:
  - https://example.com/photos/cover.jpg
  - https://cdn.example.org/gallery/img123.webp
```

Notes:

• The plugin performs only syntactic validation of URLs by default. Enabling content-type validation activates the HEAD check described above.
• Remote images are not automatically downloaded into your vault. If you need permanent local copies, mirror the assets manually.

Supported formats

• JPEG (.jpg, .jpeg)
• PNG (.png)
• GIF (.gif)
• WebP (.webp)

Interface

Thumbnail Grid

• Responsive grid layout adapts to screen size
• Hover effects for better interactivity
• Lazy loading for performance

Modal Viewer

• Full-size image display
• Multiple ways to close:
  • Click the × button
  • Press Escape key
  • Click outside the image
• Image name displayed at bottom

Development

Building from Source

# Install dependencies
npm install

# Development build with watching
npm run dev

# Production build
npm run build

# Simple build (MVP version)
npm run build-mvp

Project Structure

obsidian-gallery-plugin/
├── main.ts              # Main plugin code
├── main.js              # Compiled plugin
├── manifest.json        # Plugin metadata
├── styles.css           # Gallery styling
├── package.json         # Dependencies
├── tsconfig.json        # TypeScript config
└── src/                 # Advanced architecture (future)
    ├── models/          # Data models
    ├── views/           # View components
    ├── services/        # Core services
    └── processors/      # Content processing

Troubleshooting

Gallery Not Appearing

• Check that the path exists and has correct case sensitivity
• Verify images are in supported formats
• Use exact folder names (e.g., Images not images if capitalized)

Modal Not Opening

• Ensure styles.css is properly loaded
• Check browser console for JavaScript errors
• Try refreshing Obsidian or restarting the plugin

Path Issues

• Use relative paths from vault root
• Don't include leading or trailing slashes
• Example: Images/Photos not /Images/Photos/

Performance with Many Images

• Plugin uses lazy loading automatically
• Consider organizing large collections into subfolders
• Modal loads full-resolution images on demand

Roadmap

Current (v1.0.0)

• ✅ Basic thumbnail galleries
• ✅ Modal image viewer
• ✅ Folder and file support
• ✅ Responsive design

Future Enhancements

• 🔄 Carousel view mode
• 🔄 Grid layout options
• ✅ External URL support (opt-in, timeouts)
• 🔄 Image filtering and sorting
• 🔄 Batch operations
• 🔄 Settings panel

Contributions are welcome! Please feel free to:

• Share usage examples and feedback
• Help with documentation

Development Setup

1. Clone the repository
2. Run npm install to install dependencies
3. Use npm run dev for development with auto-rebuilding
4. Test in your Obsidian vault

License

MIT License — see LICENSE for details.

Acknowledgments

• Built for the Obsidian community

Support

• Bug reports: GitHub Issues
• Feature requests: GitHub Discussions
• Documentation: Plugin docs