leigh/outline.nvim
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge branch 'master' of github.com:hedyhli/symbols-outline.nvim

Browse Source
This commit is contained in:
hedy
2023-11-08 14:33:01 +08:00
parent 011f2e6122 7922f990ae
commit 8abd2f6e9b
1 changed files with 240 additions and 150 deletions
Download Patch File Download Diff File Expand all files Collapse all files

390
doc/symbols-outline.txt
View File

@@ -19,6 +19,8 @@ Table of Contents *symbols-outline-table-of-contents*
- Commands |symbols-outline-symbols-outline.nvim-commands|
- Default keymaps |symbols-outline-symbols-outline.nvim-default-keymaps|
- Highlights |symbols-outline-symbols-outline.nvim-highlights|
- Lua API |symbols-outline-symbols-outline.nvim-lua-api|
- Tips |symbols-outline-symbols-outline.nvim-tips|
- Recipes |symbols-outline-symbols-outline.nvim-recipes|
==============================================================================
@@ -84,10 +86,34 @@ FIXES *symbols-outline-fork-status-fixes*
This section may be relevant to you if your existing config uses the mentioned
features:
- **Config**: Configuration options have been significantly restructured to
provide better consistency and understandability. Please see the
|symbols-outline-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` (true by default) so that
the `hover_symbol` action can be triggered when `toggle_preview`is
@@ -129,7 +155,8 @@ Features/Changes:
- 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.
- 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`)
(simrat39/symbols-outline.nvim#229, simrat39/symbols-outline.nvim#228).
@@ -137,7 +164,8 @@ Features/Changes:
- New restore location keymap option to go back to corresponding outline location
synced with code (see config `restore_location`).
Screen recordings of some of the features is shown at the bottom of the readme.
Screen recordings of some of the features is shown at the
|symbols-outline-bottom-of-the-readme|.
PRS *symbols-outline-fork-status-prs*
@@ -239,11 +267,12 @@ Table of contents
- |symbols-outline-setup|
- |symbols-outline-configuration|
- |symbols-outline-terminology|
- |symbols-outline-options|
- |symbols-outline-default-options|
- |symbols-outline-commands|
- |symbols-outline-lua-api|
- |symbols-outline-default-keymaps|
- |symbols-outline-highlights|
- |symbols-outline-lua-api|
- |symbols-outline-tips|
- |symbols-outline-recipes|
@@ -255,19 +284,17 @@ PREREQUISITES *symbols-outline-symbols-outline.nvim-prerequisites*
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'
use 'hedyhli/symbols-outline.nvim'
<
Lazy:
>lua
{
"simrat39/symbols-outline.nvim",
"hedyhli/symbols-outline.nvim",
config = function()
-- Example mapping to toggle outline
vim.keymap.set("n", "<leader>tt", "<cmd>SymbolsOutline<CR>",
@@ -284,11 +311,11 @@ Lazy with lazy-loading:
>lua
{
"simrat39/symbols-outline.nvim",
"hedyhli/symbols-outline.nvim",
cmd = { "SymbolsOutline", "SymbolsOutlineOpen" },
keys = {
-- Example mapping to toggle outline
{ "<leader>tt", "<cmd>SymbolsOutline<CR>", desc = "Toggle outline window" },
{ "<leader>tt", "<cmd>SymbolsOutline<CR>", desc = "Toggle outline" },
},
opts = {
-- Your setup opts here
@@ -314,9 +341,15 @@ Note that a call to `.setup()` is _required_ for this plugin to work
CONFIGURATION *symbols-outline-symbols-outline.nvim-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
@@ -329,23 +362,56 @@ TERMINOLOGY ~
- **Focus**: Which window the cursor is in
OPTIONS ~
DEFAULT 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,
{
outline_window = {
-- Where to open the split window: right/left
position = 'right',
-- Percentage or integer of columns
width = 25,
-- Whether width is relative to existing windows
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,
},
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,
},
-- Whether to highlight the currently hovered symbol (high cpu usage)
highlight_hovered_item = true,
-- Options for outline guides.
-- Only in this fork
guides = {
@@ -357,54 +423,35 @@ Default values are shown:
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.
-- Only in this fork
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,
-- 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
-- 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,
-- 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,
symbol_folding = {
-- Depth past which nodes will be folded by default
autofold_depth = nil,
-- Automatically unfold hovered symbol
auto_unfold_hover = true,
markers = { '', '' },
},
-- 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
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,
-- 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',
border_hl = 'Pmenu',
-- Highlight group for the preview background
bg_hl = 'Pmenu',
-- Pseudo-transparency of the preview window
winblend = 0
},
-- These keymaps can be a string or a table for multiple keys
keymaps = {
@@ -445,52 +492,58 @@ Default values are shown:
up_and_goto = '<C-k>',
},
-- Lsp clients to ignore
lsp_blacklist = {},
-- Symbols to ignore.
-- Possible values: lua/symbols-outline/symbols.lua
symbol_blacklist = {},
providers = {
lsp = {
-- Lsp client names to ignore
blacklist_clients = {},
},
},
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' },
-- 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, check out the
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.
@@ -526,39 +579,6 @@ COMMANDS *symbols-outline-symbols-outline.nvim-commands*
With bang, it can be understood as the converse of `focus_location`.
LUA API ~
>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.
DEFAULT KEYMAPS *symbols-outline-symbols-outline.nvim-default-keymaps*
These mappings are active for the outline window.
@@ -592,38 +612,96 @@ HIGHLIGHTS *symbols-outline-symbols-outline.nvim-highlights*
Pmenu Highlight of the preview popup windows
SymbolsOutlineConnector Highlight of the table connectors
Comment Highlight of the info virtual text
Note that some highlights are configurable such as the preview window border
and background. Please see |symbols-outline-configuration-options|.
LUA API *symbols-outline-symbols-outline.nvim-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-symbols-outline.nvim-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.
RECIPES *symbols-outline-symbols-outline.nvim-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
autofold_depth = 1,
auto_unfold_hover = true,
symbol_folding = {
autofold_depth = 1,
auto_unfold_hover = true,
},
<
Any other recipes you think others may also find useful? Feel free to open a
PR.
**Use outline window as a quick-jump window**
>lua
auto_preview = true,
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 and not use the preview window:
location directly and not use the preview window:
>lua
auto_goto = true,
outline_window = {
auto_goto = true,
},
<
This feature was added by @stickperson in an upstream PR 🙌
@@ -634,22 +712,34 @@ https://github.com/hedyhli/symbols-outline.nvim/assets/50042066/3d06e342-97ac-40
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
show_symbol_details = false,
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
show_symbol_lineno = true,
outline_items = {
show_symbol_lineno = false,
},
<
The default highlight group is `LineNr`.
The default highlight group for the line numbers is `LineNr`.
------------------------------------------------------------------------------
Any other recipes you think others may also find useful? Feel free to open a
PR.
==============================================================================
3. Links *symbols-outline-links*