README file from
GithubRGA Search
Full-text search inside the PDFs, EPUBs and other documents in your Obsidian vault, powered by ripgrep-all (rga).
Type a phrase, see the matching lines with the page they're on, and press Enter to open the PDF at that page. If a note in your vault links to the PDF (for example a reference note made by Stacks), the result shows that note's title and citekey, and Shift+Enter opens the note instead.
RGA Search is desktop only. It runs rga, a separate program you install yourself.
How it works
- Search runs
rga --jsonover the folders you choose.rgaextracts the text of each document (withpdftotextfor PDFs,pandocfor EPUB and Office files), then ripgrep searches it. Each keystroke cancels the previous search. - Results show pages.
rgalabels each line of a PDF with its page number, so a result opensfile.pdf#page=Nin Obsidian's PDF viewer. - The cache lives outside your vault.
rgakeeps extracted text in its own cache folder (~/Library/Caches/ripgrep-allon macOS,~/.cache/ripgrep-allon Linux,%LOCALAPPDATA%\ripgrep-allon Windows). Nothing is added to your vault and nothing syncs. The first search over a large library extracts every document and can take a while (over an hour for about 950 PDFs on a recent Mac); later searches read the cache. Run Warm the cache to do that first pass ahead of time, or turn on Warm the cache at startup. RGA Search raisesrga's cache size limit so very large books are cached too; by defaultrgare-extracts any document whose text compresses to more than 2 MB on every search. - Damaged files don't stop a search. A file
rgacan't read (a damaged PDF, an EPUB pandoc rejects) is skipped, and the search box names it. - Notes are left to Obsidian. By default only
*.pdfand*.epubfiles are searched, because Obsidian's own search already covers Markdown.
Install
- Install ripgrep-all and the PDF text extractor:
- macOS:
brew install ripgrep-all poppler(addpandocfor EPUB and Office files) - Linux:
rgafrom its releases or your package manager, plusripgrepandpoppler-utils - Windows:
scoop install rgaor a release from GitHub, plus poppler
- macOS:
- Install RGA Search (from Community plugins once it's listed; until then, see Building).
- Open Settings → RGA Search. The status line should show the
rgaversion. Ifrgaisn't found, enter its full path (for example/opt/homebrew/bin/rga).
Obsidian started from the Dock or Finder doesn't see your shell's PATH. RGA Search adds the usual Homebrew, Cargo and Scoop folders itself, so this normally just works.
Use
| Command | What it does |
|---|---|
| Search inside documents | Opens the search box (also on the ribbon). Starts with the selected text, if any. |
| Search inside documents for the selection | Same, from the editor. |
| Warm the cache | Extracts any new documents now, so later searches are fast. |
In the search box: Enter opens the document at the matching page, Cmd/Ctrl+Enter opens it in a new tab, and Shift+Enter opens the note that links to it.
Lowercase queries ignore case; a query with a capital letter matches case exactly (ripgrep's "smart case"). Turn on Regular expressions in settings to use ripgrep's regex syntax.
Settings
- Folders: where to search, for example
archive/zotero. Empty searches the whole vault. - File types: glob patterns, matched ignoring case (
*.pdfalso findsScan.PDF). Add*.docx,*.odtor*.zipto search those too. - Maximum results and Matches per file: keep the list short on common words.
- Reference notes: the properties that link a note to its document (
pdfandattachmentsby default), and the title and citekey properties to show. With Use Stacks' properties on, RGA Search reads Stacks' own field mapping first, so renamed properties still work, and falls back to these names for notes written before a rename. Links can be wikilinks or Markdown links ([Smith](Smith%20(2020).pdf "Title")).
Working with Stacks
Stacks files each PDF in your vault and links it from its reference note's pdf property. RGA Search uses that link to show the reference's title and citekey on each result, and Shift+Enter jumps from a hit on page 47 straight to the reference note. RGA Search doesn't need Stacks; any note that links to a document through a property works the same way.
Compared with Omnisearch
Omnisearch is a search engine for your notes, and it can include PDFs through a text-extraction plugin. RGA Search does one narrower job: exact phrase and regex search inside documents, with page numbers, using a command-line tool you already trust. The two can be used side by side, Omnisearch for notes and RGA Search for the library.
Limits
- Scanned PDFs with no text layer have nothing to search. Add a text layer first, for example with OCRmyPDF.
- Pages are known for PDFs only. EPUB and Office results open the file.
- Desktop only: mobile apps can't run other programs.
Building
npm install
npm run build # main.js
npm run deploy -- "/path/to/vault" # copy main.js, manifest.json and styles.css into the vault's plugin folder
Development
| Command | What it runs |
|---|---|
npm test |
Unit tests (node:test). The runner tests also use the real rga on a fixture PDF when it's installed. |
npm run lint |
ESLint with the Obsidian community rules |
npm run lint:scanner |
ESLint the way the community directory scans a release |
npm run test:e2e |
End-to-end tests in real Obsidian; see test/e2e/README.md |
CI runs lint, unit tests, build and the scanner lint on every push and pull request, and the e2e suite in real Obsidian (minAppVersion and latest). Merging a version bump to main (manifest.json, package.json and versions.json) publishes a GitHub release with main.js, manifest.json and styles.css, with build provenance attested.
License
MIT. ripgrep-all, ripgrep, poppler and pandoc are separate programs under their own licences; RGA Search runs them but doesn't include them.