<!-- panvimdoc-ignore-start --> <details> <summary>⚠️ Coming from <strong>symbols-outline.nvim</strong>?</summary>

This is a fork of the original symbols-outline.nvim with many fixes and improvements, you can see the full list in #12 on github with links to issues from the original repo, and after outline.nvim was detached as a fork, all changes are documented in the changelog.

Migrating your configuration

If you have existing setup opts for symbols-outline.nvim, you can convert it to be usable for outline.nvim using this script: scripts/convert-symbols-outline-opts.lua.

</details> <!-- panvimdoc-ignore-end -->

---

<!-- panvimdoc-ignore-start -->

outline.nvim

A sidebar with a tree-like outline of symbols from your code, powered by LSP.

https://github.com/hedyhli/outline.nvim/assets/50042066/f66fa661-b66a-4b48-84e8-37920a3d8d2c

Features

• Auto-updates items and highlight for current symbol as the cursor moves
• Supports JSX (treesitter), Markdown, Norg (treesitter), Man, in addition to LSP.
• Support for other languages for treesitter through an external provider.
• Outline window opened for each tabpage
• Symbol hierarchy UI with collapsible nodes and automatic collapsing based on cursor movements
• Custom symbol icon function, mapping, or use LspKind (see custom function and config)
• Dynamically set cursorline and cursor colors in outline (see screenshot)
• Extra symbol details and line numbers of symbols (see screenshot)
• Preview symbol location without visiting it
• Neovim command modifiers on where to open outline (see :h mods)

Unconvinced? Check out the outline.nvim alternatives and related plugins.

<!-- panvimdoc-ignore-end -->

Prerequisites

• Neovim 0.7+
  • Note that it is recommended to use Neovim 0.8+ for all the features and fixes. See details here. Everything else works as normal in Neovim 0.7.
• To use outline.nvim with LSP, a properly configured LSP client is required.

<!-- panvimdoc-ignore-start -->

Contents

<!-- mtoc-start -->

• Installation
• Setup
• Configuration
• Providers
• Commands
• Default keymaps
• Highlights
• Lua API
• Tips
• Recipes
• Neovim 0.7
• Limitations
• Related plugins

<!-- mtoc-end --> <!-- panvimdoc-ignore-end -->

Installation

• GitHub repo: "hedyhli/outline.nvim"
• Or SourceHut repo: url = "https://git.sr.ht/~hedy/outline.nvim" (an equivalent key to url for your plugin manager)

Lazy.nvim example:

{
  "hedyhli/outline.nvim",
  config = function()
    -- Example mapping to toggle outline
    vim.keymap.set("n", "<leader>o", "<cmd>Outline<CR>",
      { desc = "Toggle Outline" })

    require("outline").setup {
      -- Your setup opts here (leave empty to use defaults)
    }
  end,
},

Lazy.nvim with lazy-loading example:

{
  "hedyhli/outline.nvim",
  lazy = true,
  cmd = { "Outline", "OutlineOpen" },
  keys = { -- Example mapping to toggle outline
    { "<leader>o", "<cmd>Outline<CR>", desc = "Toggle outline" },
  },
  opts = {
    -- Your setup opts here
  },
},

This allows Lazy.nvim to lazy-load the plugin on commands Outline, OutlineOpen, and your keybindings.

Setup

Call the setup function with your configuration options.

Note that a call to .setup() is required for this plugin to work (otherwise you might see this error: simrat39/symbols-outline.nvim#213).

require("outline").setup({})

Skip to commands

Configuration

The configuration structure has been heavily improved and refactored in this plugin. If you're migrating from the original symbols-outline, see #12 on github under "breaking changes" section.

Terminology

Check this list if you have any confusion with the terms used in the configuration.

• Provider: Source of the items in the outline view. Could be LSP, CoC, etc.
• Node: An item in the outline view
• Fold: Collapse a collapsible node
• Location: Where in the source file a node is from
• Preview: Show the location of a node in code using a floating window. Syntax highlighting is provided if treesitter is installed.
• Jump/Peek: Go to corresponding location in code without leaving outline window
• Hover: Cursor currently on the line of a node
• Hover symbol: Displaying a floating window to show symbol information provided by provider.
• Focus: Which window the cursor is in
• Follow: Update hover highlight and cursor position in outline to match position in code. Opposite of 'jump'.

Skip to commands

Default options

Pass a table to the setup call with your configuration options.

<details><summary>Show defaults</summary>

{
  outline_window = {
    -- Where to open the split window: right/left
    position = 'right',
    -- The default split commands used are 'topleft vs' and 'botright vs'
    -- depending on `position`. You can change this by providing your own
    -- `split_command`.
    -- `position` will not be considered if `split_command` is non-nil.
    -- This should be a valid vim command used for opening the split for the
    -- outline window. Eg, 'rightbelow vsplit'.
    -- Width can be included (with will override the width setting below):
    -- Eg, `topleft 20vsp` to prevent a flash of windows when resizing.
    split_command = nil,

    -- Percentage or integer of columns; serves as the base/minimum width
    -- for the outline window (and for auto_width calculations)
    width = 25,
    -- When auto_width.enabled = true, 'width' is the minimum window width.
    -- When auto_width.enabled = false, 'width' is the exact/default window width.
    auto_width = {
      -- Dynamically resize window width to fit content
      enabled = false,
      -- Maximum width (columns or percent if relative_width)
      max_width = 40,
      -- Include symbol details in width calculation
      include_symbol_details = false,
    },
    -- Whether width is relative to the total width of nvim
    -- When relative_width = true, this means take 25% of the total
    -- screen width for outline window.
    relative_width = true,

    -- Auto close the outline window if goto_location is triggered and not for
    -- peek_location
    auto_close = false,
    -- Automatically scroll to the location in code when navigating outline window.
    auto_jump = false,
    -- boolean or integer for milliseconds duration to apply a temporary highlight
    -- when jumping. false to disable.
    jump_highlight_duration = 300,
    -- Whether to center the cursor line vertically in the screen when
    -- jumping/focusing. Executes zz.
    center_on_jump = true,

    -- Vim options for the outline window
    show_numbers = false,
    show_relative_numbers = false,
    wrap = false,

    -- true/false/'focus_in_outline'/'focus_in_code'.
    -- The last two means only show cursorline when the focus is in outline/code.
    -- 'focus_in_outline' can be used if the outline_items.auto_set_cursor
    -- operations are too distracting due to visual contrast caused by cursorline.
    show_cursorline = true,
    -- Enable this only if you enabled cursorline so your cursor color can
    -- blend with the cursorline, in effect, as if your cursor is hidden
    -- in the outline window.
    -- This makes your line of cursor have the same color as if the cursor
    -- wasn't focused on the outline window.
    -- This feature is experimental.
    hide_cursor = false,

    -- Whether to auto-focus on the outline window when it is opened.
    -- Set to false to *always* retain focus on your previous buffer when opening
    -- outline.
    -- If you enable this you can still use bangs in :Outline! or :OutlineOpen! to
    -- retain focus on your code. If this is false, retaining focus will be
    -- enforced for :Outline/:OutlineOpen and you will not be able to have the
    -- other behaviour.
    focus_on_open = true,
    -- Winhighlight option for outline window.
    -- See :help 'winhl'
    -- To change background color to "CustomHl" for example, use "Normal:CustomHl".
    winhl = '',
    -- Message displayed when there are no providers avialable.
    no_provider_message = 'No supported provider...'
  },

  outline_items = {
    -- Show extra details with the symbols (lsp dependent) as virtual next
    show_symbol_details = true,
    -- Show corresponding line numbers of each symbol on the left column as
    -- virtual text, for quick navigation when not focused on outline.
    -- Why? See this comment:
    -- https://github.com/simrat39/symbols-outline.nvim/issues/212#issuecomment-1793503563
    show_symbol_lineno = false,
    -- Whether to highlight the currently hovered symbol and all direct parents
    highlight_hovered_item = true,
    -- Whether to automatically set cursor location in outline to match
    -- location in code when focus is in code. If disabled you can use
    -- `:OutlineFollow[!]` from any window or `<C-g>` from outline window to
    -- trigger this manually.
    auto_set_cursor = true,
    -- Autocmd events to automatically trigger these operations.
    auto_update_events = {
      -- Includes both setting of cursor and highlighting of hovered item.
      -- The above two options are respected.
      -- This can be triggered manually through `follow_cursor` lua API,
      -- :OutlineFollow command, or <C-g>.
      follow = { 'Cu