Offline semantic search engine for documentation. Vector embeddings are generated locally at build time using ONNX Runtime. The browser client performs keyword matching and integer vector cosine similarity - sending no data to cloud services and shipping no neural network weights to the user.
Run npx docmd-search ./docs in any directory. Works out of the box with no setup, API keys, or manual config files.
Ways to Use It
docmd-search works as a standalone command-line tool or as a plugin for docmd documentation sites.
Run docmd-search ./my-folder to index any directory and search directly from your terminal. Add --ui to open a local browser interface.
Add semantic: true to your docmd.config.js to build search indexes automatically when building your site.
Overview
Build time (Node.js) Search time (Browser, <3KB)
─────────────────── ──────────────────────────
Crawl markdown files Load manifest.json
→ Heading-aware chunking → Load batches/000.json (search immediately)
→ ONNX vector embedding → Load remaining batches in background
→ Float32 → Int8 quantisation → BM25 keyword + cosine scoring
→ Product / ternary compression → Display ranked search results
→ Save index files (_docmd-search/)
At build time, embeddings are calculated using ONNX Runtime on your computer. The browser client receives pre-computed integer vectors and calculates term matching and vector scores locally.
Key Features
All vector embeddings are generated on your machine using ONNX Runtime. No data leaves your computer and no cloud API keys are needed.
Search is ready as soon as the first batch loads. Incremental re-indexing checks modification times and only re-indexes changed files.
The browser runtime is under 3KB gzipped. It runs without neural network weights or heavy WASM modules.
If indexing is interrupted, it resumes from the last completed batch. Output index files stay usable even if partial.
Quick Start
# Install globally
npm install -g docmd-search
# Install embedding dependencies (one-time setup)
npm install -g @huggingface/transformers onnxruntime-node
# Index any folder
docmd-search ./my-folder
# Launch browser preview
docmd-search ./my-folder --ui
# In your docmd project repository
npm install docmd-search
Enable semantic search in your config file:
// docmd.config.js
export default {
plugins: {
search: {
semantic: true, // Activates the docmd-search indexer
}
}
};
On your first run, a interactive prompt helps you select an embedding model. Your documentation is crawled, split into sections by heading, embedded, and saved to _docmd-search/.
Documentation Pages
| Page | Description |
|---|---|
| Getting Started | Installation, first run, and model selection |
| Configuration | Global, project, and command-line configuration options |
| How It Works | Architecture, chunking, quantisation, and hybrid scoring |
| CLI Reference | Command-line options, flags, and exit codes |
| Programmatic API | Node.js API methods for custom build scripts |
| Browser Client | Browser client integration API and scoring logic |
Architecture
docmd-search and docmd are independent tools designed to work seamlessly together:
┌─────────────────────────────────────────────────────────────────────┐
│ docmd-search (standalone) │
│ │
│ CLI → Index directory → _docmd-search/ batches → Terminal search │
│ │ │
│ │ --ui flag │
│ ▼ │
│ Start docmd preview server │
│ (docmd serves the web UI) │
└─────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────┐
│ docmd (documentation engine) │
│ │
│ Config → Build site → plugin-search execution │
│ │ │
│ │ semantic: true │
│ ▼ │
│ Run docmd-search indexer │
│ (Generates _docmd-search/ asset bundle) │
└─────────────────────────────────────────────────────────────────────┘
When running standalone with the --ui flag:
docmd-searchbuilds the search index.- It generates a temporary
docmdconfig pointing to_docmd-search/. - It starts
docmdas a local preview server to display the search UI.
When used as a plugin (semantic: true):
docmdimportsdocmd-searchduring site builds.- The indexer writes multi-batch JSON files into
_docmd-search/in the output build directory. - The browser client searches these pre-built index files directly.
