Improvements from symbols-outline.nvim and ⚠️ breaking changes

[hedyhli]

This comment documents changes from upstream before github detaches the fork into a proper repo.

---

Fixes

• Extra padding/indent on left on outline window removed. Fixed issues:
  • How to eliminate the indent (two spaces) on the left side? simrat39/symbols-outline.nvim#165
  • How do I get rid of all this wasted padding? simrat39/symbols-outline.nvim#178
  • How to decrease padding size? simrat39/symbols-outline.nvim#209
• Symbol preview empty (Current symbol preview is Empty simrat39/symbols-outline.nvim#176)
• OutlineClose crashing when already closed: fix: plugin crashes when SymbolOutlineClose used simrat39/symbols-outline.nvim#163
• Symbols not showing by supporting Nerd fonts v3.0: Update nerd fonts to 3.0 simrat39/symbols-outline.nvim#225
• Newlines in symbols crash: fix: replace newlines with spaces in writer simrat39/symbols-outline.nvim#204 (New lines in symbols break the outline menu simrat39/symbols-outline.nvim#184)
• code_actions: fix(code_actions): use the builtin code_action simrat39/symbols-outline.nvim#168 (Getting errors when trying to rename functions or use code actions. simrat39/symbols-outline.nvim#123)
• Fold all operation too slow: fix(folding): optimize fold/unfold all simrat39/symbols-outline.nvim#223 (Very slow fold all, unfold all operations simrat39/symbols-outline.nvim#224)
• "Invalid buffer id" error fix: Invalid buffer id error simrat39/symbols-outline.nvim#177
• Open handler triggering multiple times ends up in messy state with errors Open handler checks if view is not already open simrat39/symbols-outline.nvim#235
• Fixed _highlight_current_item function checking provider on outline window
• Fixed behaviour of empty markdown headings ^(#+)(%s+)$ being listed in the outline.

🛑 Breaking changes

The fork has been renamed to outline.nvim for the following reasons:

1. While symbols-outline is a great name, using SymbolsOutline* everywhere as a prefix for commands and highlight groups is quite long to type.
2. I did not find existing plugins that use the outline import path.
3. The only plugin I could find named outline.nvim does not use this import path.
4. This is a fork starting anew, it makes sense to undergo a rename.

Regardless of this rename, I am eternally grateful to @simrat39 for their work in the original symbols-outline.nvim. This plugin would not exist without it.

What this means for you:

• Commands and highlights that had the SymbolsOutline* prefix should now use Outline*
• The import path should be changed from symbols-outline to outline

:s/FocusedSymbol/OutlineCurrent/g
:s/SymbolsOutlineConnector/OutlineGuides/g
:%s/SymbolsOutline/Outline/g
:%s/symbols-outline/outline/g

Here are other breaking changes:

If your existing config uses the mentioned features, you can convert the setup opts using this script.

• Config: Configuration options have been significantly restructured to
  provide better consistency and understandability. Please see the default config for an example of the full list.

  • Options that control the looks and behaviour of outline window is now moved to outline_window table;
  • Options that control the items that show up are now in outline_items
  • Options for the preview window is in preview_window.
  • Symbol icons are now in symbols.icons, symbol blacklists are in symbols.blacklist
  • Lsp blacklists are now in providers.lsp.blacklist_clients.
  • Fold options are now in symbol_folding with fold_markers being symbol_folding.markers, consistent to guides.markers.

  The reasoning for the above is simple. When you see 'border' under preview_window you can directly infer it controls the border for the preview window. Previously, for example, when you see winblend or wrap: is it for the outline window or the preview window? Furthermore, this change also aids extensibility to the configuration, and avoids cluttering the root setup opts namespace.

  If you disagree with this decision, you are always free to switch back to the original symbols-outline.nvim, or you could pin a commit in this fork if you still want to use the features and fixes from here.

• 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.

  You can set guides = false to disable guides altogether, or set guides = true to enable it but use default configuration for the guides. Otherwise, please use guides.enabled if your configuration for guides is a table.

• Behaviour: Removed hover floating window from toggle_preview.

  • Instead, you can set open_hover_on_preview=true (false by default) so that the hover_symbol action can be triggered when toggle_previewis 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 (Do not close outline when focus_location occurs 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.

• (66aecc7) Algorithms in parser and writer modules have been rewritten for better performance. Various exported functions have been removed. Everything seems to work the same but because of this major rewrite some things may break which I've missed

Features

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) ([request] Toggle fold simrat39/symbols-outline.nvim#194).

• Control focus between outline and code window.

  • New commands: OutlineFocus,FocusOutline,FocusCode (see
    commands
  • Fixed issues:
    • Keep focus on current buffer when SymbolsOutline opens simrat39/symbols-outline.nvim#143
    • SymbolsOutlineFocus command is needed simrat39/symbols-outline.nvim#174
    • [Feature] Focus the Symbols Outline panel simrat39/symbols-outline.nvim#207

• Show line number of each symbol in outline window (see recipes for a screenshot)

  • Fixed issues: how to show souce code line number? simrat39/symbols-outline.nvim#212

• 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, default bindings are <C-j> and <C-k> just like Aerial.

• Flash highlight when using goto/peek location.

• Auto jump config option (see config auto_goto) (auto_jump config param simrat39/symbols-outline.nvim#229, Jump to symbol when the cursor moves simrat39/symbols-outline.nvim#228).

• New Follow command, opposite of goto_location/focus_location

• New restore location keymap option to go back to corresponding outline location synced with code (see config restore_location).

• Outline/Preview window border/background/winhighlight configuration. ([Question] Possible to change bg colour of main window? simrat39/symbols-outline.nvim#136). See outline_window.winhl, preview_window.winhl, preview_window.*width options.

• All highlights used including the virtual text for symbol details and symbol lineno are now fully customizable using outline_window.winhl. See highlights.

• Option to blend cursor with cursorline (outline_window.hide_cursor)

• Option to use lspkind for icons, and use your own fetcher function. See config and tips sections in the readme.

• Option for outline window split command

Screen recordings/shots of some of the features is shown at the bottom of the readme.

PRs

Key:

✅ = Either merged superseded
📮 = Planned for merge

• Distinguish between public and private function display in Elixir
  (#187 by scottming)

• Floating window (Draft)
  (#101 by druskus20)

Show completed PRs

• ✅ center view on goto symbol
  (#239 by skomposzczet)

  Superseded by adding config option

• ✅ Open handler checks if view is not already open
  (#235 by eyalz800)

• ✅ auto_jump config param
  (#229 by stickperson)

  Renamed to auto_goto for consistency

• ✅ 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

• ✅ 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-)

  Improved implementation

• ✅ Added preview width and relative size
  (#130 by Freyskeyd)

  Improved upon and refactored with new config structure

• ✅ Improve preview, hover windows configurability and looks
  (#128 by toppair)

  Improved upon and refactored with new config structure

• ✅ 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 was forgotten to be closed)

[hedyhli]

It looks there are a lot more people migrating from symbols-outline.nvim to outline.nvim than elsewhere, I've included a script that can convert the setup opts into the new structure.

[hedyhli]

Since github support has now detached my fork from symbols-outline.nvim, new changes from now on will be in CHANGELOG.md.