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