Obsidian Stats logoObsidian Stats

Star QMD

by starhunter
5
4
3
2
1
New Plugin
Install Code

Description

This plugin has not been manually reviewed by Obsidian staff. Search your vault with the qmd CLI using BM25, vector, and hybrid semantic retrieval.

Reviews

No reviews yet.

Stats

stars
downloads
0
forks
0
days
NaN
days
NaN
days
0
total PRs
0
open PRs
0
closed PRs
0
merged PRs
0
total issues
0
open issues
0
closed issues
0
commits

Latest Version

Invalid date

Changelog

See all version on GitHub

README file from

Github

English | 한국어

Star QMD

An Obsidian plugin that wraps the qmd CLI so you can run BM25 / vector / hybrid (deep) semantic search directly inside your vault.

Features

  • Three search modes
    • BM25 — fast exact keyword matching (optional live search as you type)
    • Vector — embedding-based semantic similarity
    • Deep — query expansion + reranking (3–10s, most accurate)
  • Sidebar + modal — two UIs sharing result cards, shortcuts, history, and tips
  • Search scopes — limit search to a folder prefix, with a per-scope command auto-registered
  • Index status card — doc/vector counts, last update, stale badge, index/embedding refresh with live progress
  • Find similar to current note command — uses the active file as a vector query
  • Search selected text command — one step from editor selection to search
  • Result context menu — open in new tab / split / copy markdown link / copy path / reveal in file manager
  • Hover page preview — native Obsidian preview when hovering a result card
  • Result mtime + per-mode score chips — visually distinguish recency and match source
  • Auto suggestions on zero results — chips to retry instantly with another mode/scope
  • Empty-state tip card — query syntax cheatsheet + recent search history
  • Copy full error — copy a truncated error message in one click
  • Embedding refresh confirmation modal — prevents accidents, exposes the --force option
  • Auto-growing textarea — long deep-search queries at a glance
  • Highlighting — query terms emphasized in result titles/paths/snippets
  • a11y — listbox/option roles + aria-live result count
  • Korean / English i18n — auto-detect, or pick the language explicitly in settings

Prerequisites

The qmd CLI must be installed.

# After installing qmd, register your vault as a collection
qmd collection add vault ~/Documents/YourVault
qmd update         # index
qmd embed          # vector embeddings (for vector / deep search)

See the qmd docs for full installation details. Desktop only on macOS / Linux (isDesktopOnly).

Installation

BRAT (recommended)

  1. Install BRAT in Obsidian
  2. "Add Beta Plugin" → add starhunt/star-qmd
  3. Enable it in the plugin settings

Manual

  1. Download main.js, manifest.json, styles.css from Releases
  2. Create <vault>/.obsidian/plugins/star-qmd/ and copy the three files there
  3. Enable it under Obsidian → Settings → Community plugins

Usage

Commands (Cmd+P)

Command Description
QMD: Search Open the default search modal
QMD: Vector search Open the modal in vector mode
QMD: Deep search Open the modal in hybrid mode
QMD: Open sidebar Search view in the right sidebar
QMD: Find similar to current note Use the active note's body as a vector query
QMD: Search selected text Search using the text selected in the editor
QMD: Search in {scope} Auto-registered per defined scope
QMD: Open install guide qmd CLI install guidance modal
QMD: Update index Re-index changed documents
QMD: Refresh embeddings Generate/refresh vector embeddings

Keyboard shortcuts

When the search input is focused:

Key Action
Enter Search if the query is new, otherwise open the active result
Shift+Enter Newline while typing; open in a new tab while navigating results
↑ ↓ Move between results
Tab Cycle search mode (modal only)
Esc Close (modal only)

Search scopes

Useful when you want to search the same keyword within a specific folder only. Built-in scopes:

Name Folder prefix
LLM Wiki 500-Wiki/
Insights Insights/
Projects 100-199

Add/edit freely in the settings tab. Folder names with spaces, underscores, @, +, etc. are matched via normalized comparison.

Settings

Item Description
Language Plugin UI language — Auto Detect / 한국어 / English
QMD binary path Location of the qmd executable (default: looked up from PATH)
Default search mode BM25 / vector / deep
Result limit 5–50
Default collection qmd collection name filter (empty = all)
Show scores Show relevance score chips on results (per-mode colors)
Chunk preview Show matched text snippets
Highlight query terms Emphasize query terms in previews
BM25 live search Search as you type (debounced)
Live search debounce (ms) 100–1000
Show modification time File mtime on the right of result cards
Hover page preview Hover a result card → Obsidian page preview
Index stale threshold Show a stale badge when the last update is older than this (hours)
Confirm before embed refresh Confirmation modal before refreshing embeddings
Search scopes Add/remove your frequently used folder scopes
Default scope Scope applied automatically when searching

About the language setting: Auto Detect follows the Obsidian/browser locale. Picking 한국어/English explicitly changes the UI immediately, but command palette and ribbon icon names update only after restarting Obsidian.

Known behavior / implementation notes

  • execFile + qmd 8KB truncation workaround: the qmd CLI truncates output at 8192 bytes when stdout is a direct pipe, so we wrap it with /bin/sh -c '"$0" "$@" | cat' (argument injection is blocked by the shell's "$@" pattern).
  • Unicode-aware path normalization: qmd converts @, +, _, spaces, etc. in filenames to hyphens/lowercase, so when matching a result URI to the actual vault file we compare after normalizing to \p{L}\p{N} only.
  • YAML frontmatter filtering: snippet lines like key: value or - "[[link]]" are removed as noise so only the body is shown. If the match is only in frontmatter, the snippet is left empty.

Development

# Install dependencies
npm install

# Watch mode (development)
npm run dev

# Production build (type-check + bundle)
npm run build

# Unit tests (vitest, 50 search-utils cases)
npm test

The build artifact (main.js) is in .gitignore. Ship it only with releases.

Deploy straight to a vault:

cp main.js styles.css manifest.json \
   ~/Documents/YourVault/.obsidian/plugins/star-qmd/

License

MIT

Sponsors