Spotlight

Spotlight

Star a note, folder, or file, and it surfaces on its own shelf at the top of that branch in Obsidian's file explorer — without moving anything on disk.

Spotlight watches one or more folders you choose ("roots"). Inside a root, you can star:

• any Markdown note,
• any subfolder (if you turn on "Spotlight folders too" for that root), and
• any other file — an image, a PDF, a .base, a .canvas, anything.

A starred item keeps living exactly where it already is. Spotlight adds a small "SPOTLIGHT (n)" shelf above the root's normal contents, listing everything starred underneath it. Click a shelf row to reveal and open the real item; click its star to un-star it. Nothing is copied, moved, or duplicated — the shelf is a second way to see items that are already there, allowing you to focus on, or Spotlight, specific items.

Built for ICOR for Life, works anywhere

This plugin was built primarily for the ICOR for Life Obsidian scaffold (https://www.myicor.com), and it's ICOR-aware: on a fresh install, it checks whether the vault is actually running that scaffold (by reading its own .icor-for-life/manifest.json), and if so, it seeds one root for each of the five "My Life" areas that already exist in that vault — Goals, Habits, Key Elements, Projects, and Topics.

But you don't need to be using ICOR for Life to use Spotlight. In any other vault — or once you're past the fresh-install seeding — a root is just a folder path you type into the settings tab. Point it at anything: a work-in-progress folder, a project folder, your whole vault. Add as many roots as you like; remove or disable any of them at any time.

Installation

Not yet on the Obsidian community plugin list. Submission is planned; until it's approved, install it one of these ways:

Via BRAT (Beta Reviewers Auto-update Tool):

1. Install and enable the BRAT community plugin.
2. In BRAT's settings, "Add a beta plugin", and paste this repository's URL.
3. Enable Spotlight under Community plugins.

Manually:

1. Download main.js, manifest.json, and styles.css from the latest release.
2. Create a folder named spotlight inside your vault's .obsidian/plugins/ folder, and put the three files there.
3. Reload Obsidian (or disable/re-enable community plugins), then enable Spotlight under Settings → Community plugins.

How it works

Roots. A root is a folder path, with one on/off switch. Roots can't nest inside or overlap each other — Spotlight refuses an add or an edit that would create that. A disabled root's shelf disappears but its settings are kept.

What's starrable, and where the star lives.

A note's star lives in the note itself — it's just a YAML frontmatter key, so it travels with the note (copy the note anywhere, sync it, whatever) and shows up in a normal frontmatter search. Un-starring a note removes the spotlight: key entirely rather than setting it to false, so a note that's never been starred stays untouched. Writing that key edits the frontmatter block's raw text directly, rather than using Obsidian's higher-level frontmatter API, specifically to preserve the rest of your YAML exactly as you wrote it — comments, key order, quote style — instead of having the whole block reparsed and reserialized for a one-key change. A folder's or a file's star has nowhere similar to live (a folder carries no frontmatter), so those go into the plugin's own data.json under starredPaths instead — which means folder and file stars are local to this copy of the plugin unless your vault as a whole (including .obsidian/plugins/) is what you're syncing. data.json also holds which shelves and branches you've collapsed or hidden, and the roots list itself — none of that is vault content, so none of it syncs unless your plugin folder does.

The shelf. Each enabled root gets its own shelf, showing every starred item under it (notes, folders, and files, all mixed together). Click a row to reveal the real item in the tree and open it; click the star on a row to un-star directly from the shelf. The shelf's own header collapses/expands the list. A separate small tab on the shelf's bottom edge hides or shows everything below it — the real folder tree for that root — useful when you only want the curated shelf visible and don't need to browse the raw contents underneath.

The star you see in the note's own properties above — spotlight ticked on — is the whole mechanism for a note: no separate database, just that one frontmatter key.

Renames and deletes. Moving or renaming a starred item, or a configured root, inside Obsidian keeps its star and its settings attached. A change made outside Obsidian (vault closed, another synced device, a sync client that hasn't caught up yet) isn't seen by those listeners, so a star can go stale — the settings tab has a "Remove stars for missing files" button for that, which only ever runs when you click it, never automatically (so a temporarily-offline synced file is never mistaken for a deletion).

Settings reference

Add a directory — type a folder path and click Add. Refused if the path is already covered by, or would nest inside/around, an existing root.

Active directories — one card per configured root:

• Toggle — track this root or not.
• Trash icon — remove this root from settings. A note's own frontmatter star is untouched either way. A folder's or file's star under this root, stored in data.json, is left in place rather than deleted — it simply stops showing (no shelf, no visible star) until either the same root is added back, or the starred item itself is later deleted, at which point "Remove stars for missing files" (below) will clear it.
• Folder path — editable in place; committed on blur or Enter.
• Counts — how many candidates and how many are currently starred, or a warning if the path doesn't currently exist in the vault.
• Spotlight folders too — lets subfolders under this root be starred and shelved too (folders are always walked and shown normally either way; this only controls whether a folder itself can carry a star).

Clean up stale stars — removes stars kept for files/folders that no longer exist in the vault. Shows a live count; does nothing when there's nothing to clean.

Auto-reveal active file — reports whether Obsidian's own "auto-reveal active file" is on for an open file explorer pane, with a one-way "Turn off" button. Spotlight doesn't turn it on or manage it otherwise; this is here because auto-reveal can scroll the file explorer toward a note that's inside a branch you've hidden with the shelf's own hide toggle (above), and Spotlight has no way to prevent that itself.

Theming

Every color, size, and spacing Spotlight draws is a CSS custom property, so a theme or a CSS snippet can restyle it without touching the plugin. The main ones:

--spotlight-marker        /\* the core accent color — defaults to your theme's own accent \*/
--spotlight-accent        /\* an alias of --spotlight-marker; the shelf border (--spotlight-fence) reads this one \*/
--spotlight-marker-soft   /\* soft background tint for a starred/hovered row, derived from the accent \*/
--spotlight-star-rest     /\* unstarred star color \*/
--spotlight-star-hover    /\* star color on hover \*/
--spotlight-fence         /\* the shelf's border color \*/
--spotlight-fence-width   /\* the shelf's border width \*/
--spotlight-radius        /\* corner radius used across shelf/pill elements \*/
--spotlight-header-text   /\* the "SPOTLIGHT (n)" header's text color \*/
--spotlight-header-font   /\* the header's font \*/
--spotlight-header-size   /\* the header's font size \*/
--spotlight-kicker-tracking /\* letter-spacing on the header label \*/
--spotlight-hover-bg      /\* row hover background \*/
--spotlight-pill-tint     /\* the directory pill's background tint (settings tab) \*/
--spotlight-pill-height   /\* the directory pill's height \*/
--spotlight-pill-radius   /\* the directory pill's corner radius \*/

By default these derive from your theme's own accent and background tokens, so Spotlight should look at home in most themes with no snippet needed.

Known limits and conflicts

• Mobile is supported, tested on iPhone and iPad. A few things work differently there: long-press a shelf row to remove it (there is no right-click), a "Star or unstar this note" command is available for Obsidian's mobile toolbar, and the shelf's tap targets are larger. Desktop looks and behaves exactly as before.

• Depends on Obsidian's internal file-explorer structure, not only its public API. The shelf is drawn directly into the file explorer's own internal row structure (its per-file DOM elements and its virtualized list), which Obsidian doesn't document or guarantee as stable, plus one specific undocumented method (revealInFolder(), used to scroll to and highlight a row when you click a shelf item — called behind a feature-detection guard, so its removal degrades to "opens the note without the scroll/highlight" rather than an error). A future Obsidian release that reworks the file explorer internally could break the shelf until this plugin is updated to match.

• A star can go stale if a starred item is moved, renamed, or deleted outside Obsidian — while the vault is closed, from another synced device, or before a sync client has caught up. Spotlight only learns about renames and deletes through Obsidian's own vault events, so a change made outside those events isn't detected until you run "Remove stars for missing files" yourself in Settings. This is deliberate: automatically pruning on every load would risk deleting a real star for a file that's simply still syncing down.

• Iconize (obsidian-icon-folder) — set its custom icons before starring a row, or disable Spotlight while assigning them. Iconize decides whether to draw an icon based on how many child elements a row already has; once Spotlight has added its star element to a row (even after un-starring), that row's child count no longer matches what Iconize expects, and an icon assigned afterward won't render. Spotlight checks whether Iconize is enabled (through Obsidian's own installed-plugin list) and shows a notice about this once per session.

• Stock/default accent colors can fail contrast on some Spotlight elements. The directory pill and a few other elements read your theme's own accent color at a modest opacity; a theme (or Obsidian's own default purple accent at certain lightness values) can land under the WCAG AA 4.5:1 text-contrast floor at that opacity, with no tint value that fixes it for every possible accent. This is a property of the theme's own accent, not something Spotlight's CSS alone can guarantee against — override the relevant token (see Theming, above) if you hit this.

On mobile:

Development

No build step — main.js is hand-written CommonJS, and it's exactly what Obsidian loads. Edit it directly.

npm test

runs the plugin's test suite (Node's built-in test runner, no dependencies to install) against a small stub of the obsidian module, covering settings, discovery/classification, the storage layer, and the file-explorer integration logic.

See CONTRIBUTING.md before opening a pull request.

Credits

Built by Matt Zymet (@zymetm).

Not affiliated with or endorsed by ICOR for Life or Paperless Movement. "ICOR for Life" refers to a separate, independently maintained Obsidian vault scaffold; this plugin only reads that scaffold's own small machine-readable manifest file to detect whether it's installed, and reproduces none of that suite's own code.

License

MIT © 2026 Matt Zymet