# Visual 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 - 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 `cover` frontmatter 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](docs/EXPLORER_022.md). 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](https://community.obsidian.md/plugins/visual-gallery). 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](https://github.com/yidachen-14/obsidian-visual-gallery/releases): 1. Download `main.js`, `manifest.json` and `styles.css` from the same release. 2. Create `/.obsidian/plugins/visual-gallery/` and put those three files inside it. 3. 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. ## 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. Delete still acts on the pressed item only and uses Obsidian's confirmation/trash preferences. Desktop mouse behavior is unchanged. 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. **Delete uses Obsidian's native deletion flow and preferences.** If you disabled confirmation or selected permanent deletion in Obsidian, those preferences also apply here. The card menu acts on the right-clicked item, not the entire selection. 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 `/.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. ## 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](docs/MOBILE_019.md). 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: ```sh corepack enable corepack prepare pnpm@10.12.1 --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](docs/CARD_GEOMETRY.md) and [development constraints](AGENTS.md). 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](LICENSE) for this project's license and [THIRD_PARTY_NOTICES.md](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](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](https://github.com/yidachen-14/obsidian-visual-gallery/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](docs/DEVELOPMENT_HANDOFF.md). 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.