telescope-pdfgrep.nvim

A Neovim telescope extension for searching text within PDF files using pdfgrep.

Features

• 🔍 Search text in PDF files with telescope interface
• 📖 Live search as you type
• 👁️ Preview search results with context
• 🚀 Open PDFs with your preferred reader (okular, evince, zathura, etc.)
• ⚡ Fast searching using pdfgrep
• 📋 Copy file paths to clipboard

Requirements

• Neovim >= 0.7.0
• telescope.nvim
• pdfgrep installed on your system
• pdftotext for previews (usually comes with poppler-utils)

Installing pdfgrep

# Ubuntu/Debian
sudo apt install pdfgrep poppler-utils

# macOS
brew install pdfgrep poppler

# Arch Linux
sudo pacman -S pdfgrep poppler

# Fedora
sudo dnf install pdfgrep poppler-utils

Installation

Using lazy.nvim

{
  "GuanshiyinPusa/telescope-pdfgrep.nvim",
  dependencies = {
    "nvim-telescope/telescope.nvim",
  },
  config = function()
    require("telescope").load_extension("pdfgrep")
  end,
}

Using packer.nvim

use {
  "GuanshiyinPusa/telescope-pdfgrep.nvim",
  requires = { "nvim-telescope/telescope.nvim" },
  config = function()
    require("telescope").load_extension("pdfgrep")
  end,
}

Usage

Commands

• :TelescopePdfGrep [search_term] - Search for text in PDFs (prompts if no term provided)
• :TelescopeLivePdfGrep - Live search as you type

Telescope commands

:Telescope pdfgrep
:Telescope live_pdfgrep

Lua API

-- Basic search
require("telescope").extensions.pdfgrep.pdfgrep()

-- Search with specific query
require("telescope").extensions.pdfgrep.pdfgrep({ query = "search term" })

-- Live search
require("telescope").extensions.pdfgrep.live_pdfgrep()

Configuration

Setup the extension with custom options:

-- Default settings - customize as needed
require("telescope").setup({
  extensions = {
    pdfgrep = {
      -- PDF readers in order of preference
      -- Plugin tries each reader in order until it finds one that's installed
      -- If all fail, falls back to xdg-open (system default)
      pdf_readers = { "okular", "zathura", "evince", "mupdf", "xdg-open" },
      
      -- Search behavior
      search_subdirs = true,        -- true: search recursively in subdirectories
                                   -- false: only search current directory
      max_depth = 3,               -- When search_subdirs=true, limit recursion depth
                                   -- 1 = current dir only, 2 = one level down, etc.
      case_sensitive = false,      -- false: ignore case (finds "PDF" and "pdf")
                                   -- true: exact case matching only
      search_timeout = 10,         -- Kill search after N seconds to prevent hanging
                                   -- 0 = no timeout (may hang on large directories)
      max_results = 500,           -- Limit displayed results to prevent overwhelming UI
                                   -- Higher = more complete but slower display
      show_line_numbers = true,    -- true: show "file.pdf:42: content"
                                   -- false: show "file.pdf: content"
      
      -- File filtering
      ignore_patterns = { "*.tmp.pdf", "*cache*" }, -- Skip files matching these patterns
                                                    -- Useful for temp files, backups, etc.
      min_file_size = "1KB",       -- Skip tiny files (likely corrupted/empty)
      max_file_size = "50MB",      -- Skip huge files (slow to search, likely not documents)
      
      -- Performance (experimental)
      cache_results = true,        -- true: remember recent searches for faster repeat queries
                                   -- false: always search from scratch
      parallel_search = true,      -- true: search multiple files simultaneously
                                   -- false: search files one by one (slower but less CPU)
    },
  },
})

require("telescope").load_extension("pdfgrep")

Keymaps

Add these to your Neovim config:

-- Basic keymaps
vim.keymap.set('n', '<leader>fp', function()
  require("telescope").extensions.pdfgrep.pdfgrep()
end, { desc = "Search PDFs" })

vim.keymap.set('n', '<leader>fP', function()
  require("telescope").extensions.pdfgrep.live_pdfgrep()
end, { desc = "Live search PDFs" })

Telescope Mappings

When in the telescope picker:

• <Enter> - Open PDF with configured reader
• <C-o> - Open PDF with configured reader (alternative)
• <C-y> - Copy PDF file path to clipboard
• <C-c> or <Esc> - Close telescope

Examples

Search for a specific term

:TelescopePdfGrep machine learning

Search in a specific directory

require("telescope").extensions.pdfgrep.pdfgrep({
  query = "neural network",
  search_dir = "~/Documents/papers"
})

Troubleshooting

"pdfgrep not found" error

Make sure pdfgrep is installed and in your PATH:

which pdfgrep
pdfgrep --version

Preview not working

Install pdftotext (part of poppler-utils):

which pdftotext
pdftotext -v

PDFs not opening

The plugin tries multiple PDF readers in order. You can customize the list in configuration or install one of the supported readers.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License