Core concepts
Vaults
A vault is a folder on disk containing your content. Haft supports Markdown (.md), HTML (.html), and media files. The folder structure becomes the navigation tree in the reader.
Your files are never modified. Haft maintains a separate SQLite catalog that indexes your content for fast lookup, search, and rendering.
Pages
Each file in your vault becomes a page in the reader. Pages have:
- A stable ID (used in URLs and API responses)
- A source path (the original file on disk)
- Rendered HTML (generated from the source)
- Metadata (title, position in the tree, timestamps)
The catalog
The catalog is a SQLite database stored in .haft/ at the vault root. It maps your file tree to page IDs, stores rendered HTML, and tracks import state. Deleting .haft/ and re-importing rebuilds everything from your source files.
The reader
The reader is a single-page application served by the Haft server. It provides:
- Tree navigation matching your folder structure
- Full-text and semantic search (when QMD is configured)
- Theme support (light, dark, and custom themes)
- Responsive layout for desktop and mobile
The server
haft serve starts a local HTTP server that:
- Serves the reader SPA
- Exposes a JSON API for pages, search, and vault metadata
- Watches the vault for file changes and re-imports incrementally
The server binds to localhost:9001 by default. For public access, put it behind a reverse proxy (see Self-hosting).