Search and Navigation in Vaultex

One of Vaultex’s most useful features is its full-text search — no external service, no API key, just a local search.xml generated at build time. This post walks through how the search works, how navigation is structured, and the keyboard shortcuts worth memorizing.

Full-Text Search

How It Works

At build time, hexo-generator-search creates a search.xml file that indexes every post’s title, content, and tags. The Vaultex search module fetches this file once on first search, parses it client-side, and scores results against the query.

The search is:

Offline — works with no network connection after the initial page load
Private — no keystrokes leave the browser
Fast — everything is in memory after the first fetch

Opening Search

1 2	`Ctrl+Shift+F (Windows / Linux) Cmd+Shift+F (macOS)`

Or click the search icon in the left sidebar. The search panel opens as an overlay with a text input focused automatically.

Search Behavior

Results appear as you type (debounced at ~150ms)
Matching terms are highlighted in results
Each result shows the post title, a content excerpt, and tags
Press ↑/↓ to navigate results, Enter to open the selected post
Press Esc to close without navigating

The left sidebar is the primary navigation surface. It contains:

Navigation section — links configured in themes/vaultex/_config.yml:

nav_items:
  - label: Home
    icon: home
    path: /
  - label: Archive
    icon: archive
    path: /archives/
  - label: Categories
    icon: folder
    path: /categories/
  - label: Tags
    icon: tags
    path: /tags/

Categories tree — auto-generated from post categories. Folders represent parent categories, files represent individual posts. The tree is collapsed by default; clicking a folder expands it.

Recent Notes — the last 10 posts, always visible for quick access.

Links — custom external links, configurable in the theme config.

Click the panel toggle icon in the tab bar (or use the activity bar button) to collapse the left sidebar. The state persists across page navigations via sessionStorage.

On screens narrower than 768px, both sidebars are hidden by default and open as drawers on demand.

The Tab Bar

The tab bar runs across the top of the content area. It contains:

Breadcrumb — Vault → Category → Post Title
Left sidebar toggle — panel-left icon
Right sidebar toggle — panel-right icon

The breadcrumb updates as you navigate. On the homepage it shows the vault name and the homepage subtitle configured in _config.yml:

1	`homepage_subtitle: Recent Notes`

The Quick Switcher

Pressing Ctrl+O (Cmd+O on macOS) opens the quick switcher — a filtered list of all posts by title. Type to narrow the list, press Enter to navigate.

This mirrors the command palette UX pattern from VS Code and Obsidian — fast keyboard-driven navigation without reaching for the mouse.

Keyboard Reference

Shortcut	Action
`Ctrl+O` / `Cmd+O`	Open quick switcher
`↑` / `↓`	Navigate search results
`Enter`	Open selected result
`Esc`	Close any open overlay
`?`	Open help modal (keyboard shortcut reference)

The ? key opens a modal listing all keyboard shortcuts — useful for new users discovering the interface.

Activity Bar

The slim strip on the far left edge of the screen is the activity bar. It contains:

Social links — GitHub, LinkedIn, Twitter, or any links configured in social_links
Vault switcher — the vault name button at the bottom (position configurable)

Social link icons are SVGs sourced from themes/vaultex/source/icons/. To add a social link with a custom icon, drop an SVG into that directory and reference it by filename.

SEO and Discoverability

Beyond in-site navigation, Vaultex generates several files that help search engines and feed readers:

File	Purpose	Plugin
`atom.xml`	RSS feed for subscribers	`hexo-generator-feed`
`sitemap.xml`	Sitemap for search engines	`hexo-generator-sitemap`
`search.xml`	Full-text search index	`hexo-generator-search`

All three are generated automatically on hexo generate with no additional configuration beyond adding the plugins and their config blocks to _config.yml.