browse.nvim

Seamless browsing experience in Neovim with customizable search providers

Table of Contents

1. Features
2. Requirements
3. Installation
4. Setup
5. Usage
   • Bookmarks
   • Search
   • DevDocs
   • MDN
6. Customizations
7. Command Usage
8. Acknowledgements and Credits

---

Features

• 🖥️ Cross-platform: Works on Linux, macOS, Windows, and WSL.
• ⌨️ Efficient Searching: Reduces search keystrokes for queries on StackOverflow, DevDocs, and MDN.
• 🔍 Customizable Providers: Define your own search providers or use pre-built ones.
• 🔖 Bookmarks: Easily open and search your saved bookmarks.

Requirements

• Neovim (0.7.0+)
• Telescope.nvim for interactive picking.
• Command for opening URLs:
  • xdg-open (Linux)
  • wslview (WSL)
  • open (macOS)
  • start (Windows)
• dressing.nvim (optional) for better input and selection UIs.

Installation

• lazy.nvim

  {
      "neovim-plugin/browse.nvim",
      dependencies = { "nvim-telescope/telescope.nvim" },
  }

• packer.nvim

  use({
      "neovim-plugin/browse.nvim",
      requires = { "nvim-telescope/telescope.nvim" },
  })

• vim-plug

  Plug 'nvim-telescope/telescope.nvim'
  Plug 'neovim-plugin/browse.nvim'

Setup

-- default values for the setup
require('browse').setup({
  bookmarks = {},
  icons = {
    bookmark_alias = "->",
    bookmark_prompt = "",
    grouped_bookmarks = "->",
  },
  persist_grouped_bookmarks_query = false,
  debug = false,
  use_icon = true,
  init = function()
    require("browse.providers.input")
    require("browse.providers.bookmarks")
    require("browse.providers.devdocs")
    require("browse.providers.mdn")
    require("browse.providers.devdocs_file")
  end,
})

Usage

Bookmarks

You can declare bookmarks in various formats. Below are some examples:

1. Grouped URLs with a name key (recommended):

   local bookmarks = {
     ["github"] = {
         ["name"] = "search github from neovim",
         ["code_search"] = "https://github.com/search?q=%s&type=code",
         ["repo_search"] = "https://github.com/search?q=%s&type=repositories",
         ["issues_search"] = "https://github.com/search?q=%s&type=issues",
         ["pulls_search"] = "https://github.com/search?q=%s&type=pullrequests",
     },
   }

2. URLs with aliases:

   local bookmarks = {
     ["github_code_search"] = "https://github.com/search?q=%s&type=code",
     ["github_repo_search"] = "https://github.com/search?q=%s&type=repositories",
   }

3. URLs with a query parameter:

   local bookmarks = {
     "https://github.com/search?q=%s&type=code",
     "https://github.com/search?q=%s&type=repositories",
   }

4. Simple and direct URLs:

   local bookmarks = {
        "https://github.com/hoob3rt/lualine.nvim",
        "https://github.com/neovim/neovim",
        "https://neovim.discourse.group/",
        "https://github.com/nvim-telescope/telescope.nvim",
        "https://github.com/rockerBOO/awesome-neovim",
    }

5. Combine all of the above in a single table if desired.

To use bookmarks:

vim.keymap.set("n", "<leader>b", function()
  require("browse").run_action({ bookmarks = bookmarks })
end)

IF the bookmarks table is empty or not passed, selection "Bookmarks" in Telescope will show an empty result.

Search

• Prompt a search:

require('browse').run_action('input')

• Search with bookmarks:

require("browse").run_action('bookmarks', { bookmarks = bookmarks })

• Open telescope.nvim dropdown to select a method:

require("browse").run_action({ bookmarks = bookmarks })

DevDocs

• Search DevDocs:

require('browse').run_action("devdocs")

• Search DevDocs based on the current filetype:

require('browse').run_action("devdocs_file")

MDN

• Search on MDN

require('browse').run_action("mdn")

Customizations

You can register your own provider with:

require('browse').register(provider)

Command Usage

You can invoke the Browse command in Neovim using:

:Browse [subcommand]

• Subcommand: The subcommand corresponds to a specific provider (e.g., input, mdn, devdocs, bookmarks). If you provide a subcommand, browse.nvim will use that provider to execute the corresponding action.

• Empty Subcommand: If no subcommand is provided, the command will fallback to Browse.run_action(), which will prompt you to select a provider or perform a default action.

Acknowledgements and Credits

• telescope.nvim
• open-browser.nvim
• original browse.nvim