docs: Document new options, commands, API functions
This commit is contained in:
hedy
@@ -52,6 +52,10 @@
|
||||
cursorline is enabled only when focus is in outline. This lessens the visual
|
||||
changes due to `auto_set_cursor`, when focus is in code.
|
||||
- Floating windows are now used for `show_help` keymap and `:OutlineStatus` command.
|
||||
- New command `:OutlineRefresh` and corresponding lua API function
|
||||
`refresh_outline()` triggers re-requesting of symbols from provider and
|
||||
updating the outline.
|
||||
- New lua API function `is_focus_in_outline()`
|
||||
|
||||
### Fixes
|
||||
|
||||
|
||||
99
README.md
99
README.md
@@ -58,6 +58,9 @@ Table of contents
|
||||
* [Custom icons](#custom-icons)
|
||||
* [Disable icons](#disable-icons)
|
||||
* [TODO](#todo)
|
||||
* [Limitations](#limitations)
|
||||
* [Preview window](#preview-window-1)
|
||||
* [Many outlines](#many-outlines)
|
||||
* [Related plugins](#related-plugins)
|
||||
|
||||
<!-- mtoc-end -->
|
||||
@@ -138,8 +141,9 @@ configuration.
|
||||
- **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
|
||||
- **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.
|
||||
@@ -182,7 +186,7 @@ Pass a table to the setup call with your configuration options.
|
||||
-- when jumping. false to disable.
|
||||
jump_highlight_duration = 300,
|
||||
-- Whether to center the cursor line vertically in the screen when
|
||||
-- jumping/focusing. Runs zz.
|
||||
-- jumping/focusing. Executes zz.
|
||||
center_on_jump = true,
|
||||
|
||||
-- Vim options for the outline window
|
||||
@@ -190,13 +194,14 @@ Pass a table to the setup call with your configuration options.
|
||||
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 is useful because with cursorline, there isn't really a need
|
||||
-- to know the vertical column position of the cursor and it may even
|
||||
-- be distracting, rendering lineno/guides/icons unreadable.
|
||||
-- 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.
|
||||
@@ -219,8 +224,6 @@ Pass a table to the setup call with your configuration options.
|
||||
},
|
||||
|
||||
outline_items = {
|
||||
-- Whether to highlight the currently hovered symbol and all direct parents
|
||||
highlight_hovered_item = true,
|
||||
-- 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
|
||||
@@ -228,6 +231,25 @@ Pass a table to the setup call with your configuration options.
|
||||
-- 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 = { 'CursorMoved' },
|
||||
-- Re-request symbols from the provider.
|
||||
-- This can be triggered manually through `refresh_outline` lua API, or
|
||||
-- :OutlineRefresh command.
|
||||
items = { 'InsertLeave', 'WinEnter', 'BufEnter', 'BufWinEnter', 'TabEnter', 'BufWritePost' },
|
||||
},
|
||||
},
|
||||
|
||||
-- Options for outline guides which help show tree hierarchy of symbols
|
||||
@@ -296,7 +318,6 @@ Pass a table to the setup call with your configuration options.
|
||||
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
|
||||
@@ -494,6 +515,19 @@ A fallback is always used if the previous candidate returned a falsey value.
|
||||
|
||||
With bang, it can be understood as the converse of `peek_location`.
|
||||
|
||||
This is automatically triggered on events
|
||||
`config.outline_items.auto_update_events.follow`.
|
||||
|
||||
You can also trigger this manually using the `restore_location` keymap
|
||||
(default `<C-g>`) from the outline window.
|
||||
|
||||
- **:OutlineRefresh**
|
||||
|
||||
Trigger refresh of symbols from provider and update outline items.
|
||||
|
||||
This is automatically triggered on events
|
||||
`config.outline_items.auto_update_events.refresh`.
|
||||
|
||||
|
||||
## Default keymaps
|
||||
|
||||
@@ -625,6 +659,20 @@ require'outline'
|
||||
|
||||
With `opts.focus_outline=false`, cursor focus will remain on code window.
|
||||
|
||||
This is automatically called on events
|
||||
`config.outline_items.auto_update_events.follow`.
|
||||
|
||||
- **is_focus_in_outline()**
|
||||
|
||||
Return whether outline is open and current focus is in outline.
|
||||
|
||||
- **refresh_outline()**
|
||||
|
||||
Re-request symbols from provider and update outline items.
|
||||
|
||||
This is automatically called on events
|
||||
`config.outline_items.auto_update_events.refresh`.
|
||||
|
||||
|
||||
## Tips
|
||||
|
||||
@@ -854,20 +902,31 @@ Key:
|
||||
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.nvim#128)
|
||||
- ✅ Configurable width and height of preview window (simrat39/symbols-outline.nvim#130)
|
||||
|
||||
- View
|
||||
- ✅ Outline window customizations (simrat39/symbols-outline.nvim#137)
|
||||
- ✅ Option to show line number next to symbols (simrat39/symbols-outline.nvim#212)
|
||||
- ✅ Option to hide cursor in outline window if cursorline enabled
|
||||
the correct location like `NvimTree` does, and pressing `q` can properly
|
||||
close the buffer.
|
||||
|
||||
<!-- panvimdoc-ignore-end -->
|
||||
|
||||
## Limitations
|
||||
|
||||
### Preview window
|
||||
|
||||
Sometimes the preview window could be slow in loading. This could be due to the
|
||||
code buffer being large. As of now there are no good solutions in circumventing
|
||||
this problem — currently the entire code buffer is read, and then put into the
|
||||
preview buffer. If only the required portion to preview is read and set
|
||||
instead, there would be highlighting issues (say the calculated starting line
|
||||
was within a markdown code block, so what was previously not supposed to be
|
||||
code is now highlighted as code).
|
||||
|
||||
### Many outlines
|
||||
|
||||
Outline.nvim does not support having multiple outlines attached to different
|
||||
buffers as of now. However, this feature is
|
||||
[planned](https://github.com/hedyhli/outline.nvim/issues/26), and for now you
|
||||
can use a single outline sidebar and have it auto-update whenever you switch
|
||||
buffers.
|
||||
|
||||
## Related plugins
|
||||
|
||||
- Aerial.nvim
|
||||
|
||||
@@ -610,7 +610,7 @@ function M.is_open()
|
||||
return M.view:is_open()
|
||||
end
|
||||
|
||||
function M.is_active()
|
||||
function M.is_focus_in_outline()
|
||||
local winid = vim.fn.win_getid()
|
||||
if M.view:is_open() and winid == M.view.winnr then
|
||||
return true
|
||||
@@ -621,7 +621,7 @@ end
|
||||
---Whether there is currently an available provider.
|
||||
---@return boolean has_provider
|
||||
function M.has_provider()
|
||||
if M.is_active() then
|
||||
if M.is_focus_in_outline() then
|
||||
return _G._outline_current_provider ~= nil
|
||||
end
|
||||
return providers.has_provider()
|
||||
@@ -631,7 +631,7 @@ function M.show_status()
|
||||
---@type outline.StatusContext
|
||||
local ctx = {}
|
||||
local p = _G._outline_current_provider
|
||||
if not M.is_active() then
|
||||
if not M.is_focus_in_outline() then
|
||||
p = providers.find_provider()
|
||||
end
|
||||
|
||||
|
||||
Reference in New Issue
Block a user