*symbols-outline.txt*       For NVIM v0.7.0      Last change: 2023 November 08

==============================================================================
Table of Contents                          *symbols-outline-table-of-contents*

  - Prerequisites                              |symbols-outline-prerequisites|
  - Installation                                |symbols-outline-installation|
  - Setup                                              |symbols-outline-setup|
  - Configuration                              |symbols-outline-configuration|
  - Commands                                        |symbols-outline-commands|
  - Default keymaps                          |symbols-outline-default-keymaps|
  - Highlights                                    |symbols-outline-highlights|
  - Lua API                                          |symbols-outline-lua-api|
  - Tips                                                |symbols-outline-tips|
  - Recipes                                          |symbols-outline-recipes|
**A tree like view for symbols in Neovim using the Language Server Protocol.
Supports all your favourite languages.**


PREREQUISITES                                  *symbols-outline-prerequisites*

- `neovim 0.7+`
- Properly configured Neovim LSP client


INSTALLATION                                    *symbols-outline-installation*

Packer:

>lua
    use 'hedyhli/symbols-outline.nvim'
<

Lazy:

>lua
    {
      "hedyhli/symbols-outline.nvim",
      config = function()
        -- Example mapping to toggle outline
        vim.keymap.set("n", "<leader>tt", "<cmd>SymbolsOutline<CR>",
          { desc = "SymbolsOutline" })
    
        require("symbols-outline").setup {
          -- Your setup opts here (leave empty to use defaults)
        }
      end,
    },
<

Lazy with lazy-loading:

>lua
    {
      "hedyhli/symbols-outline.nvim",
      cmd = { "SymbolsOutline", "SymbolsOutlineOpen" },
      keys = {
        -- Example mapping to toggle outline
        { "<leader>tt", "<cmd>SymbolsOutline<CR>", desc = "Toggle outline" },
      },
      opts = {
        -- Your setup opts here
      },
    },
<

This allows Lazy.nvim to lazy load the plugin on commands `SymbolsOutline`,
`SymbolsOutlineOpen`, and your keybindings.


SETUP                                                  *symbols-outline-setup*

Call the setup function with your configuration options.

Note that a call to `.setup()` is _required_ for this plugin to work
(simrat39/symbols-outline.nvim#213).

>lua
    require("symbols-outline").setup({})
<


CONFIGURATION                                  *symbols-outline-configuration*

The configuration structure has been heavily improved and refactored in this
plugin. For details and reasoning, see |symbols-outline-breaking-changes|.


TERMINOLOGY ~

Check this list if you there’s 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
- **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


DEFAULT OPTIONS ~

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

Default values are shown:

>lua
    {
      outline_window = {
        -- Where to open the split window: right/left
        position = 'right',
        -- Percentage or integer of columns
        width = 25, 
        -- 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,
    
        -- Behaviour changed in this fork:
        -- Auto close the outline window if goto_location is triggered and not for
        -- peek_location
        auto_close = false,
        -- Automatically go to location in code when navigating outline window.
        -- Only in this fork
        auto_goto = false,
    
        -- Vim options for the outline window
        show_numbers = false,
        show_relative_numbers = false,
        show_cursorline = true,  -- Only in this fork
    
        -- Whether to wrap long lines, or let them flow off the window
        wrap = false,
        -- Only in this fork:
        -- Whether to focus on the outline window when it is opened.
        -- Set to false to remain focus on your previous buffer when opening
        -- symbols-outline.
        focus_on_open = true,
        -- Only in this fork:
        -- Winhighlight option for outline window.
        -- See :help 'winhl'
        -- To change background color to "CustomHl" for example, set to "Normal:CustomHl".
        winhl = "SymbolsOutlineDetails:Comment,SymbolsOutlineLineno:LineNr",
      },
    
      outline_items = {
        -- Whether to highlight the currently hovered symbol (high cpu usage)
        highlight_hovered_item = true,
        -- Show extra details with the symbols (lsp dependent)
        show_symbol_details = true,
        -- Only in this fork.
        -- Show line numbers of each symbol next to them.
        -- Why? See this comment:
        -- https://github.com/simrat39/symbols-outline.nvim/issues/212#issuecomment-1793503563
        show_symbol_lineno = false,
      },
    
      -- Options for outline guides.
      -- Only in this fork
      guides = {
        enabled = true,
        markers = {
          bottom = '└',
          middle = '├',
          vertical = '│',
          horizontal = '─',
        },
      },
    
      symbol_folding = {
        -- Depth past which nodes will be folded by default
        autofold_depth = nil,
        -- Automatically unfold hovered symbol
        auto_unfold_hover = true,
        markers = { '', '' },
      },
    
      preview_window = {
        -- Automatically open preview of code location when navigating outline window
        auto_preview = false,
        -- Automatically open hover_symbol when opening preview (see keymaps for
        -- hover_symbol).
        -- If you disable this you can still open hover_symbol using your keymap
        -- below.
        -- Only in this fork
        open_hover_on_preview = true,
        -- Only in this fork:
        width = 50,     -- Percentage or integer of columns
        min_width = 50, -- This is the number of columns
        -- Whether width is relative to the total width of nvim.
        -- When relative_width = true, this means take 50% of the total
        -- screen width for preview window, ensure the result width is at least 50
        -- characters wide.
        relative_width = true,
        -- Border option for floating preview window.
        -- Options include: single/double/rounded/solid/shadow or an array of border
        -- characters.
        -- See :help nvim_open_win() and search for "border" option.
        border = 'single',
        -- winhl options for the preview window, see ':h winhl'
        winhl = '',
        -- Pseudo-transparency of the preview window, see ':h winblend'
        winblend = 0
      },
    
      -- These keymaps can be a string or a table for multiple keys
      keymaps = { 
        show_help = '?',
        close = {"<Esc>", "q"},
        -- Jump to symbol under cursor.
        -- It can auto close the outline window when triggered, see
        -- 'auto_close' option above.
        goto_location = "<Cr>",
        -- Jump to symbol under cursor but keep focus on outline window.
        -- Renamed in this fork!
        peek_location = "o",
        -- Only in this fork:
        -- Change cursor position of outline window to the current location in code.
        -- "Opposite" of goto/peek_location.
        restore_location = "<C-g>",
        -- Open LSP/provider-dependent symbol hover information
        hover_symbol = "<C-space>",
        -- Preview location code of the symbol under cursor
        toggle_preview = "K",
        -- Symbol actions
        rename_symbol = "r",
        code_actions = "a",
        -- These fold actions are collapsing tree nodes, not code folding
        fold = "h",
        unfold = "l",
        fold_toggle = "<Tab>",       -- Only in this fork
        -- Toggle folds for all nodes.
        -- If at least one node is folded, this action will fold all nodes.
        -- If all nodes are folded, this action will unfold all nodes.
        fold_toggle_all = "<S-Tab>", -- Only in this fork
        fold_all = "W",
        unfold_all = "E",
        fold_reset = "R",
        -- Only in this fork:
        -- Move down/up by one line and peek_location immediately.
        down_and_goto = "<C-j>",
        up_and_goto = "<C-k>",
      },
    
      providers = {
        lsp = {
          -- Lsp client names to ignore
          blacklist_clients = {},
        },
      },
    
      symbols = {
        -- Symbols to ignore.
        -- Possible values are the Keys in the icons table below.
        blacklist = {},
        -- Changed in this fork to fix deprecated icons not showing.
        icons = {
          File = { icon = "󰈔", hl = "@text.uri" },
          Module = { icon = "󰆧", hl = "@namespace" },
          Namespace = { icon = "󰅪", hl = "@namespace" },
          Package = { icon = "󰏗", hl = "@namespace" },
          Class = { icon = "𝓒", hl = "@type" },
          Method = { icon = "ƒ", hl = "@method" },
          Property = { icon = "", hl = "@method" },
          Field = { icon = "󰆨", hl = "@field" },
          Constructor = { icon = "", hl = "@constructor" },
          Enum = { icon = "ℰ", hl = "@type" },
          Interface = { icon = "󰜰", hl = "@type" },
          Function = { icon = "", hl = "@function" },
          Variable = { icon = "", hl = "@constant" },
          Constant = { icon = "", hl = "@constant" },
          String = { icon = "𝓐", hl = "@string" },
          Number = { icon = "#", hl = "@number" },
          Boolean = { icon = "⊨", hl = "@boolean" },
          Array = { icon = "󰅪", hl = "@constant" },
          Object = { icon = "⦿", hl = "@type" },
          Key = { icon = "🔐", hl = "@type" },
          Null = { icon = "NULL", hl = "@type" },
          EnumMember = { icon = "", hl = "@field" },
          Struct = { icon = "𝓢", hl = "@type" },
          Event = { icon = "🗲", hl = "@type" },
          Operator = { icon = "+", hl = "@operator" },
          TypeParameter = { icon = "𝙏", hl = "@parameter" },
          Component = { icon = "󰅴", hl = "@function" },
          Fragment = { icon = "󰅴", hl = "@constant" },
          -- Added ccls symbols in this fork
          TypeAlias =  { icon = ' ', hl = '@type' },
          Parameter = { icon = ' ', hl = '@parameter' },
          StaticMethod = { icon = ' ', hl = '@function' },
          Macro = { icon = ' ', hl = '@macro' },
        },
      },
    }
<

To find out exactly what some of the options do, please see the
|symbols-outline-recipes| section of the readme at the bottom for
screen-recordings.


COMMANDS                                            *symbols-outline-commands*

- **:SymbolsOutline[!]**
    Toggle symbols outline. With bang (`!`) the cursor focus stays in your original
    window after opening the outline window. Set `focus_on_win = true` to always
    use this behaviour.
- **:SymbolsOutlineOpen[!]**
    Open symbols outline. With bang (`!`) the cursor focus stays in your original
    window after opening the outline window. Set `focus_on_win = true` to always
    use this behaviour.
- **:SymbolsOutlineClose**
    Close symbols outline
- **:SymbolsOutlineFocus**
    Toggle focus on symbols outline
- **:SymbolsOutlineFocusOutline**
    Focus on symbols outline
- **:SymbolsOutlineFocusCode**
    Focus on source window
- **:SymbolsOutlineStatus**
    Display current provider and outline window status in the messages area.
- **:SymbolsOutlineFollow[!]**
    Go to corresponding node in outline based on cursor position in code, and focus
    on the outline window.
    With bang, retain focus on the code window.
    This can be understood as the converse of `goto_location` (see keymaps).
    `goto_location` sets cursor of code window to the position of outline window,
    whereas this command sets position in outline window to the cursor position of
    code window.
    With bang, it can be understood as the converse of `focus_location`.


DEFAULT KEYMAPS                              *symbols-outline-default-keymaps*

These mappings are active for the outline window.

  Key          Action
  ------------ ----------------------------------------------------
  Escape       Close outline
  ?            Show help message
  Enter        Go to symbol location in code
  o            Go to symbol location in code without losing focus
  Ctrl+k       Go up and goto location
  Ctrl+j       Go down and goto location
  Ctrl+g       Go to code location in outline window
  Ctrl+Space   Hover current symbol
  K            Toggles the current symbol preview
  r            Rename symbol
  a            Code actions
  h            Fold symbol or parent symbol
  Tab          Toggle fold under cursor
  Shift+Tab    Toggle all folds
  l            Unfold symbol
  W            Fold all symbols
  E            Unfold all symbols
  R            Reset all folding

HIGHLIGHTS                                        *symbols-outline-highlights*


OUTLINE WINDOW ~

Default:

>lua
    outline_window = {
      winhl = "SymbolsOutlineDetails:Comment,SymbolsOutlineLineno:LineNr",
    },
<

Possible highlight groups to customize:

  -------------------------------------------------------------------------
  Highlight                 Purpose
  ------------------------- -----------------------------------------------
  SymbolsOutlineCurrent     Highlight of the focused symbol

  SymbolsOutlineConnector   Highlight of the table connectors

  SymbolsOutlineDetails     Highlight of the details info virtual text

  SymbolsOutlineLineno      Highlight of the lineno column
  -------------------------------------------------------------------------

PREVIEW WINDOW ~

>lua
    preview_window = {
      winhl = "",
    },
<


LUA API                                              *symbols-outline-lua-api*

Symbols-outline provides the following public API for use in lua.

>lua
    require'symbols-outline'
<

- setup(opts)
- **toggle_outline(opts)**
    Toggle opening/closing of outline window.
    If `opts.focus_outline=false`, keep focus on previous window.
- **open_outline(opts)**
    Open the outline window.
    If `opts.focus_outline=false`, keep focus on previous window.
- **close_outline()**
    Close the outline window.
- **focus_toggle()**
    Toggle cursor focus between code and outline window.
- **focus_outline()**
    Focus cursor on the outline window.
- **focus_code()**
    Focus cursor on the window which the outline is derived from.
- **is_open()**
    Return whether the outline window is open.
- **show_status()**
    Display current provider and outline window status in the messages area.
- **has_provider()**
    Returns whether a provider is available for current window.
- **follow_cursor(opts)**
    Go to corresponding node in outline based on cursor position in code, and focus
    on the outline window.
    With `opts.focus_outline=false`, cursor focus will remain on code window.


TIPS                                                    *symbols-outline-tips*

- To open the outline but don’t focus on it, you can use `:SymbolsOutline!` or
    `:SymbolsOutlineOpen`.
    This is useful in autocmds, say you have a filetype that, whenever a buffer
    with that filetype is opened you want to open the outline.
- After navigating around in the outline window, you can use `<C-g>` (default
    mapping for `restore_location`) to go back to the corresponding outline
    location based on the code location.
- To customize the background colors, text colors, and borders, you can use
    `outline_window.winhl` for the outline window or `preview_window.winhl` for the
    preview floating window. See |symbols-outline-highlights|.


RECIPES                                              *symbols-outline-recipes*

Behaviour you may want to achieve and the combination of configuration options
to achieve it.

Code snippets in this section are to be placed in `.setup({ <HERE> })` directly
unless specified otherwise.

- **Unfold all others except currently hovered item**

>lua
    symbol_folding = {
      autofold_depth = 1,
      auto_unfold_hover = true,
    },
<



- **Use outline window as a quick-jump window**

>lua
    preview_window = {
      auto_preview = true,
    },
<


https://github.com/hedyhli/symbols-outline.nvim/assets/50042066/a473d791-d1b9-48e9-917f-b816b564a645

Note that in the recording I have `preview_window.open_hover_on_preview =
false`.

Alternatively, if you want to automatically navigate to the corresponding code
location directly and not use the preview window:

>lua
    outline_window = {
      auto_goto = true,
    },
<

This feature was added by @stickperson in an upstream PR 🙌


https://github.com/hedyhli/symbols-outline.nvim/assets/50042066/3d06e342-97ac-400c-8598-97a9235de66c

Or, you can use keys `<C-j>` and `<C-k>` to achieve the same effect, whilst not
having `auto_goto` on by default.

This feature is newly added in this fork.

- **Hide the extra details after each symbol name**

>lua
    outline_items = {
      show_symbol_details = false,
    },
<

- **Show line numbers next to each symbol to jump to that symbol quickly**

This feature is newly added in this fork.

>lua
    outline_items = {
      show_symbol_lineno = false,
    },
<

The default highlight group for the line numbers is `LineNr`, you can customize
it using `outline_window.winhl`: please see |symbols-outline-highlights|.



==============================================================================
1. Links                                               *symbols-outline-links*

1. *demo*: https://github.com/simrat39/rust-tools-demos/raw/master/symbols-demo.gif
2. *@stickperson*: 

Generated by panvimdoc <https://github.com/kdheepak/panvimdoc>

vim:tw=78:ts=8:noet:ft=help:norl: