User Guide

Everything you need to find documents quickly. Also see the full README on GitHub.

Search modes

Use the toggle at top right to pick Keyword, Semantic or Both (the default). Search runs when you press Enter; clearing the box shows all documents again.

• Keyword: literal text via SQLite FTS5. Each word is prefix-matched and the words are OR-ed, so budget report finds documents containing budget… or report…. Matches in the title and author outrank body and tags. Best when you know a word, name or code that is in the document.
• Semantic: meaning, via AI embeddings. Finds documents that are about your query even without your exact words. Best for "documents about X".
• Both: runs both and keeps the stronger score per document, with a small boost when both hit. A document needs a keyword hit or a meaningful semantic score to appear, so weak semantic noise does not bury solid keyword matches.

What different word pairings do

Quotes mean exact phrase

Wrap words in "..." to require that exact consecutive phrase, case-insensitive, in any mode. In Semantic and Both it acts as a presence filter first, then ranks the matches by meaning. You can mix forms: golang "import fmt" means the phrase import fmt OR the loose word golang. Only articles (a/an/the) and conjunctions are treated as filler in Semantic mode, so quote a phrase when the exact wording matters.

Deep Links

Semantic search finds which documents match. Deep Links finds where inside one. Click the button on any result to list matching passages, each labeled by page, line or section. Click one to open it with the matched text highlighted in yellow. It runs on demand with no reindex.

Mode follows your search: semantic finds passages by meaning, keyword or hybrid finds them by term. Works for PDF, TXT, HTML, Markdown, DOCX, RTF, ODT, e-books, DjVu, the XML family, LaTeX, email, source code and more. Spreadsheets and presentations fall back to opening in their own reader.

AI synopsis

Click any document title for a book-jacket summary generated locally by dolphin3:latest and cached after the first run. The first synopsis on CPU-only hardware can be slow; later requests are instant.

The interface

• Dark and light theme toggle
• Paginated results (50 per page) with Back and Next
• A–Z and 0–9 index bar for quick jumping; Home resets it
• Tag cloud for filtering by topic
• Relevance badges (0–100%) on every result
• Open launches the file in your default app; 📋 copies the path; 🗑 deletes the file from disk and index, with confirmation
• Clicking a document whose file is gone shows a dismissable modal and removes it from the index. If the drive is simply unmounted, you get a toast and no index change.

Indexing your documents

Run docubrowser rescan to scan, index and embed. Supported formats include:

• PDF, DOCX, PPTX, XLSX, RTF, CSV/TSV, email (.eml)
• OpenDocument (ODT, ODS, ODP and templates)
• EPUB, MOBI, AZW3, AZW, DjVu
• Visio (VSDX, legacy VSD), draw.io, PlantUML, Mermaid, SVG
• HTML, Markdown, XML/SGML, DocBook, RSS/Atom/OPML, reST, AsciiDoc, LaTeX, config and log files, source code

Titles, authors and subjects are read from document metadata, and tags are generated from directory structure and content. A post-ingest PII scanner removes and permanently blacklists documents that contain SSNs, credit cards, bank routing and account numbers, DOB, MRN, driver license or passport patterns, validated structurally to limit false positives. Dotfiles and hidden directories are skipped by design.

Find and clean up duplicates with docubrowser duplist and docubrowser dupclean.

Settings

Open the gear icon, or go to /settings. The General panel sets the document directory (with a live directory browser), any number of additional scan directories, the working directory, port and language. The Ignored Directories panel excludes folders from scanning, with confirmation before purging anything already indexed.

Languages

One install serves one language, and the interface, search tokenizer, embedding model and synopsis model all follow it. Currently supported: English (the default), Japanese, Korean, Simplified Chinese and Traditional Chinese. Mixed-language collections are not supported.

Choosing a language

• First start. DocuBrowse starts in English. The first time you run docubrowser start in a terminal, it asks which language you want and saves your answer. Just follow the prompt.
• Any time after. Open the Settings page (gear icon), and pick a language from the dropdown in the General panel.

Known limitations