README file from
GithubVisual Gallery
Browse your Obsidian vault as a visual card gallery, with thumbnails of the whole Canvas, not just its first image. Visual Gallery is an independent community plugin, with desktop and mobile interaction paths starting in 0.1.19.
Features
-
Independent gallery heading size: default 24px, adjustable 18–40px under Interface; card title sizing remains separate. Existing-file tab activation has no reveal flash.
-
Adjustable title font size (12–22px, default 14px) under Card layout. Compact, flat list rows use horizontal dividers; click Name, Last viewed, Modified or Created to reverse sorting. Last viewed is local history and unseen files remain last.
-
Craft-style Masonry / Grid / List views with an icon-only segmented switch before Create, Sort and Filter. Each folder remembers its own view on this device. Switching keeps selection, sorting/filtering and the visible file as a scroll anchor while previews finish loading.
-
Equal-height grid cards with titles above formatted document previews; variable-height masonry with bounded content; compact list rows with miniature previews, summaries and last-viewed/modified/created dates. Date columns disappear as the pane narrows. Last viewed is local history, shown as a dash until recorded.
-
Notes preserve headings, lists, tables, code and local images in a bounded, inert Markdown preview with a fading lower edge. Explicit covers retain priority. Preview work is queued and unloaded when the view changes; note embeds and common query fences are not expanded. Craft is a visual reference; no Craft code or assets are included.
-
Whole-Canvas previews: text, groups, connections, local images, Markdown excerpts and nested Canvases.
-
Markdown covers from
coverfrontmatter or the first embedded local image; readable excerpts for notes without covers. -
Image previews and locally rendered PDF first-page thumbnails.
-
Folder cards, breadcrumbs, file-type filters and Obsidian-style sorting by name, modification time or creation time in either direction.
-
A dedicated Visual Gallery files tab in the left sidebar. Expand/collapse folders, click a folder to locate the gallery, click a file to select it, and double-click a file to open a new tab. It shows every file loaded by Obsidian, including types without gallery cards, and retains the host file explorer's context menus, rename, clipboard and drag/drop operations. Its expansion state is independent of the original Files tab. Markdown rows show NOTE in the same type-badge position as CANVAS. Closed/open folder icons turn into right/down arrows on hover; recursive file counts appear at the right. The vault-name Home button returns to the top-level gallery. Reopen it with Open Visual Gallery file browser in the command palette. Requires the Files core plugin.
-
Single-click to select; double-click to open. Command/Ctrl-click toggles individual cards, Shift-click selects a range, and dragging blank space selects a rectangle. Escape or a blank-space click clears selection.
-
On mobile, tap to open and long-press to enter selection mode and show actions. Tap more cards to toggle selection, then long-press a selected card and choose Move selected items…. Choose a destination folder and confirm Move here. Scroll and pinch gestures do not start selection. Tap blank space or choose Clear selection to exit selection mode.
-
Drag files from Finder/system file managers into the gallery to copy them into the current folder, or onto folder cards/breadcrumbs to import into that destination. Directories and collision naming use Obsidian’s native importer; originals are preserved.
-
Drag vault files and folders to gallery folders, breadcrumbs or the native file explorer. Dragging an unselected card works immediately; dragging a selected card moves the selection.
-
Right-click a card to rename it, delete it or reveal its original file in Finder/system file manager. Right-click blank space to create a note, Canvas or folder, in that order.
-
Right-click a folder or supported file in the native file explorer and choose Show in Visual Gallery. Folders open their contents; files open their parent gallery and become selected, even if the previous gallery filter hid them.
-
18 interface languages: English, Simplified Chinese, Traditional Chinese, Japanese, Korean, German, Spanish, French, Italian, Brazilian Portuguese, Russian, Ukrainian, Dutch, Polish, Turkish, Indonesian, Vietnamese and Thai. New installations default to English; upgrading preserves your choice.
-
Adjustable card width, gallery heading, independent folder/note light/dark cover gradients, folder icons and ribbon icons.
-
Local thumbnail caching, lazy generation, progressive rendering and automatic removal of stale or orphaned previews.
Favorites and device state
Right-click a folder in the file tree and choose Pin in Visual Gallery. Pinned folders appear below the vault Home button; click a shortcut to locate that folder in the existing gallery. Use its unpin button or native folder menu to remove it. The pinned section can collapse. Renaming/moving a folder updates its shortcut and descendant shortcuts. A folder not yet available on this device stays listed as unavailable until it arrives or you unpin it.
Settings and pins merge across devices when your existing vault sync transfers
this plugin's data.json. Enable community-plugin settings sync in that service.
Visual Gallery does not connect to a sync provider itself. Different preference
fields merge independently; unpin records prevent old snapshots from restoring
removed pins. Changes are read on external-settings notifications and a 5-second
poll. See state and merge details.
Per-folder display modes and scroll positions, last-viewed dates, the current gallery folder, current filter/sort, scrolling, card width, tree expansion and favorite-section collapse are stored locally on each device. Browsing does not rewrite shared plugin settings. Existing custom colors, icons and language migrate without resetting. Obsidian continues to manage its own workspace/pane layout independently.
Installation
Visual Gallery is listed in the Obsidian Community directory. In Obsidian, install it from Settings → Community plugins → Browse when the catalog has propagated to your client.
You can also install manually from the GitHub releases:
- Download
main.js,manifest.jsonandstyles.cssfrom the same release. - Create
<vault>/.obsidian/plugins/visual-gallery/and put those three files inside it. - Reload Obsidian and enable Visual Gallery in Settings → Community plugins.
PDF rendering is included in main.js; no separate worker, external service or download is needed. When updating manually, disable the plugin, replace those three files, and re-enable it. Keep your data.json to retain settings.
Library workflow
- The button above the file tree defaults to the vault name. Change Library home name in Interface; leave it blank to restore the vault name.
- New defaults use a closed folder for folder cards and Home for navigation. Saved custom icons are retained. Both icon settings open a searchable grid of Obsidian's registered icons, with current-selection feedback and keyboard navigation. Search accepts icon names/IDs and translated common families such as folders and Home.
- Grid, masonry and list share a bounded page width (1120 px content maximum). Cards keep their preferred width in wide panes and compress when the pane narrows. The title and icon toolbar remain on one row.
- Creating a note or Canvas selects it in the current gallery without opening it. Opening from the gallery or its sidebar activates an existing file tab, or creates one new tab while retaining the gallery. Concurrent requests for the same file share one open operation.
- For multiple selections, Delete first shows the complete batch for confirmation. Cancel leaves originals untouched. The count-labelled new-folder action moves the selected originals into one sibling folder; name collisions and stale selections are rejected, and interrupted moves attempt safe rollback. Partial failures are reported.
Usage
Click the gallery ribbon icon, or run Visual Gallery: Open Visual Gallery in the command palette. The gallery restores this device's last folder; on a first visit it uses the active note's folder. Use breadcrumbs to navigate, the file-type filter to narrow the cards, and the sort menu to reorder files. Folders remain first and sorted A–Z, like the native file explorer.
For multiple selections, use Command on macOS or Ctrl on Windows/Linux. Command/Ctrl+A selects currently displayed filtered cards. Shift-click and Shift+arrow keys extend a range. Drag from blank gallery space to select files and folders together.
On iPhone, iPad and Android, use the touch selection and destination menu described above instead of desktop HTML drag-and-drop or modifier keys. The mobile card menu omits Finder/system file manager and omits Rename when multiple items are selected. Single and multiple selections always show a deletion confirmation. The header retains exactly Create (+), Sort, Filter, with larger mobile touch targets.
Drag-and-drop and rename act on original files, not previews. Moves through gallery targets check name conflicts and invalid folder nesting before starting the batch. If a disk error interrupts a batch, a notice reports how many items moved; already completed moves are not automatically rolled back. Link updates follow Obsidian's preferences. Back up your vault before reorganizing important files.
Every deletion requires confirmation, even if native deletion prompts are disabled. All deletion respects Obsidian's trash-location preference. Multi-selection menus omit Rename and Finder/system reveal, and can create a folder containing all selected items.
Settings-save failures display a translated notice; local edits are retained for the existing automatic sync retry. Cache-clear failures display a notice and restore the button so you can retry.
Settings include a read-only cache location and Clear thumbnail cache. Clearing the cache removes disposable previews only; the next gallery visit regenerates them. Commands can also rebuild all Canvas previews or generate a preview for the active Canvas.
Settings are grouped into Interface, Card layout, Browsing defaults, Icons, Folder cover colors, Note card cover colors and Thumbnail cache. Changing the interface language updates the gallery, settings, command names and ribbon tooltip immediately; it never renames your files or replaces your custom title. The header keeps the folder title alongside three icon-only buttons, in order: Create (+), Sort, Filter. Clicking + opens a native menu ordered New note, New Canvas, New folder; choosing an action then opens the existing naming dialog. Sort and Filter open their respective native text menus. Hover tooltips and accessible labels are translated and show the current sort/filter. Sort and Filter menus mark the active choice; an active filter tints its icon. The title and buttons stay on one row, including narrow windows and very few cards. Only the header expands when needed, without changing card/grid widths. Folder cards and breadcrumbs use Obsidian's native navigation history. The pane's Back/Forward arrows, mouse side buttons and configured native navigation shortcuts share that history, including returning from a note opened in the same pane. Each visited gallery page retains its filter and sort. A new folder destination after going back clears the old forward branch.
Privacy and storage
- No account, payment, ads, telemetry or analytics are required.
- The plugin makes no network requests, uploads no vault contents and loads no remote thumbnail images. Link nodes show a simplified URL card; remote covers are not fetched.
- Preview generation reads files within the vault. Settings and generated WebP (or PNG fallback) previews are stored inside the plugin directory, normally
<vault>/.obsidian/plugins/visual-gallery/thumbnail-cache/(or the vault's custom configuration directory). - Canvas rendering does not modify the source board or notes. Rename, move, create and delete happen only through the corresponding user actions. Automatic cleanup removes this plugin's generated cache entries, never original vault files.
- Show in Finder/system file manager resolves the original vault item's local path and asks the operating system to reveal it. It does not read arbitrary files outside the vault.
- Any synchronization service you configured for the vault may also synchronize the plugin's cache and settings. Cache files contain visual previews of your notes.
- The plugin does not install or update itself; updates use Obsidian or manual installation.
Community review disclosures: vault enumeration is needed to list files and rebuild previews. Base64 conversion handles local binary data and older WebViews. The pinned PDF.js source contains optional WASM filenames, but no WASM assets are shipped or enabled. The build removes dynamic compilation and replaces PDF.js fetch/XHR/worker fallback paths with explicit denial functions; remote module imports are blocked. The embedded local worker is created by Visual Gallery itself. See the review remediation notes for the audit boundary and verification.
Compatibility and limitations
Obsidian 1.13.7 or newer is required. 0.1.19 removes the desktop-only installation restriction and implements iOS/iPadOS/Android touch support. Keep Obsidian and your OS/WebView updated. Native desktop UI integration was previously tested on macOS with Obsidian 1.13.7; Windows/Linux-specific file-manager behavior has not been independently tested.
Mobile validation covers official Obsidian 1.13.8 on Android phone/tablet emulators: plugin enablement, local Canvas/image/PDF thumbnails, native menus, touch selection and batch moves, cache cleanup/rebuilding, offline app restart and portrait/landscape layouts. iPhone/iPad simulator WebKit rendering and touch-logic checks also pass, but use substituted Obsidian APIs and are not iOS Obsidian E2E. Physical devices, older OS/WebViews and full iOS Obsidian integration remain unverified; compatibility with every mobile device is not claimed. See mobile support and verification.
On mobile, Canvas generation is limited to one concurrent job and a 1024 px maximum dimension, with one nested level, to reduce memory pressure. PDF thumbnails have a 900 px size cap. If ImageBitmap or WebP encoding is unavailable, local HTML image decoding and correctly named PNG caching provide fallbacks. PDF worker startup errors/timeouts show an unavailable preview without hanging the thumbnail queue; no remote worker is fetched. Existing desktop rendering limits remain unchanged.
Canvas previews are a Canvas2D reconstruction, not screenshots of Obsidian's Canvas. Full Markdown layout, remote embeds, custom plugin nodes and theme-specific details are not reproduced exactly. Very wide or tall boards preserve the whole board, so individual nodes may look small.
Interoperability with the native file explorer uses a guarded internal drag API. If that API changes, the adapter may need an update. PDF previews show only the first page and do not prompt for encrypted-document passwords.
Development
Use Node.js 22 and pnpm 10.12.1:
corepack enable
corepack prepare [email protected] --activate
pnpm install --frozen-lockfile
pnpm run build
The build runs the type checker and tests before generating main.js. pnpm run dev watches source files. Use a disposable test vault for file-management testing. Build outputs and personal vault contents are not committed.
Card styles follow the locked card geometry contract and development constraints. The build rejects an inset or duplicate outline implementation. Changes also require real-host rendering checks of all four corners in ordinary, selected and drop-target states, in both themes.
The bundled PDF.js 5.4.624 worker is loaded as a local module Blob and released when the plugin unloads. Remote PDF worker/asset fetching, dynamic font evaluation and optional WebAssembly loading are disabled. This version is tested against Obsidian 1.13.7's embedded browser. Third-party attribution and the full PDF.js license are embedded in the distributed bundle as well as included in this repository.
License and credits
See LICENSE for this project's license and THIRD_PARTY_NOTICES.md for attribution and third-party licenses. PDF.js is licensed under Apache-2.0; its full license is also in PDFJS_LICENSE.txt.
Rendering and cache design draw on Embed Canvas, Gallery Navigator, the JSON Canvas specification and the official Obsidian sample plugin, as documented in the notices. This plugin is not an official Obsidian product.
Report problems through GitHub Issues, including the plugin version, Obsidian version, operating system and reproduction steps. Do not post private vault contents.
Continuing development on another computer
Clone this repository and read the development handoff. It records the released baseline, settled interactions, build commands, native verification boundaries and publication steps. Codex conversation history and local credentials are separate from this repository.