How to Set Up Telescope for Advanced Search and Navigation in jdhao/nvim-config

You can set up Telescope for advanced search and navigation by creating a dedicated configuration file at lua/config/telescope.lua, updating the plugin specification in lua/plugin_specs.lua to require this module, and binding the built-in pickers to intuitive keymaps in lua/mappings.lua.

The jdhao/nvim-config repository provides a minimal, performance-oriented Neovim setup where Telescope is lazy-loaded to reduce startup time. Because the plugin is only loaded when you execute the :Telescope command, you must explicitly extend the default configuration to unlock advanced fuzzy-finding, file browsing, and symbol navigation capabilities.

Understanding the Default Telescope Configuration

In lua/plugin_specs.lua (lines 150–162), Telescope is declared with lazy-loading enabled via the cmd = "Telescope" trigger. This specification includes nvim-telescope/telescope-symbols.nvim as a dependency but does not include a config function, meaning the plugin runs with factory defaults until you override them.

{
  "nvim-telescope/telescope.nvim",
  cmd = "Telescope",
  dependencies = {
    "nvim-telescope/telescope-symbols.nvim",
  },
},

This setup defers loading until you invoke any Telescope command, keeping your Neovim startup fast while maintaining access to powerful fuzzy-finding tools.

Creating a Custom Telescope Configuration File

To override defaults and enable extensions, create lua/config/telescope.lua and invoke require('telescope').setup() with your preferences. This file customizes the UI, defines ignore patterns, and configures the mappings for insert mode navigation.

local status_ok, telescope = pcall(require, "telescope")
if not status_ok then return end

telescope.setup{
  defaults = {
    prompt_prefix = "🔍 ",
    selection_caret = "➜ ",
    path_display = { "smart" },
    file_ignore_patterns = { "node_modules", ".git/", "dist/" },
    layout_strategy = "horizontal",
    layout_config = {
      horizontal = { preview_width = 0.55 },
      vertical = { width = 0.9 },
    },
    mappings = {
      i = {
        ["<C-j>"] = require("telescope.actions").move_selection_next,
        ["<C-k>"] = require("telescope.actions").move_selection_previous,
        ["<Esc>"] = require("telescope.actions").close,
      },
    },
  },
  extensions = {
    ["ui-select"] = {
      require("telescope.themes").get_dropdown(),
    },
    symbols = {
      ignore_cases = true,
      symbols = {
        "emoji",
        "math",
        "git",
        "arrow",
        "currency",
        "latin",
        "greek",
        "geometric",
      },
    },
  },
}

-- Load extensions
telescope.load_extension('ui-select')
telescope.load_extension('symbols')

Key configuration highlights include:

• file_ignore_patterns: Excludes node_modules, .git/, and build directories from search results
• layout_strategy: Uses horizontal splits with a dedicated preview width of 55%
• mappings: Binds <C-j> and <C-k> to navigate results, and <Esc> to close the picker in insert mode

Integrating Your Configuration with lazy.nvim

After creating the configuration file, modify the Telescope entry in lua/plugin_specs.lua to load your custom setup. Add a config function that requires the new module, ensuring your settings apply when the plugin loads.

{
  "nvim-telescope/telescope.nvim",
  cmd = "Telescope",
  dependencies = {
    "nvim-telescope/telescope-symbols.nvim",
  },
  config = function()
    require("config.telescope")   -- Load custom setup
  end,
},

This wiring ensures that lua/config/telescope.lua executes immediately after Telescope loads, overriding the factory defaults with your advanced search configuration.

Binding Telescope Commands to Keys

While Telescope provides powerful pickers such as find_files, live_grep, and buffers, you must bind them to keys in lua/mappings.lua (around lines 70–80) for efficient navigation. Use vim.keymap.set to create normal-mode shortcuts that trigger specific pickers.

local keymap = vim.keymap

-- Telescope shortcuts
keymap.set('n', '<leader>ff', '<cmd>Telescope find_files<cr>',   { desc = 'Find file' })
keymap.set('n', '<leader>fg', '<cmd>Telescope live_grep<cr>',    { desc = 'Live grep' })
keymap.set('n', '<leader>fb', '<cmd>Telescope buffers<cr>',      { desc = 'Buffers' })
keymap.set('n', '<leader>fh', '<cmd>Telescope help_tags<cr>',    { desc = 'Help tags' })
keymap.set('n', '<leader>fs', '<cmd>Telescope symbols<cr>',      { desc = 'Symbols picker' })

These mappings provide instant access to:

• find_files: Fuzzy search for files in the current working directory
• live_grep: Real-time grep across project files using ripgrep
• buffers: Quickly switch between open buffers
• symbols: Insert emoji, math symbols, and special characters via the telescope-symbols.nvim extension

Summary

• Telescope in jdhao/nvim-config is lazy-loaded via cmd = "Telescope" in lua/plugin_specs.lua to minimize startup overhead.
• Create lua/config/telescope.lua to override defaults, set ignore patterns, and configure UI preferences using require('telescope').setup().
• Update the plugin specification to include a config function that requires your custom configuration file.
• Add keybindings in lua/mappings.lua to invoke find_files, live_grep, buffers, and the symbols extension with leader-key shortcuts.
• Load extensions explicitly with telescope.load_extension() to enable advanced pickers like symbols and ui-select.

Frequently Asked Questions

Where is Telescope defined in jdhao/nvim-config?

Telescope is declared in lua/plugin_specs.lua between lines 150 and 162. The specification uses the cmd key to lazy-load the plugin only when you execute a :Telescope command, and it lists telescope-symbols.nvim as a dependency for enhanced symbol picking.

How do I enable the symbols picker in Telescope?

First, ensure telescope-symbols.nvim is listed in the dependencies array of your Telescope plugin spec (which it is by default in this repository). Then, add the symbols configuration table inside the extensions section of your setup() call, specifying which symbol categories to include. Finally, run telescope.load_extension('symbols') to activate it.

Why does Telescope take time to open initially?

Because the jdhao/nvim-config repository configures Telescope with cmd = "Telescope", the plugin is not loaded during Neovim startup. The first time you invoke a Telescope command, the plugin manager must load the Lua modules and dependencies, causing a brief delay. Subsequent invocations during the same session will be instantaneous.

Can I use Telescope without modifying plugin_specs.lua?

You can use Telescope with its factory defaults immediately after installation because the plugin spec already declares it. However, to enable advanced search features, custom keymaps, or extensions like symbols, you must modify plugin_specs.lua to include a config function that loads your custom setup file, or place your configuration in a file that loads after the plugin manager initializes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}