detour.nvim

It's a dangerous business, Frodo, going out your door. You step onto the road, and if you don't keep your feet, there's no knowing where you might be swept off to.

J.R.R. Tolkien, The Lord of the Rings

Never lose your spot!📍🗺️

What does detour.nvim do?

Provides the :Detour command (and require('detour').Detour() in lua) that opens a popup window.

detour.nvim has two uses:

Use popup windows instead of split windows

👍 Popups preserve your position in the current file during detours into other files (just like splits)

👍 Popups can use the entire screen (unlike splits)
Provide a large popup windows for TUIs, scripts, and commands.
- This plugin can be considered a generalized version of toggleterm.nvim and lazygit.nvim.

Basic Usage
Open a popup -> Go to different file -> Create vertical split -> Close popup

Installation

Lazy.nvim

{ "carbon-steel/detour.nvim",
    config = function ()
       vim.keymap.set('n', '<c-w><enter>', ":Detour<cr>")
   end
},

Recipes

detour.nvim is capable of more than just displaying file buffers. It generalizes the floating window behavior of plugins such as toggleterm.nvim and lazygit.nvim. It is as flexible as (Neo)Vim's split window mechanism.

Here are some examples of what you can do...

Use with Telescope

-- A keymap for selecting a terminal buffer to open in a popup
vim.keymap.set('n', '<leader>t', function()
    require('detour').Detour()               -- Open a detour popup

    -- Switch to a blank buffer to prevent any accidental changes.
    vim.cmd.enew()
    vim.bo.bufhidden = 'delete'

    require('telescope.builtin').buffers({}) -- Open telescope prompt
    vim.api.nvim_feedkeys("term", "n", true) -- popuplate prompt with "term"
end)


Open two terminal buffers -> Use the keymap above -> Select desired terminal

Wrap a TUI: tig

-- A keymap for running tig in a popup
vim.keymap.set('n', '<leader>g', function()
    local current_path = vim.fn.expand("%:p:h")
    local command = "a".. -- go into terminal mode
                "cd ".. current_path .. "<CR>" ..
                "tig<CR>" -- run tig
    command = vim.api.nvim_replace_termcodes(command, true, false, true)

    require('detour').Detour()  -- open a detour popup
    vim.cmd.terminal()          -- open a terminal buffer
    vim.bo.bufhidden = 'delete' -- close the terminal when window closes
    vim.api.nvim_feedkeys(command, "n", false)
end)


Use keymap above -> Close window

Wrap a TUI: top

-- Wrap any TUI inside a popup
vim.keymap.set("n", '<leader>p', function ()
    require('detour').Detour()  -- open a detour popup
    vim.cmd.terminal()          -- open a terminal buffer
    vim.bo.bufhidden = 'delete' -- close the terminal when window closes
    -- Run the `top` command
    local text = vim.api.nvim_replace_termcodes("atop<CR>", true, false, true)
    vim.api.nvim_feedkeys(text, "n", false)
end)


Use keymap above -> Close window

FAQ

I want to convert popups to splits or tabs.

<C-w>s and <C-w>v can be used from within a popup to create splits. <C-w>T creates tabs.

My LSP keeps moving my cursor to other windows.

If your LSP movements (ex: go-to-definition) are opening locations in other windows, make sure that you're not calling these movements with the reuse_win set to true.

My popups don't look good.

Some colorschemes don't have visually clear floating window border colors. Consider customizing your colorscheme's FloatBorder to a color that makes your popups clearer.

SmithWebDev / detour.nvim