browse.nvim

browse for anything using your choice of method

improved-navigation.mp4

browse.nvim is a plugin that provides a unified interface for browsing and searching web resources directly from within Neovim. It uses telescope.nvim to offer a powerful picker for accessing your bookmarks, searching with different providers (like Google, DuckDuckGo), and querying documentation sites like DevDocs and MDN.

Showcase

🎥 Click here to see features in action!

Unified Command System

commands.mp4

Unified Bookmark Search

bookmarks.mp4

Filetype Docs Search

devdocs-ft.mp4

Visual Mode Search

visual-mode-selection.mp4

Features

• Cross-platform support.
• Reduces keystrokes for search queries.
• DevDocs integration.
• MDN Web Docs integration.
• Powerful and flexible bookmarking system, with support for multiple files (JSON, YAML, TOML, TXT) and browser bookmark importing.

Requirements

• neovim (0.7.0+)
• telescope.nvim
• A command-line opener:
  • Linux: xdg-open
  • WSL: wsl-open
  • macOS: open
  • Windows: start
• dressing.nvim (optional, for a better UI).

Installation

• Using lazy.nvim

  {
      "lalitmee/browse.nvim",
      dependencies = { "nvim-telescope/telescope.nvim" },
      opts = {
          -- add your options here, or leave empty to use defaults
      },
  }

Configuration

Here is the default configuration:

require('browse').setup({
    -- The default search provider for `input_search()`.
    -- Values: "google", "duckduckgo", "bing", "brave".
    provider = "google",

    -- A Lua table containing your bookmarks.
    bookmarks = {},

    -- A list of absolute paths to external bookmark files.
    bookmark_files = {},

    -- Configuration for importing bookmarks from web browsers.
    browser_bookmarks = {
        enabled = false,
        browsers = {
            chrome = false,
            firefox = false,
            safari = false,
            edge = false,
        },
        group_by_folder = true,
        auto_detect = true,
    },

    -- If `true`, duplicate bookmark URLs from all sources will be removed.
    deduplicate_bookmarks = true,

    -- If `true`, bookmarks loaded from files and browsers will be cached to improve performance.
    cache_bookmarks = true,

    -- The duration in seconds for which the bookmark cache is valid.
    cache_duration = 60,

    -- If `true`, the plugin will create default user commands for you.
    create_commands = true,

    -- A table to configure the Telescope theme for each picker.
    themes = {
        browse = "dropdown",
        manual_bookmarks = "dropdown",
        browser_bookmarks = nil, -- nil uses the default Telescope theme
    },

    -- Configuration for parsing plain text (`.txt`) bookmark files.
    plain_text = {
        delimiters = { ":", "=" },
        comment_chars = { "#", ";" },
    },

    -- Customize the icons used in the Telescope pickers.
    icons = {
        bookmark_alias = "->",
        bookmarks_prompt = "",
        grouped_bookmarks = "->",
        file_bookmark = "📄",
        browser_bookmark = "🌐",
    },

    -- If `true`, the search query is preserved when you navigate into a nested bookmark group.
    persist_grouped_bookmarks_query = false,

    -- Configuration for the bookmark picker.
    bookmark_picker = {
        -- If `true`, nested bookmarks are displayed in a nested structure.
        -- If `false`, all bookmarks are shown in a flat list.
        show_nested = true,
    },

    -- The number of Telescope pickers to cache, enabling back-navigation.
    cache_pickers = 10,

    -- If `true`, bookmark results are sorted alphabetically.
    -- If `false`, they are displayed in the order they were defined.
    sort_results = true,
})

Usage

The main entry point is the require('browse').browse() Lua function. This opens a Telescope window with the following options:

• Manual Bookmarks: Search through your bookmarks from your config and files.
• Browser Bookmarks: Search through bookmarks imported from your web browsers.
• Devdocs Search: Search for queries on devdocs.io.
• Devdocs Search with filetype: Search DevDocs, automatically using the current buffer's filetype as a filter.
• Input Search: Enter a query to search with your default search provider.
• MDN Web Docs: Search for queries on the MDN Web Docs.

Text selected in visual mode will be used as the initial query for searches.

Commands

If create_commands = true (the default), the plugin will create the :Browse command.

:Browse <subcommand>

If no subcommand is provided, the main selection menu will open. All subcommands support visual mode selection to pre-fill the search query.

Subcommand	Action
input	Opens the input search to query with your default provider.
mdn	Searches the MDN Web Docs.
mdn_ft	Searches MDN, including the current buffer's filetype.
devdocs	Searches devdocs.io.
devdocs_ft	Searches DevDocs, including the current buffer's filetype.
bookmarks	Opens a picker to select a bookmark source.
bookmarks_manual	Opens your manual bookmarks directly.
bookmarks_browser	Opens your browser bookmarks directly.

API

All public functions are available under the require('browse') module.

• browse.setup({opts}): Configures the plugin. See Configuration.

• browse.browse({opts}): Opens the main Telescope picker to select a search type.

• browse.open_manual_bookmarks({opts}): Opens the Telescope picker directly to your manual bookmarks (from config and files).

• browse.open_browser_bookmarks({opts}): Opens the Telescope picker directly to your browser bookmarks.

• browse.input_search(): Prompts for input and searches using the configured provider.

• browse.devdocs.search(): Prompts for input and searches on devdocs.io.

• browse.devdocs.search_with_filetype(): Prompts for input and searches on devdocs.io, using the current buffer's filetype to narrow the search.

• browse.mdn.search(): Prompts for input and searches on MDN Web Docs.

Bookmarks

browse.nvim can aggregate bookmarks from three sources: a Lua table, external files, and your web browser's bookmarks.

Lua Table

You can define bookmarks directly in your setup() call or pass them to the browse() or open_bookmarks() functions. The table can have several formats:

1. Simple list of URLs:

   bookmarks = {
       "https://neovim.io",
       "https://github.com/nvim-telescope/telescope.nvim",
   }

2. Aliases for URLs (name = URL):

   bookmarks = {
       neovim = "https://neovim.io",
       telescope = "https://github.com/nvim-telescope/telescope.nvim",
   }

   If the URL contains %s, it will be treated as a search query, and you will be prompted for input.

   bookmarks = {
       gh_search = "https://github.com/search?q=%s",
   }

3. Grouped bookmarks: You can create nested tables to group related bookmarks.

   bookmarks = {
       neovim = {
           name = "Neovim Resources", -- Optional display name for the group
           website = "https://neovim.io",
           discourse = "https://neovim.discourse.group/",
       },
   }

External Files

Use the bookmark_files option to specify a list of files to load bookmarks from. The following formats are supported:

• json: Standard JSON format.
• yaml: YAML format.
• toml: TOML format.
• txt: A plain text file where each line is a bookmark. The format can be name: url or just url. Use the plain_text config table to customize delimiters and comments.

Browser Bookmarks

Set browser_bookmarks.enabled = true to import bookmarks from your installed web browsers.

• enabled (boolean): Master switch to enable/disable this feature.
• browsers (table): A table of booleans to control which browsers to import from (e.g., { chrome = true, firefox = false }).
• auto_detect (boolean): If true, the plugin will try to find installed browsers and enable them automatically if they are not explicitly set in the browsers table.
• group_by_folder (boolean): If true, bookmarks will be nested in the picker according to the folder structure in your browser.

Acknowledgements and Credits

• telescope.nvim
• open-browser.nvim

Support