Vault Search

A local search and browsing UI for markdown knowledge vaults. Point it at any folder of .md files and get fuzzy search, tag filtering, a live markdown preview, and Obsidian-style [[wikilinks]] resolved into clickable note-to-note links with backlinks.

Built as a companion to Ars Contexta — a Claude Code plugin that generates personalized knowledge vaults from conversation — but works with any Obsidian-compatible markdown vault.

Setup

bun install

Configuration

Copy .env.example to .env and edit as needed — Bun loads it automatically:

cp .env.example .env

Variable	Default	Description
NOTES_DIR	(required)	Path to your markdown notes folder
IGNORED_PATHS	(none)	Comma-separated paths to ignore, relative to NOTES_DIR

The following paths are always ignored regardless of config: .obsidian, .trash, attachments, node_modules, templates.

Example .env:

NOTES_DIR=~/vault
IGNORED_PATHS=archive,journal/private,inbox/scratch.md

Usage

Build index and serve:

bun run dev

Opens at http://localhost:3000

Rebuild index only:

bun run index

Watch mode (auto-reindex on file changes):

bun run watch
# Then in another terminal:
bunx serve .

Themes

A floating theme picker (top-right corner) lets you switch themes. Your choice is saved in localStorage.

Theme	Description
Light	Warm paper — the default
Dark	Warm ink — low-contrast dark with the same terracotta accent
Catppuccin Mocha	Catppuccin Mocha palette with Mauve accent

Theme definitions live in styles/themes.css as CSS custom property overrides on [data-theme]. Adding a new theme is a small, self-contained change — see Contributing.

Keyboard Shortcuts

Key	Action
/	Focus search
Escape	Clear search
↑ / ↓	Navigate notes

Expected Frontmatter

The indexer reads YAML frontmatter from your markdown files. All fields are optional:

---
title: My Note Title
date: 2025-02-20
tags: [design, figma, components]
category: work
---

If title is missing, the filename is used. If date is missing, the file's modification date is used.

Wikilinks

Notes can reference each other using Obsidian-style wikilinks:

[[note title]]
[[note title|display text]]
[[subfolder/note title]]

The indexer resolves these into links and backlinks arrays on each note. In the UI, inline wikilinks are clickable and a Links / Backlinks section appears at the bottom of each note. Matching is case-insensitive and handles smart quotes.

File Structure

vault-search/
├── build-index.js       # Indexer — parses notes into search-index.json
├── watch.js             # File watcher for auto-reindexing
├── index.html           # Search UI
├── styles/
│   ├── themes.css       # CSS variable definitions for all themes
│   └── app.css          # Structural styles
├── search-index.json    # Generated index (gitignored)
├── .env.example         # Configuration template
├── package.json
└── README.md

Contributing

Contributions welcome! Some good starting points:

Adding a new theme is the easiest contribution — open styles/themes.css, copy the [data-theme="catppuccin"] block, give it a new name, and adjust the variables. Then add a swatch button in index.html and a HLJS_THEMES entry in the theme picker JS.

Some themes that would be great to see:

• Solarized (light + dark)
• Gruvbox
• Nord
• Rosé Pine
• Tokyo Night

Other ideas:

• Persist sidebar width (draggable resizer)
• Export / copy note as markdown
• Mobile layout improvements