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)

Keyboard shortcuts

When the search input is focused:

Search scopes

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

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

Settings

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