README file from
GithubGallery View
Turn any folder of photos into a gallery inside your notes. Pick a layout (masonry, justified rows, a mosaic, thumbnails, a carousel or full-width embeds), click a photo to see it full screen, and pull images from your vault, the web, Immich or Nextcloud.

Features

- Six layouts. Masonry columns, justified rows (like Google Photos or Immich), a mosaic of large and small tiles (draw your own patterns, blank spaces included), a thumbnail grid, a carousel and borderless embeds. Switch by changing one word.
- Full-screen viewer. Click any photo for a dark, distraction-free view with slideshow, zoom, photo details, keyboard arrows and swipe.
- Your photos, wherever they are. Vault folders (including subfolders and paths relative to the note), web URLs, Immich (shared links, or your library with albums, people, tags and dates) and Nextcloud (share links or WebDAV folders).
- No YAML needed. The Insert gallery command builds the block for you, Build custom mosaic lets you draw mosaic patterns on a grid, and autocomplete helps if you'd rather type it.
- Fast with big folders. Images load as you scroll, with optional pagination.
- Fits your notes. Uses your theme, works on mobile, and can drop its frame so the gallery sits in the text.
- Ready for Publish (experimental). Obsidian Publish can't run plugins, so Burn galleries in this note turns a note's galleries into images of how they look, ready to publish.

Quick start
Install
In Obsidian, open Settings → Community plugins → Browse, search for Gallery View, then install and enable it. Or open it in Obsidian.
- Download
main.js,manifest.jsonandstyles.cssfrom the latest release. - Create the folder
YourVault/.obsidian/plugins/gallery-view/and copy the files into it. - Enable Gallery View in Settings → Community plugins.
Try it in 30 seconds
Run Gallery View: Create showcase notes from the command palette. It creates a GalleryDemo/ folder with ready-made notes for every layout and source, including use cases built on real photos.
Make your own
Run Gallery View: Insert gallery, pick a layout and a folder, and click Insert gallery block:

Basic Usage
Create galleries in your notes using code blocks:
```obs-gallery
sources:
- type: local
path: Images/Screenshots
view:
type: thumbnail
```
[!NOTE] The plugin fully supports the legacy v1 syntax (e.g.,
path: Images/Screenshots) for backward compatibility, but the v2 nestedsourcesschema is preferred.
Documentation
For full details on configuring the plugin, usage examples, and available settings, please refer to the Gallery View documentation.
Supported formats
- JPEG (
.jpg,.jpeg) - PNG (
.png) - GIF (
.gif) - WebP (
.webp) - AVIF (
.avif) - SVG (
.svg): scaled to fill the viewer, since it's a vector - Videos (
.mp4,.m4v,.webm,.mov,.ogv) from your vault, Immich, Nextcloud and external URLs: shown as a still frame with a play badge, and played in the full-screen viewer
Showcase Generator
Gallery View includes a built-in command to generate a set of interactive demo notes inside your vault. This is the fastest way to see what the plugin can do and to learn the configuration syntax.
- Open the Obsidian command palette (
Ctrl+P/Cmd+P) - Run Gallery View: Create showcase notes
- Choose whether to add the read-only demo server connections (see below), or create the notes only.
- Open the generated
GalleryDemo/folder in your vault to explore working examples of local sources, external URLs, every view, and Immich and Nextcloud sources backed by public demo servers.
Network use
Gallery View only makes network requests for sources you configure, or for demo notes you choose to create:
- Your own sources:
external,immich,immich-share,nextcloudandnextcloud-sharesources contact the server in their URL or connection. External image URLs load only when Allow remote images is on. - Demo servers: the showcase notes for Immich and Nextcloud load photos from public, read-only demo servers run by the plugin's author (
demo-immich.mkshp.devanddemo-nextcloud.mkshp.dev). Create showcase notes asks before adding their connections to your settings. When those notes are open, your IP address reaches that server; access logs are kept for about 14 days. See Try it with the demo servers. - Sample web images: the showcase's External URLs and Mixed sources notes load sample images from
picsum.photoswhen Allow remote images is on. - Sample photos (optional): Create showcase notes and Create use-case notes can download a set of 39 sample photos (about 10 MB) for the use-case notes from
docs.mkshp.dev, the documentation site. This happens once, only when you run one of those commands and leave Download sample photos on in the dialog; the photos are then saved in your vault underGalleryDemo/Use cases/_photos/. See Use cases.
The plugin has no telemetry and sends nothing anywhere else.
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.js # Compiled plugin
├── manifest.json # Plugin metadata
├── styles.css # Gallery styling
├── package.json # Dependencies
├── tsconfig.json # TypeScript config
└── src/ # Source code
├── main.ts # Main plugin code, lifecycle management
├── models/ # Data models
├── views/ # View components
├── services/ # Core services
└── processors/ # Content processing
Contributing
Contributions are welcome! Please feel free to:
- Share usage examples and feedback
- Help with documentation
Development Setup
- Clone the repository
- Run
npm installto install dependencies - Use
npm run devfor development with auto-rebuilding - Test in your Obsidian vault
License
MIT License — see LICENSE for details.
Acknowledgments
- Built for the Obsidian community
Support
If this project helps your workflow, consider supporting its development with a ☕
- Bug reports: GitHub Issues
- Feature requests: GitHub Discussions
- Documentation: Plugin docs