User Guide¶
Main Topics¶
Adding Sources - Configure directories to index and search.
Searching - Learn search syntax, filters, and tips for finding what you need.
Web Interface - Navigate the web UI and use all its features.
Document Preview - View full document content with syntax highlighting.
Scheduling - Set up automatic scan schedules for your sources.
Understanding Indexing - How indexing works and how to optimize it.
Common Workflows¶
Daily Use¶
Search your documents, use filters to narrow results, and click results to preview content. The status page shows indexing progress and any errors.
Adding New Content¶
After adding files to your source directories, trigger a reindex from Admin → Sources. Use incremental reindex (the default) for speed - OneSearch only processes changed files.
Maintaining Your Index¶
Reindex sources when content changes. Check the status page for failed files and fix any issues (permissions, corrupt files, etc.). Adjust include/exclude patterns to skip irrelevant content.
Supported File Types¶
OneSearch currently supports:
| Type | Extensions | Features |
|---|---|---|
| Text, code, config | .txt, .log, .py, .js, .yaml, .json, and more | Full-text search, encoding detection |
| Markdown | .md, .markdown | Full-text search, YAML front-matter parsing, rendered preview |
| Text extraction, metadata | ||
| Office | .docx, .xlsx, .pptx | Document, spreadsheet, slide, and notes extraction |
| RTF, EPUB, subtitles | .rtf, .epub, .srt, .vtt, .ass | Readable text and format metadata |
| Comics | .cbz | Page listing and ComicInfo metadata |
| Images and RAW photos | .jpg, .png, .webp, .tiff, .cr2, .cr3, .nef, .dng, and more | Image/EXIF metadata and authenticated previews |
| Audio/video media | .mp4, .mkv, .mov, .mp3, .flac, .wav, and more | Optional ffprobe metadata |
| Unsupported files | any other extension | Optional filename/path metadata-only indexing |
See Supported Formats for details.
Tips & Best Practices¶
Organizing Sources¶
Create separate sources for different content types (Documents, Code, Notes, etc.). Use meaningful names - they appear in search filters. Mount directories read-only (:ro in Docker) for safety.
Include/Exclude Patterns¶
Be specific about what to include. Exclude build artifacts, dependencies, and hidden files to reduce noise. Test your patterns by adding a source and checking what gets indexed.
Searching Effectively¶
Use filters to narrow by source or file type. Meilisearch is typo-tolerant, so don't worry about exact spelling. Check highlighted snippets for context. Click results to see the full document.
Performance¶
Incremental reindex is fast for regular updates. Full reindex rebuilds everything - use it sparingly. Exclude large files you don't need. SSD storage improves indexing and search speed.
Interface Overview¶
Search Page¶
The main page has a search box (press Ctrl+K or Cmd+K to focus it), filters for source and file type, and clickable result cards with highlighted snippets. Pagination lets you browse through results.
Admin Section¶
Sources: Manage sources - test root paths, add, edit, delete, trigger incremental reindexing, or run a full reindex when rebuilding the search index.
Status: Monitor indexing progress, view per-source statistics, and check failed files.
Settings: Choose Light, Dark, or System mode, adjust accent colors, configure previews/indexing behavior, and tune search display preferences.
See the Web Interface Guide for details.
Getting Help¶
Check the Troubleshooting Guide for common issues.
For bugs or feature requests, open a GitHub Issue.
For questions or discussions, use GitHub Discussions.