A powerful Neovim plugin that enhances the built-in Netrw file explorer with live preview functionality and improved keybindings.

The main motivation to write this plugin was to add a live preview to Netrw similar to oil.nvim or mini.files.

I find Netrw quite powerful with many useful features. Although I have used other alternatives over the years (e.g., Nvimtree, Neo-tree, Oil.nvim, Mini.files), I wanted to get comfortable using netrw since it is the built-in file manager in Neovim. However, despite its built-in preview functionality, it opens files you're previewing as actual buffers. This leaves numerous unwanted buffers open at the end of your session, which I find undesirable.

Along the way, I decided to also include other enhancements to improve my own workflow in Netrw, similar in some ways to vim-vinegar and dirvish.vim.

• Live Preview: Real-time preview of files and directories as you navigate
• Flexible Preview Layout: Choose vertical or horizontal splits with configurable positioning and sizing
• Smart File Detection: Automatically detects and handles non-text files with file size information
• Smart Enter Navigation: Intelligent file/directory opening with proper alternate buffer handling
• History Tracking: Go back and forward in navigation history
• Flexible Directory Shortcuts: Create custom keybindings for frequently accessed directories
• Dynamic Path Support: Use functions for context-aware directory navigation
• Multiple Key Support: Assign multiple keys to the same action for maximum flexibility
• Enhanced Navigation: Improved keybindings for better netrw workflow
• File Operations: Quick path copying, insertion, and navigation utilities, ala vim-vinager
• Reveal Functionality: Jump to current file in netrw from any buffer
• Command-Based Interface: Use commands for flexible external mapping
• Highly Configurable: Customize preview window size and layout, keybindings, and behavior

{
  "idr4n/netrw-preview.nvim",
  ft = "netrw",
  keys = {
    { ",,", "<cmd>NetrwRevealToggle<cr>", desc = "Toggle Netrw - Reveal" },
    { ",l", "<cmd>NetrwRevealLexToggle<cr>", desc = "Toggle Netrw (Lex) - Reveal" },
    { "ga", "<cmd>NetrwLastBuffer<cr>", desc = "Go to alternate buffer (with netrw reveal)" },
  },
  opts = {}
}

use {
  "idr4n/netrw-preview.nvim",
  config = function()
    require("netrw-preview").setup()
  end
}

Plug 'idr4n/netrw-preview.nvim'

Then add to your init.lua:

require("netrw-preview").setup()

require("netrw-preview").setup({
  -- Preview window width as percentage of total width (for vertical splits)
  preview_width = 60,

  -- Preview window height as percentage of total height (for horizontal splits)
  preview_height = 60,

  -- Preview window layout orientation
  preview_layout = "vertical", -- "vertical" or "horizontal"

  -- Side to open preview window
  preview_side = "right", -- "left" or "right" for vertical, "above" or "below" for horizontal

  -- Enable preview by default when entering netrw
  preview_enabled = false,

  -- Key mappings
  mappings = {
    -- Enable/disable all mappings
    enabled = true,

    -- Toggle preview window
    toggle_preview = "p",

    -- Keys to close netrw (multiple options)
    close_netrw = { "q", "gq", "<c-q>" },

    -- Navigate to parent directory
    parent_dir = { "h", "-" },

    -- Enter directory/open file (smart enter)
    enter_dir = { "l", "<cr>" },

    -- Go back in history
    go_back = "<s-h>",

    -- Go forward in history
    go_forward = "<s-l>",

    -- Go to the first entry in history
    go_first = "<",

    -- Go to the last entry in history
    go_last = ">",

    -- Insert relative path in command line
    insert_path = ".",

    -- Yank absolute path to clipboard
    yank_path = "Y",

    -- Mark files in visual mode
    mark_files_visual = "m",

    -- Unmark files in visual mode
    unmark_files_visual = "u",

    -- Custom directory shortcuts
    directory_mappings = {
      { key = "~", path = "~", desc = "Home directory" },
    },
  }
})

All mappings support both single keys and multiple keys for the same action:

require("netrw-preview").setup({
  mappings = {
    -- Single key
    toggle_preview = "p",

    -- Multiple keys for same action
    close_netrw = { "q", "gq", "<c-q>", "<esc>" },
    parent_dir = { "h", "<BS" },
    enter_dir = { "l", "<CR>" },

    -- Disable with {}, empty string or false
    yank_path = {},         -- Disabled
    insert_path = "",       -- Also disabled
  }
})

require("netrw-preview").setup({
  preview_width = 70,           -- Wider preview window (vertical splits)
  preview_height = 30,          -- Preview height (horizontal splits)
  preview_layout = "horizontal",-- Use horizontal split
  preview_side = "below",       -- Preview below netrw
  preview_enabled = true,       -- Auto-enable preview
  mappings = {
    toggle_preview = "<space>",
    close_netrw = { "q", "<Esc>" },
    yank_path = "yy",
    last_buffer = "",           -- diabled mapping, also false or {}
    directory_mappings = {
      { key = "~", path = "~", desc = "Home directory" },
      { key = "gd", path = "~/Downloads", desc = "Downloads directory" },
      -- relative path
      { key = "gs", path = "../../src", desc = "Source directory" },
      -- dynamic path
      { key = "gw", path = function() return vim.fn.getcwd() end, desc = "Current working directory" },
    },
  }
})

The l key (or your configured enter_dir mapping) provides intelligent behavior:

• On directories: Normal navigation (same as <CR>)
• On files: Opens file AND preserves proper alternate buffer context
  • If opening the same file you came from → alternate = previous alternate buffer
  • If opening a different file → alternate = file you came from

This creates intuitive buffer navigation when jumping between files via netrw.

• File Preview: Shows file contents with syntax highlighting
• Directory Preview: Shows directory contents with folders listed first
• Binary Files: Displays file information for binary files
• Large Files: Automatically truncates large files (>500 lines) for performance
• Layout Options: Choose between vertical (left/right) or horizontal (above/below) preview splits
• Customizable Sizing: Configure preview window width for vertical splits or height for horizontal splits

NetrwReveal, NetrwRevealLex (and their toggle counterparts), and NetrwLastBuffer can be mapped globally as:

vim.keymap.set("n", ",,", "<cmd>NetrwReveal<cr>", { desc = "Open Netrw - Reveal current file" })
vim.keymap.set("n", "ga", "<cmd>NetrwLastBuffer<cr>", { desc = "Go to alternate buffer (with netrw reveal)" })

NetrwRevealFile Examples:

• Reveal current file (if no argument provided)

  :NetrwRevealFile

• Reveal specific file

  :NetrwRevealFile /path/to/file.txt

• Open directory in netrw

  :NetrwRevealFile /path/to/directory

  :NetrwRevealFile ~/projects

• Works with relative paths

  :NetrwRevealFile ./lua/config/init.lua

  :NetrwRevealFile ../docs

NetrwLastBuffer Logic:

• From regular file to file: uses vim.cmd('edit #') to ensure the alternate buffer appears in the buffer list if closed
• From netrw: uses vim.cmd('buffer #') to just switch to alternate buffer (usually a regular file)
• From regular file to netrw: uses vim.cmd('edit #') plus file reveal logic (as long as the file is in the same netrw directory)

The other commands (NetrwPreviewToggle, NetrwPreviewEnable, NetrwPreviewDisable) are designed to be used from within netrw buffers.

local netrw_preview = require("netrw-preview")

-- Preview controls
netrw_preview.enable_preview()
netrw_preview.disable_preview({ delete_buffer = true })
netrw_preview.toggle_preview()

-- File/directory revelation
netrw_preview.reveal()                             -- Reveal current file
netrw_preview.reveal_lex()                         -- Reveal current file (Lexplore)
netrw_preview.reveal_file("/path/to/file.txt")     -- Reveal specific file
netrw_preview.reveal_file_lex("/path/to/file.txt") -- Reveal specific file (Lexplore)
netrw_preview.reveal_file("/path/to/directory")    -- Open specific directory
netrw_preview.reveal_file("~/projects")            -- Works with tilde expansion
netrw_preview.reveal_file("./src")                 -- Works with relative paths

require("netrw-preview").setup({
  preview_enabled = true,
  preview_width = 50,
})

-- Create an autocmd to open netrw when launching nvim without arguments
vim.api.nvim_create_autocmd("VimEnter", {
  callback = function()
    if vim.fn.argc() == 0 then
      require("netrw-preview").reveal()
    end
  end,
})

-- Create autocmd to open netrw when launching nvim with a directory as argument
vim.api.nvim_create_autocmd("VimEnter", {
  callback = function()
    if vim.fn.argc() == 1 then
      local stat = vim.loop.fs_stat(vim.fn.argv(0))
      if stat and stat.type == "directory" then
        require("netrw-preview").reveal()
      end
    end
  end,
})

• Text files: Full syntax highlighting
• Code files: Language-specific highlighting
• Directories: Sorted file listings (directories first)
• Other files: Non-text file size and type information
• Large file handling: Auto-truncation of files >500 lines for better performance

Contributions are welcome! Please feel free to submit a pull request. For major changes or additional features, it is recommended to open a new discussion first before embarking in writing a full PR.

Here's how you can contribute:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request
6. Please make sure to follow the existing code style.

MIT License - see the LICENSE file for details.

• Built for Neovim's built-in netrw file explorer
• Inspired by various file manager related plugins in the Neovim ecosystem, such as oil.nvim and vim-vinegar
• Thanks to all contributors and users providing feedback

Note: This plugin enhances netrw without replacing it, maintaining compatibility with existing netrw workflows while adding powerful preview capabilities.