HTML Gallery

日本語版 README · Plugin page

Browse the HTML files, PDFs, SVGs and images in your vault as thumbnails and jump to the notes that reference them.

If you save generated diagrams and documents next to your notes, you know the problem: you remember the picture, not the file name or the folder. HTML Gallery shows each file as a thumbnail so you can find it by eye, and puts a button under each one that leads to the notes linking to it.

HTML is on by default. SVG, raster images and PDF are each a separate switch under Settings, off until you turn them on.

What you get

• Every HTML file in the vault shown as a scaled-down live thumbnail.
• Optionally PDFs (first page rendered as the thumbnail, with page count and full-text search over the first pages), SVGs (searchable by <title>, <desc> and their text) and raster images.
• A Backlinks button on each card opens the notes linking to the file in one click. Files nothing links to get "Same folder" candidates instead, and you can turn a candidate into a real link from the same menu.
• Search by file name, title and page text, and sort by date or folder. Sorting by folder groups the cards under folder headings.
• Filter by folder. You can also right-click a folder in the file explorer to narrow the gallery to it.
• An "Unreferenced" toggle in the header shows only the files that no note links to.
• Click a card for a full-size view. Scripts run there, so interactive and library-based pages look the way they should. PDF cards open in Obsidian's own PDF viewer instead.
• Right-click a card to copy an embed link or the path, reveal the file in the explorer, or open it in the default app.
• A command that inserts a link to a file from the current note's folder that the note does not link to yet.
• Keyboard friendly: arrow keys move between cards, Enter opens, / jumps to the search box.
• English and Japanese UI.

Screenshots

The screenshots use the sample content in examples/. Copy that folder into a vault to try the plugin with the same files.

Each card has a button that lists the notes linking to the file. Files that nothing links to get a dashed "Same folder" button with the closest notes in the same folder instead.

Script-rendered pages show a text fallback in the grid, but the enlarged view always runs scripts, so the chart renders as intended.

Search matches file names, titles and body text, including the text of PDFs and the labels in an SVG. Here "queue" narrows eleven files down to six, across all three formats.

Requirements

• Enable "Detect all file extensions" under Settings → Files and links. Without it Obsidian does not treat HTML as vault files and the gallery stays empty
• Files must be inside the vault
• PDF thumbnails use the PDF.js copy that ships with Obsidian, so nothing is downloaded and nothing leaves your machine. Scanned PDFs have no text layer, so they are only findable by file name; this plugin does not do OCR

Installation

Install it from the community plugin directory: community.obsidian.md/plugins/html-gallery. The "Add to Obsidian" button there opens the plugin in Obsidian. You can also search for "HTML Gallery" under Settings → Community plugins → Browse.

Manual install: put main.js, manifest.json and styles.css from a release (or from your own build, see below) into <vault>/.obsidian/plugins/html-gallery/, then enable HTML Gallery under Settings → Community plugins.

Open the gallery from the ribbon icon or the command "HTML Gallery: Open gallery".

On mobile there is no ribbon bar. The command palette is the reliable way in: run "Open gallery". Long-pressing a folder in the file explorer gives the same menu as right-clicking one. Adding "Open gallery" to the toolbar at the bottom of the screen makes it one tap away; it can be added from the mobile toolbar settings.

Commands

Settings

Sample content

examples/ holds a small set of diagrams and notes that exercise every behaviour: linked and unlinked HTML, a file with two backlinks, two script-rendered pages that fall back to a text thumbnail, and an index.html that is hidden by default. Copy the folder anywhere inside a vault to try it.

Development

TypeScript + esbuild, the same layout as the official Obsidian sample plugin.

npm install
npm run build   # type-check and emit main.js
npm run dev     # watch mode
npm run lint    # same rules as the community plugin review (eslint-plugin-obsidianmd)
npm test        # unit tests for the pure helpers (vitest)

Symlink this repository into a vault's plugin folder so every build is picked up by Obsidian:

ln -s "$(pwd)" "<vault>/.obsidian/plugins/html-gallery"

Reload the plugin with the Obsidian CLI (obsidian plugin:reload id=html-gallery) or with "Reload app without saving" from the command palette. Errors show up in the developer console (Cmd+Option+I / Ctrl+Shift+I).

Release steps are in RELEASING.md (Japanese).

Source layout

Implementation notes

• Thumbnails load the real file in an <iframe> with a fixed 1280px virtual viewport and scale it down with CSS, so responsive pages keep their desktop layout. Only cards near the viewport are loaded
• Scripts are off inside thumbnails by default. Pages whose body text is nearly empty (script-rendered) get a text preview built from <title> and body text instead of a blank card
• Never combine allow-scripts and allow-same-origin in one sandbox attribute. Thumbnails default to allow-same-origin; thumbnails with scripts enabled and the enlarged view use allow-scripts
• Use vault.adapter.getResourcePath() for iframe src. Do not build file:// URLs by hand
• Never assign file content to innerHTML. Titles and text are extracted with DOMParser
• Do not call detachLeavesOfType in onunload
• SVGs and images are shown with <img>, never inlined and never in an iframe: an SVG loaded through <img> is in the SVG spec's secure static mode, so scripts inside it never run and it fetches no external subresources
• PDFs are rendered with loadPdfJs(), the PDF.js copy Obsidian ships. No bundled dependency, and the cmap / standard-font / wasm paths under /lib/pdfjs/ must be passed to getDocument or CJK pages come out blank
• At most two PDFs are open in PDF.js at a time, and a render is cancelled (with the document destroyed) when its card scrolls out of view, so fast scrolling cannot pile up worker threads
• A failed thumbnail keeps its placeholder and gets an is-error class. Nothing is swapped into the DOM, because rebuilding a card is what the iframe rule above forbids

CSS hooks

Cards carry data-kind="html|svg|image|pdf" and their thumbnail box carries is-kind-<kind>, so a snippet can style one kind. Every kind uses the same box ratio, --html-gallery-shot-ratio (1280 / 920); a PDF page is cropped to the top to fill it, the way an HTML thumbnail shows only the top of the page.