Telescope helpgrep

• Telescope helpgrep
  • Using help
  • Alternative
  • Usage
    • Default picker options
  • Setup
    • Defaults
    • Example
  • Extra

Telescope extension that uses Telescope builtins (live_grep or grep_string) to grep through help files

Sometimes help tags are not available for what you are looking for with Telescope help_tags or :help. Telescope helpgrep can be used to grep through help files using Telescope's builtins

Using help

Searching for help the help topic: vim.api.nvim_open_win using :help

Searching for help the help topic: vim.api.nvim_open_win using :Telescope help_tags

Grepping through help files for vim.api.nvim_open_win with :Telescope helpgrep

Alternative

Of course you can use the built in helpgrep, but I wanted something more "Telescopic" rather than having to filter through quickfix.

Usage

Defaults to live_grep picker:

:Telescope helpgrep

Uses Telescope live_grep builtin:

:Telescope helpgrep live_grep

Uses Telescope grep_string builtin:

:Telescope helpgrep grep_string

Default picker options

These are the default options passed into the Telescope picker

{
  prompt_title = "Help Grep",
  glob_pattern = "*.txt",
  disable_coordinates = true,
  path_display = { "tail" },
}

These options can be overridden by passing opts table into live_grep or grep_string :help telescope.builtin.live_grep and :help telescope.builtin.grep_string

require("telescope-helpgrep").live_grep({
  prompt_title = "Helpy McGrepperson",
  ...,
})

require("telescope-helpgrep").grep_string({
  prompt_title = "grep_string",
  ...,
})

Setup

ignore_paths defines which paths will be ignored by helpgrep mappings defines mappings overrides default_grep specifies which telescope built-in to use

Defaults

local builtin = require("telescope.builtin")({
  ignore_paths = {},
  mappings = {},
  default_grep = builtin.live_grep,
})

Example

In Telescope setup:

local actions = require("telescope.actions")
local builtin = require("telescope.builtin")

telescope.setup({
  ...
  extensions = {
    helpgrep = {
      ignore_paths = {
        vim.fn.stdpath("state") .. "/lazy/readme",
      },
      mappings = {
        i = {
          ["<CR>"] = actions.select_default,
          ["<C-v>"] = actions.select_vertical,
        },
        n = {
          ["<CR>"] = actions.select_default,
          ["<C-s>"] = actions.select_horizontal,
        }
      },
      default_grep = builtin.live_grep,
    }
  }
})

require("telescope").load_extension("helpgrep")

No paths are ignored by default, but if you use lazy.nvim it is recommended to add vim.fn.stdpath("state") .. "/lazy/readme" to the ignore_paths table.

Note that telescope-helpgrep.nvim will extend the select_* actions to use the native help, vert help and tab help commands.

TODO

• Set win/buffer optsions for help window, configurable by setup opts

Extra

My other neovim projects

• neovim config
• do-the-needful.nvim
• vue-goto-definition