DOCSEARCHbyAlgolia
Submit Docs

edgy.nvim

repository·main·Indexed 22 days ago

https://github.com/folke/edgy.nvim

A Neovim plugin for managing predefined window layouts by creating 'edgebars' (sidebars and panels). It automatically moves windows into specific positions (left, right, top, bottom) to keep main editor splits untouched. Features include configurable view options such as filetype filtering, pinning, collapsing, and custom sizing, as well as a programmatic API for layout management.

Tokens
2.4K
Snippets
6
Records
8
Agent score
28%

What's inside edgy.nvim

  1. Configure recommended Neovim options for edgy.nvim

    main

    To ensure optimal behavior, especially for window collapsing and preventing main splits from jumping when edgebars open, set the following Neovim options:

    • vim.opt.laststatus = 3: Required for fully collapsing views (works best with a global statusline).
    • vim.opt.splitkeep = "screen" or "topline": Prevents main editor splits from jumping when an edgebar is opened.
    -- views can only be fully collapsed with the global statusline
vim.opt.laststatus = 3
-- Default splitting will cause your main splits to jump when opening an edgebar.
-- To prevent this, set `splitkeep` to either `screen` or `topline`.
vim.opt.splitkeep = "screen"

  2. Install edgy.nvim

    main

    Install the plugin using your preferred package manager. If you are using lazy.nvim, use the configuration below. If you are using any other manager, ensure you call require("edgy").setup(opts?) manually.

    {
  "folke/edgy.nvim",
  event = "VeryLazy",
  opts = {}
}

  3. Disable edgy.nvim for specific windows or buffers

    main

    You can exclude a specific window or buffer from the edgy layout by setting the edgy_disable variable. This can be done for a buffer or a window:

    • vim.b[buf].edgy_disable = true (Buffer-local)
    • vim.w[win].edgy_disable = true (Window-local)

    Once set, edgy will remove the window from the managed layout.

  4. Configure edgy.nvim layout and options

    main

    The configuration object allows you to define window layouts for the left, right, top, and bottom positions. Each position accepts an array of Edgy.View.Opts or strings (representing filetypes).

    {
  left = {}, ---@type (Edgy.View.Opts|string)[]
  bottom = {}, ---@type (Edgy.View.Opts|string)[]
  right = {}, ---@type (Edgy.View.Opts|string)[]
  top = {}, ---@type (Edgy.View.Opts|string)[]

  options = {
    left = { size = 30 },
    bottom = { size = 10 },
    right = { size = 30 },
    top = { size = 10 },
  },
  -- ... other options
}

  5. Example: Complex layout setup

    main

    This example demonstrates how to configure edgy.nvim with multiple views in the bottom and left positions, including filtering for specific plugins like toggleterm, lazyterm, and neo-tree.

    {
  "folke/edgy.nvim",
  event = "VeryLazy",
  init = function()
    vim.opt.laststatus = 3
    vim.opt.splitkeep = "screen"
  end,
  opts = {
    bottom = {
      -- toggleterm / lazyterm at the bottom with a height of 40% of the screen
      {
        ft = "toggleterm",
        size = { height = 0.4 },
        -- exclude floating windows
        filter = function(buf, win)
          return vim.api.nvim_win_get_config(win).relative == ""
        end,
      },
      {
        ft = "lazyterm",
        title = "LazyTerm",
        size = { height = 0.4 },
        filter = function(buf)
          return not vim.b[buf].lazyterm_cmd
        end,
      },
      "Trouble",
      { ft = "qf", title = "QuickFix" },
      {
        ft = "help",
        size = { height = 20 },
        -- only show help buffers
        filter = function(buf)
          return vim.bo[buf].buftype == "help"
        end,
      },
      { ft = "spectre_panel", size = { height = 0.4 } },
    },
    left = {
      -- Neo-tree filesystem always takes half the screen height
      {
        title = "Neo-Tree",
        ft = "neo-tree",
        filter = function(buf)
          return vim.b[buf].neo_tree_source == "filesystem"
        end,
        size = { height = 0.5 },
      },
      {
        title = "Neo-Tree Git",
        ft = "neo-tree",
        filter = function(buf)
          return vim.b[buf].neo_tree_source == "git_status"
        end,
        pinned = true,
        collapsed = true, -- show window as closed/collapsed on start
        open = "Neotree position=right git_status",
      },
      {
        title = "Neo-Tree Buffers",
        ft = "neo-tree",
        filter = function(buf)
          return vim.b[buf].neo_tree_source == "buffers"
        end,
        pinned = true,
        collapsed = true, -- show window as closed/collapsed on start
        open = "Neotree position=top buffers",
      },
      {
        title = function()
          local buf_name = vim.api.nvim_buf_get_name(0) or "[No Name]"
          return vim.fn.fnamemodify(buf_name, ":t")
        end,
        ft = "Outline",
        pinned = true,
        open = "SymbolsOutlineOpen",
      },
      -- any other neo-tree windows
      "neo-tree",
    },
  },
}

  6. Use the edgy.nvim API

    main

    The following functions are available via require("edgy") to programmatically manage layouts and windows:

    -- Select a window with vim.ui.select in a position or all edgebars
require("edgy").select(pos?, filter?)

-- Close all edgebars or a specific edgebar in a position
require("edgy").close(pos?)

-- Open all pinned views in a position
require("edgy").open(pos?)

-- Toggle all pinned views in a position
require("edgy").toggle(pos?)

-- Move the cursor to the last focused main window
require("edgy").goto_main()

-- Get the Edgy.Window object for a given window or the current window
require("edgy").get_win(window?)

  7. Configure Edgy.View.Opts

    main

    When defining views in your layout, you can use the following properties to control how they behave:

    PropertyTypeDescription
    ftstringFile type of the view
    filterfun(buf:buffer, win:window)?Optional function to filter buffers and windows
    titlestring? or fun():stringOptional title of the view. Defaults to the capitalized filetype
    sizenumber or fun():numberSize of the short edge (minimum width for edgebars, minimum height for panels)
    pinnedboolean?If true, the view is always shown even when it has no windows
    collapsedboolean?If true, the view will be initially closed/collapsed
    openfun() or stringFunction or command to open a pinned view
    wovim.wo?View-specific window options

  8. Navigate and manage edgebar windows with keymaps

    main

    By default, edgy.nvim provides buffer-local keymaps for managing windows within an edgebar. You can also customize these in the keys configuration option.

    -- Default keymaps
-- q        : Close the window
-- <c-q>    : Hide the window
-- Q        : Close the edgebar
-- ]w, [w   : Next/Prev open window
-- ]W, [W   : Next/Prev loaded window