*symbols-outline.txt* For NVIM v0.7.0 Last change: 2023 November 02 ============================================================================== Table of Contents *symbols-outline-table-of-contents* 1. Fork status |symbols-outline-fork-status| - Maintenance status |symbols-outline-fork-status-maintenance-status| - Fixes |symbols-outline-fork-status-fixes| - ๐Ÿ›‘ Breaking changes |symbols-outline-fork-status-๐Ÿ›‘-breaking-changes| - Features |symbols-outline-fork-status-features| - PRs |symbols-outline-fork-status-prs| 2. symbols-outline.nvim |symbols-outline-symbols-outline.nvim| - Prerequisites |symbols-outline-symbols-outline.nvim-prerequisites| - Installation |symbols-outline-symbols-outline.nvim-installation| - Setup |symbols-outline-symbols-outline.nvim-setup| - Configuration |symbols-outline-symbols-outline.nvim-configuration| - Commands |symbols-outline-symbols-outline.nvim-commands| - Default keymaps |symbols-outline-symbols-outline.nvim-default-keymaps| - Highlights |symbols-outline-symbols-outline.nvim-highlights| - Recipes |symbols-outline-symbols-outline.nvim-recipes| ============================================================================== 1. Fork status *symbols-outline-fork-status* |symbols-outline-skip-to-plugin-readme| This is a fork of the original symbols-outline.nvim which fixes a lot of bugs from the original repo. It also adds many more features listed |symbols-outline-below|. It does not attempt to be an up-to-date successor of the original repo, nor does it attempt to ensure everyoneโ€™s use-cases are satisfied by providing an overall better experience. It is merely a fork which I maintain for my personal use-cases which incorporates some selected PRs. MAINTENANCE STATUS *symbols-outline-fork-status-maintenance-status* This fork is NOT guaranteed to be completely bug-free, nor as stable as the original (aside from the already broken things in the original repo). However, since I use this plugin myself, it is guaranteed that selected issues that I encounter myself would be fixed (to the best of my ability). I do not merge PRs from the original repo that I donโ€™t personally need. - **DO use this fork if**: - You want to use the bugfixes included in this fork, including `auto_preview`, and others listed in |symbols-outline-fixes| - You want to use |symbols-outline-features| available in this fork, which are not included upstream - You are OK with some things not being looked after well such as CoC support (things I donโ€™t personally use) - **Do NOT use this fork if**: - You want a stable plugin - You donโ€™t need the extra features in this fork - You do not need the bugfixes in this fork FIXES *symbols-outline-fork-status-fixes* - Symbol preview empty (simrat39/symbols-outline.nvim#176) - `SymbolsOutlineClose` crashing when already closed: simrat39/symbols-outline.nvim#163 - Symbols not showing by supporting Nerd fonts v3.0: simrat39/symbols-outline.nvim#225 - Newlines in symbols crash: simrat39/symbols-outline.nvim#204 (simrat39/symbols-outline.nvim#184) - `code_actions`: simrat39/symbols-outline.nvim#168 (simrat39/symbols-outline.nvim#123) - Fold all operation too slow: simrat39/symbols-outline.nvim#223 (simrat39/symbols-outline.nvim#224) - "Invalid buffer id" error simrat39/symbols-outline.nvim#177 - Open handler triggering multiple times ends up in messy state with errors simrat39/symbols-outline.nvim#235 ๐Ÿ›‘ BREAKING CHANGES *symbols-outline-fork-status-๐Ÿ›‘-breaking-changes* This section may be relevant to you if your existing config uses the mentioned features: - **Config**: `keymaps.focus_location` RENAMED to `keymaps.peek_location` to avoid confusion with focus window commands. - **Config**: Marker icons used for guides can now be customized. `show_guides` REMOVED in favor of `guides.enabled`. - **Behaviour**: Removed hover floating window from `toggle_preview`. - Instead, you can set `open_hover_on_preview=true` (true by default) so that the `hover_symbol` action can be triggered when `toggle_preview`is triggered. - The preview windowโ€™s size changed to half of neovim height (rather than a third). This is planned to be configurable. - The preview window is positioned to be vertically center-aligned (rather than fixed to the top). This is planned to be configurable. - **Behaviour**: When `auto_close=true` only auto close if `goto_location` is used (where focus changed), and not for `focus_location` (simrat39/symbols-outline.nvim#119). - **Behaviour**: For `auto_preview=true`, previously preview is only shown after some delay. Now preview is shown instantly every time the cursor moves. FEATURES *symbols-outline-fork-status-features* |symbols-outline-skip-this-section| Below is a list of features Iโ€™ve included in this fork which, at the time of writing, has not been included upstream (in the original repo). I try my best to keep this list up to date. Features/Changes: - Toggling folds (and added default keymaps for it) (simrat39/symbols-outline.nvim#194). - Control focus between outline and code window. - New commands: SymbolsOutline`Focus,FocusOutline,FocusCode` (see |symbols-outline-commands|) - Fixed issues: - simrat39/symbols-outline.nvim#143 - simrat39/symbols-outline.nvim#174 - simrat39/symbols-outline.nvim#207 - Cursorline option for the outline window. - Added function and command to show provider and outline window status, somewhat like `:LspInfo`. - Move down/up by one line and peek_location immediately. - Flash highlight when using goto/peek location. PRS *symbols-outline-fork-status-prs* |symbols-outline-skip-this-section| Key: > โœ… = Either merged superseded ๐Ÿ“ฎ = Planned for merge < - โœ… Open handler checks if view is not already open (#235 by eyalz800) - auto_jump config param (#229 by stickperson) - โœ… Update nerd fonts to 3.0 (#225 by anstadnik) - โœ… fix(folding): optimize fold/unfold all (#223 by wjdwndud0114) - โœ… Support markdown setext-style headers (#222 by msr1k) - โœ… fix(icons): replace obsolete icons (#219 by loichyan) **Superseded by #225** - โœ… Support ccls symbols (#218 by rqdmap) - โœ… fix: replace newlines with spaces in writer (#204 by tbung) - โœ… Make close_outline idempotent (#200 by showermat) **Superseded by #163** - Distinguish between public and private function display in Elixir (#187 by scottming) - โœ… Fix some options (#180 by cljoly) - โœ… fix: Invalid buffer id error (#177 by snowair) - โœ… fix(code_actions): use the builtin code_action (#168 by zjp-CN) - โœ… fix: plugin crashes when SymbolOutlineClose used (#163 by beauwilliams) - feat: Add window_bg_highlight to config (#137 by Zane-) - ๐Ÿ“ฎ Added preview width and relative size (#130 by Freyskeyd) - ๐Ÿ“ฎ Improve preview, hover windows configurability and looks (#128 by toppair) - โœ… Do not close outline when focus_location occurs (#119 by M1Sports20) - โœ… feat: instant_preview (#116 by axieax) **Superseded with an improved implementation** - โœ… check if code_win is nill (#110 by i3Cheese) **Superseded before this fork was created** (perhaps the PR ws forgotten to be closed) - Floating window (Draft) (#101 by druskus20) TODO ~ |symbols-outline-skip-this-section| Key: > - [ ] : Planned - [/] : WIP - : Idea < Items will be moved to above list when complete. - Folds - `[ ]` Org-like shift+tab behavior: Open folds level-by-level - `[ ]` Optionally not opening all child nodes when opening parent node - Fold siblings and siblings of parent on startup - Navigation - Go to parent - Cycle siblings - `[ ]` simrat39/symbols-outline.nvim#75: Handling of the outline window when attached buffer is closed. Maybe it should continue working, so that pressing enter can open a split to the correct location, and pressing `q` can properly close the buffer. - Preview / Hover - `[/]` Configurable winhighlight options for preview window (like nvim-cmp) (simrat39/symbols-outline#128) - `[/]` Configurable width and height (simrat39/symbols-outline#130) RELATED PLUGINS ~ - nvim-navic - nvim-navbuddy - dropdown.nvim - treesitter (inspect/edit) - lspsaga - navigator.lua ------------------------------------------------------------------------------ ============================================================================== 2. symbols-outline.nvim *symbols-outline-symbols-outline.nvim* **A tree like view for symbols in Neovim using the Language Server Protocol. Supports all your favourite languages.** PREREQUISITES *symbols-outline-symbols-outline.nvim-prerequisites* - `neovim 0.7+` - Properly configured Neovim LSP client INSTALLATION *symbols-outline-symbols-outline.nvim-installation* Use `hedyhli/symbols-outline.nvim` if you wish to use this fork. Packer: >lua use 'simrat39/symbols-outline.nvim' < Lazy: >lua { "simrat39/symbols-outline.nvim", config = function() -- Example mapping to toggle outline vim.keymap.set("n", "tt", "SymbolsOutline", { desc = "SymbolsOutline" }) require("symbols-outline").setup { -- Your setup opts here (leave empty to use defaults) } end, }, < Lazy with lazy-loading: >lua { "simrat39/symbols-outline.nvim", cmd = { "SymbolsOutline", "SymbolsOutlineOpen" }, keys = { -- Example mapping to toggle outline { "tt", "SymbolsOutline", desc = "Toggle outline window" }, }, opts = { -- Your setup opts here }, }, < This allows Lazy.nvim to lazy load the plugin on commands `SymbolsOutline`, `SymbolsOutlineOpen`, and your keybindings. SETUP *symbols-outline-symbols-outline.nvim-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-symbols-outline.nvim-configuration* TERMINOLOGY ~ - **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 OPTIONS ~ Pass a table to the setup call with your configuration options. Default values are shown: >lua local opts = { -- Where to open the split window: right/left position = 'right', -- Whether width is relative to existing windows relative_width = true, -- Percentage or integer of columns width = 25, -- Whether to highlight the currently hovered symbol (high cpu usage) highlight_hovered_item = true, -- Options for outline guides guides = { enabled = true, markers = { bottom = 'โ””', middle = 'โ”œ', vertical = 'โ”‚', horizontal = 'โ”€', }, }, -- Automatically open preview of code on hover auto_preview = false, -- Automatically open hover_symbol when opening toggle_preview (see keymaps). -- If you disable this you can still open hover_symbol using your keymap -- below. open_hover_on_preview = 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', -- Behaviour changed in this fork: -- Auto close the outline window if goto_location is triggered and not for -- peek_location auto_close = false, -- Vim options for the outline window show_numbers = false, show_relative_numbers = false, show_cursorline = true, -- Show extra details with the symbols (lsp dependent) show_symbol_details = true, -- Highlight group for the preview background preview_bg_highlight = 'Pmenu', -- Depth past which nodes will be folded by default autofold_depth = nil, -- Automatically unfold hovered symbol auto_unfold_hover = true, fold_markers = { '๏‘ ', '๏‘ผ' }, -- 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, -- Pseudo-transparency of the preview window winblend = 0 -- These keymaps can be a string or a table for multiple keys keymaps = { show_help = '?', close = {"", "q"}, -- Jump to symbol under cursor. -- It can auto close the outline window when triggered, see -- 'auto_close' option above. goto_location = "", -- Jump to symbol under cursor but keep focus on outline window. -- Renamed in this fork! peek_location = "o", hover_symbol = "", -- Preview symbol under cursor toggle_preview = "K", rename_symbol = "r", code_actions = "a", -- These fold actions are collapsing tree nodes, not code folding fold = "h", fold_toggle = '', -- 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 = '', -- Only in this fork unfold = "l", 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 = '', up_and_goto = '', }, -- Lsp clients to ignore lsp_blacklist = {}, -- Symbols to ignore. -- Possible values: lua/symbols-outline/symbols.lua symbol_blacklist = {}, symbols = { -- Changed in this fork 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" }, -- ccls TypeAlias = { icon = '๎ž ', hl = '@type' }, Parameter = { icon = '๎ช’ ', hl = '@parameter' }, StaticMethod = { icon = '๎ชŒ ', hl = '@function' }, Macro = { icon = '๏„ถ ', hl = '@macro' }, }, } < COMMANDS *symbols-outline-symbols-outline.nvim-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. LUA API ~ >lua require'symbols-outline' < - setup(opts) - **toggle_outline(opts)** Toggle opening/closing of outline window. If `opts.bang` is true, keep focus on previous window. - **open_outline(opts)** Open the outline window. If `opts.bang` is true, 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. DEFAULT KEYMAPS *symbols-outline-symbols-outline.nvim-default-keymaps* 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+Space Hover current symbol K Toggles the current symbol preview r Rename symbol a Code actions h fold 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-symbols-outline.nvim-highlights* Highlight Purpose ------------------------- ---------------------------------------- FocusedSymbol Highlight of the focused symbol Pmenu Highlight of the preview popup windows SymbolsOutlineConnector Highlight of the table connectors Comment Highlight of the info virtual text RECIPES *symbols-outline-symbols-outline.nvim-recipes* Behaviour you may want to achieve and the combination of configuration options to achieve it. **Unfold all others except currently hovered item** >lua autofold_depth = 1, auto_unfold_hover = true, < Any other recipes you think others may also find useful? Feel free to open a PR. ============================================================================== 3. Links *symbols-outline-links* 1. *demo*: https://github.com/simrat39/rust-tools-demos/raw/master/symbols-demo.gif Generated by panvimdoc vim:tw=78:ts=8:noet:ft=help:norl: