Beacon

Beacon is a compact, theme-aware search and heading navigation plugin for Obsidian on desktop and mobile. Search the focused Markdown note or the entire vault while the query stays untouched when switching scope—no injected path: prefix and no directory text.

In-file heading navigator

Open the heading navigator to browse the outline for the focused note. It shows rendered Markdown titles with their H1–H6 hierarchy and nesting, keeps the full outline visible while you search, and supports keyboard navigation with the arrow keys, Enter to cycle matches, and Shift+Enter to jump. Jumping selects and highlights the full destination heading line in the editor until the next editor action.

Features

• This file / All files / Properties / Tags search-mode dropdown with icons and a remembered file-search default.
• A middle-right heading navigator for the focused note with hidden-track scrolling.
• Heading searches keep the full outline visible and highlight matches in place; Enter cycles matches and Shift+Enter jumps to the selected heading.
• Rendered Markdown excerpts with theme-accent match highlights.
• File and Markdown-rendered heading hierarchy shown above every excerpt, including links and inline formatting.
• Exact quoted word and phrase matching, exclusions, OR, regex, and field operators.
• Optional fuzzy matching controlled only from the plugin settings.
• Optional heading-match exclusion hides heading-only result cards while retaining heading breadcrumbs.
• Optional Excalidraw Data exclusion omits generated drawing payload sections.
• Optional Excalidraw Data exclusion for the heading navigator hides that heading and its nested headings.
• Vault-relative paths and glob patterns can exclude files from every search mode.
• Ordinary file searches omit YAML properties and tag tokens; Properties searches and shows only YAML property content, while Tags searches and shows only tag values.
• Property and tag modes have dedicated commands and no separate settings toggles.
• Icon-only relevance, file name, location, and modified-date sorting. The chosen sort survives restarts.
• Unified segmented search bar with icon-only scope and sort controls; their menus retain descriptive text.
• Results appear in a separate theme-native panel with hidden-track scrolling and no command footer.
• No close control; click outside or press Esc to dismiss the search.
• Clicking a result opens its note and selects the exact match until the next editor action.
• Incremental in-memory indexing, shared in-flight reads, debounced input, immediate stale-search cancellation, and frame-budgeted rendering for large vaults.
• Keyboard navigation and commands for every switchable option.
• Responsive phone and tablet layouts with safe-area support, touch-sized controls, and software-keyboard-aware sizing.

Mobile

Beacon supports the same search modes, query syntax, sorting, rendered results, result jumps, and heading navigator on Obsidian Mobile. The panels follow the visible screen as the software keyboard opens, respect device safe areas, use touch-sized controls, and avoid reopening the keyboard after a result or heading jump. Mobile indexing and Markdown rendering yield in smaller batches to keep scrolling and typing responsive while preserving the desktop behavior and layout.

Open global search from the Search all files ribbon icon or the command palette, or add any Beacon command to Obsidian's mobile toolbar or Quick Action. Each command has its own distinct icon. To configure the native toolbar, open Settings → Interface → Configure mobile toolbar → Add a command... and search for Beacon. See Obsidian's mobile toolbar guide for adding and reordering commands. With a hardware keyboard connected, use the built-in panel keys listed below.

Query syntax

Operators are optional. Changing search mode never modifies the search term. Properties and Tags search across the vault and isolate their respective content types.

Commands and hotkeys

Assign global shortcuts for launching Beacon from the editor in Settings → Hotkeys → Beacon. Inside an open Beacon panel, use the built-in keys in the table. Customized global command shortcuts are not dispatched to the panel, so assigning a different shortcut there does not remap its built-in keys.

While the search panel is open, Mod+Alt+F toggles between current-file and all-files search, Mod+Alt+S cycles sorting, the arrow keys navigate results, and Enter opens the selected result. In the heading navigator, Enter cycles matching headings, Shift+Enter jumps to the selected heading, and the arrow keys move through the full outline.

The previous/next, open selected, next matching heading, and close commands operate on the open Beacon panel. Open selected result or heading opens the selected search result or jumps to the selected heading; Select next matching heading matches the heading navigator's Enter action. No global hotkeys are assigned by default.

All twelve commands can be configured in the native mobile toolbar. Beacon does not add a toolbar inside its panels. Whether Obsidian's editor toolbar remains reachable while a Beacon panel is open has not been verified on physical iOS/Android; use the panel's existing touch controls or built-in keys if the editor toolbar is covered.

Settings

• Blur background controls whether the note behind the search panel is blurred. It is on by default and applies the next time search is opened.
• Fuzzy matching enables inexact matching without adding a control to the search bar.
• Exclude heading matches hides search cards caused only by heading-line matches.
• Exclude Excalidraw data omits generated drawing content from ordinary search.
• Excluded files accepts one vault-relative file, folder, or glob per line, such as Archive/, Private.md, or *.excalidraw.md.
• Exclude Excalidraw data from heading navigator hides the Excalidraw Data outline branch.
• Result limit caps rendered results to keep repeated searches responsive.

Installation

After the plugin is accepted into the Community Plugins directory:

1. Open Settings → Community plugins → Browse in Obsidian.
2. Search for Beacon, select it, and choose Install.
3. Enable the plugin.

For a manual installation, download main.js, manifest.json, and styles.css from the latest GitHub release and place them in:

<vault>/.obsidian/plugins/vault-searchlight/

The plugin ID and install folder remain vault-searchlight for update continuity. Reload Obsidian, then enable Beacon under Community plugins.

Privacy

Beacon performs indexing and searching locally inside Obsidian. It makes no network requests and includes no analytics or telemetry.

Development

npm install
npm test
npm run build

For local development, symlink this project into that plugin directory and run npm run dev.

Preparing a release

Set matching versions in manifest.json and package.json, and add the version and minimum Obsidian version to versions.json. Push a version tag such as 1.5.2 to run Prepare release, or run that workflow manually with an existing version tag. The tag must match the manifest version exactly, without a v prefix.

The workflow runs the tests, lint, and production build, generates GitHub build-provenance attestations for main.js, manifest.json, and styles.css, and uploads those same files to a draft release. Review the generated release notes and publish the draft when ready. Existing releases and assets are never replaced; delete an unwanted draft before retrying its tag.

After downloading a release asset, verify its provenance with the GitHub CLI:

gh attestation verify main.js --repo BenGutteridge1/beacon
gh attestation verify manifest.json --repo BenGutteridge1/beacon
gh attestation verify styles.css --repo BenGutteridge1/beacon

License

MIT