2020-09-20 00:59:51 +02:00
|
|
|
# aerial.nvim
|
2021-06-16 17:48:32 +02:00
|
|
|
A code outline window for skimming and quick navigation
|
2020-09-20 02:29:26 +02:00
|
|
|
|
2021-06-17 04:22:57 +02:00
|
|
|
![Screenshot from 2021-06-16 19-05-43](https://user-images.githubusercontent.com/506791/122320750-9cddbc80-ced7-11eb-937e-90eed107f94e.png)
|
|
|
|
![Screenshot from 2021-06-16 19-17-00](https://user-images.githubusercontent.com/506791/122320760-9ea78000-ced7-11eb-8982-3d051992e91f.png)
|
2020-09-20 02:29:26 +02:00
|
|
|
|
|
|
|
## Requirements
|
|
|
|
Neovim 0.5 (nightly)
|
|
|
|
|
|
|
|
It's powered by LSP, so you'll need to have that already set up and working.
|
|
|
|
|
|
|
|
## Installation
|
|
|
|
aerial.nvim works with [Pathogen](https://github.com/tpope/vim-pathogen)
|
|
|
|
|
|
|
|
```sh
|
|
|
|
cd ~/.vim/bundle/
|
|
|
|
git clone https://github.com/stevearc/aerial.nvim
|
|
|
|
```
|
|
|
|
|
|
|
|
and [vim-plug](https://github.com/junegunn/vim-plug)
|
|
|
|
|
|
|
|
```vim
|
|
|
|
Plug 'stevearc/aerial.nvim'
|
|
|
|
```
|
|
|
|
|
2021-06-17 18:54:37 +02:00
|
|
|
## Setup
|
2020-09-20 02:29:26 +02:00
|
|
|
|
|
|
|
Step one is to get a Neovim LSP set up, which is beyond the scope of this guide.
|
|
|
|
See [nvim-lspconfig](https://github.com/neovim/nvim-lspconfig) for instructions.
|
|
|
|
|
|
|
|
After you have a functioning LSP setup, you will need to customize the
|
|
|
|
`on_attach` callback.
|
|
|
|
|
|
|
|
```lua
|
|
|
|
local aerial = require'aerial'
|
|
|
|
|
|
|
|
local custom_attach = function(client)
|
|
|
|
aerial.on_attach(client)
|
|
|
|
|
|
|
|
-- Aerial does not set any mappings by default, so you'll want to set some up
|
2021-06-16 18:18:12 +02:00
|
|
|
-- Toggle the aerial window with <leader>a
|
2021-06-17 20:10:54 +02:00
|
|
|
vim.api.nvim_buf_set_keymap(0, 'n', '<leader>a', '<cmd>AerialToggle!<CR>', {})
|
2021-06-18 01:26:13 +02:00
|
|
|
-- Jump forwards/backwards with '{' and '}'
|
|
|
|
vim.api.nvim_buf_set_keymap(0, 'n', '{', '<cmd>AerialPrev<CR>', {})
|
|
|
|
vim.api.nvim_buf_set_keymap(0, 'n', '}', '<cmd>AerialNext<CR>', {})
|
|
|
|
-- Jump forwards/backwards at the same tree level with '[[' and ']]'
|
|
|
|
vim.api.nvim_buf_set_keymap(0, 'n', '[[', '<cmd>AerialLPrev<CR>', {})
|
|
|
|
vim.api.nvim_buf_set_keymap(0, 'n', ']]', '<cmd>AerialLNext<CR>', {})
|
2020-09-20 02:29:26 +02:00
|
|
|
|
|
|
|
-- This is a great place to set up all your other LSP mappings
|
|
|
|
end
|
|
|
|
|
|
|
|
-- Set up your LSP clients here, using the custom on_attach method
|
2020-12-06 05:30:55 +01:00
|
|
|
require'lspconfig'.vimls.setup{
|
2020-09-20 02:29:26 +02:00
|
|
|
on_attach = custom_attach,
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
2021-06-17 20:10:54 +02:00
|
|
|
## Commands
|
|
|
|
|
|
|
|
Command | arg | description
|
|
|
|
------- | --- | -----------
|
|
|
|
`AerialToggle` | `left`/`right` | Open (and enter) or close the aerial window
|
|
|
|
`AerialToggle!` | `left`/`right` | Open or close the aerial window
|
|
|
|
`AerialOpen` | `left`/`right` | Open (and enter) the aerial window
|
|
|
|
`AerialOpen!` | `left`/`right` | Open the aerial window
|
|
|
|
`AerialClose` | | Close the aerial window
|
|
|
|
`AerialPrev` | N=1 | Jump backwards N symbols
|
|
|
|
`AerialNext` | N=1 | Jump forwards N symbols
|
2021-06-18 01:26:13 +02:00
|
|
|
`AerialLPrev` | N=1 | Jump backwards N symbols, skip symbols at a diffent tree level
|
|
|
|
`AerialLNext` | N=1 | Jump forwards N symbols, skip symbols at a diffent tree level
|
2021-06-18 00:33:35 +02:00
|
|
|
`AerialGo` | N=1, `v`/`h` | Jump to the Nth symbol
|
2021-06-17 20:10:54 +02:00
|
|
|
|
2021-06-17 18:54:37 +02:00
|
|
|
## Options
|
|
|
|
|
|
|
|
```lua
|
|
|
|
vim.g.aerial = {
|
2021-06-17 23:20:32 +02:00
|
|
|
-- Enum: persist, close, auto
|
|
|
|
-- persist - aerial window will stay open until closed
|
|
|
|
-- close - aerial window will close when original file is no longer visible
|
|
|
|
-- auto - aerial window will stay open as long as there is a visible
|
|
|
|
-- buffer to attach to
|
|
|
|
close_behavior = 'auto',
|
2021-06-18 02:06:21 +02:00
|
|
|
|
|
|
|
-- Set to false to remove the default keybindings for the aerial buffer
|
|
|
|
default_bindings = true,
|
|
|
|
|
2021-06-17 18:54:37 +02:00
|
|
|
-- Enum: prefer_right, prefer_left, right, left
|
|
|
|
-- Determines the default direction to open the aerial window. The 'prefer'
|
|
|
|
-- options will open the window in the other direction *if* there is a
|
|
|
|
-- different buffer in the way of the preferred direction
|
|
|
|
default_direction = 'prefer_right',
|
2021-06-18 02:06:21 +02:00
|
|
|
|
2021-06-17 18:54:37 +02:00
|
|
|
-- Fetch document symbols when LSP diagnostics change.
|
|
|
|
-- If you set this to false, you will need to manually fetch symbols
|
|
|
|
diagnostics_trigger_update = true,
|
2021-06-18 02:06:21 +02:00
|
|
|
|
2021-06-18 00:50:40 +02:00
|
|
|
-- Enum: split_width, full_width, last, none
|
2021-06-17 18:54:37 +02:00
|
|
|
-- Determines line highlighting mode when multiple buffers are visible
|
|
|
|
highlight_mode = 'split_width',
|
2021-06-18 02:06:21 +02:00
|
|
|
|
2021-06-17 18:54:37 +02:00
|
|
|
-- When jumping to a symbol, highlight the line for this many ms
|
|
|
|
-- Set to 0 or false to disable
|
|
|
|
highlight_on_jump = 300,
|
2021-06-18 02:06:21 +02:00
|
|
|
|
2021-06-18 06:02:44 +02:00
|
|
|
-- Fold code when folding the tree. Only works when manage_folds is enabled
|
|
|
|
link_tree_to_folds = true,
|
|
|
|
|
|
|
|
-- Fold the tree when folding code. Only works when manage_folds is enabled
|
|
|
|
link_folds_to_tree = false,
|
|
|
|
|
|
|
|
-- Use symbol tree for folding. Set to true or false to enable/disable
|
|
|
|
-- 'auto' will manage folds if your previous foldmethod was 'manual'
|
|
|
|
manage_folds = 'auto',
|
|
|
|
|
2021-06-17 18:54:37 +02:00
|
|
|
-- The maximum width of the aerial window
|
|
|
|
max_width = 40,
|
2021-06-18 02:06:21 +02:00
|
|
|
|
2021-06-17 18:54:37 +02:00
|
|
|
-- The minimum width of the aerial window.
|
|
|
|
-- To disable dynamic resizing, set this to be equal to max_width
|
|
|
|
min_width = 10,
|
2021-06-18 02:06:21 +02:00
|
|
|
|
2021-06-17 18:54:37 +02:00
|
|
|
-- Set default symbol icons to use Nerd Font icons (see https://www.nerdfonts.com/)
|
|
|
|
nerd_font = 'auto',
|
2021-06-18 02:06:21 +02:00
|
|
|
|
2021-06-17 18:54:37 +02:00
|
|
|
-- Whether to open aerial automatically when entering a buffer.
|
|
|
|
-- Can also be specified per-filetype as a map (see below)
|
|
|
|
open_automatic = false,
|
2021-06-18 02:06:21 +02:00
|
|
|
|
2021-06-17 18:54:37 +02:00
|
|
|
-- If open_automatic is true, only open aerial if the source buffer is at
|
|
|
|
-- least this long
|
|
|
|
open_automatic_min_lines = 0,
|
2021-06-18 02:06:21 +02:00
|
|
|
|
2021-06-17 18:54:37 +02:00
|
|
|
-- If open_automatic is true, only open aerial if there are at least this many symbols
|
|
|
|
open_automatic_min_symbols = 0,
|
2021-06-18 02:06:21 +02:00
|
|
|
|
2021-06-18 06:02:44 +02:00
|
|
|
-- Run this command after jumping to a symbol (false will disable)
|
|
|
|
post_jump_cmd = 'normal! zz',
|
2021-06-18 02:06:21 +02:00
|
|
|
|
2021-06-17 18:54:37 +02:00
|
|
|
-- Set to false to not update the symbols when there are LSP errors
|
|
|
|
update_when_errors = true,
|
2021-06-18 02:06:21 +02:00
|
|
|
|
2021-06-18 06:02:44 +02:00
|
|
|
-- A list of all symbols to display. Set to false to display all symbols.
|
2021-06-17 18:54:37 +02:00
|
|
|
filter_kind = {
|
|
|
|
"Class",
|
|
|
|
"Constructor",
|
|
|
|
"Enum",
|
|
|
|
"Function",
|
|
|
|
"Interface",
|
|
|
|
"Method",
|
|
|
|
"Struct",
|
|
|
|
},
|
|
|
|
}
|
|
|
|
|
|
|
|
-- open_automatic can be specified as a filetype map. For example, the below
|
|
|
|
-- configuration will open automatically in all filetypes except python and rust
|
|
|
|
vim.g.aerial = {
|
|
|
|
open_automatic = {
|
|
|
|
-- use underscore to specify the default behavior
|
|
|
|
['_'] = true,
|
|
|
|
python = false,
|
|
|
|
rust = false,
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
-- You can also override the default icons.
|
|
|
|
vim.g.aerial = {
|
|
|
|
icons = {
|
2021-06-17 20:10:54 +02:00
|
|
|
Class = '';
|
2021-06-17 18:54:37 +02:00
|
|
|
-- The icon to use when a class has been collapsed in the tree
|
|
|
|
ClassCollapsed = '喇';
|
2021-06-17 20:10:54 +02:00
|
|
|
Function = '';
|
|
|
|
Constant = '[c]'
|
2021-06-17 18:54:37 +02:00
|
|
|
-- The default icon to use when any symbol is collapsed in the tree
|
2021-06-17 20:10:54 +02:00
|
|
|
Collapsed = '▶';
|
2021-06-17 18:54:37 +02:00
|
|
|
}
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
Setting options in vimscript works the same way
|
|
|
|
```vim
|
|
|
|
" You can specify with global variables prefixed with 'aerial_'
|
|
|
|
let g:aerial_default_direction = 'left'
|
|
|
|
" Or you can set the g:aerial dict all at once
|
|
|
|
let g:aerial = {
|
|
|
|
\ 'default_direction': 'left',
|
|
|
|
\}
|
|
|
|
```
|
|
|
|
|
|
|
|
All possible SymbolKind values can be found [in the LSP
|
|
|
|
spec](https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#symbolKind).
|
|
|
|
These are the values used for configuring icons, highlight groups, and
|
|
|
|
filtering.
|
2021-06-17 03:55:09 +02:00
|
|
|
|
2021-06-17 05:33:06 +02:00
|
|
|
## Default Keybindings
|
2021-06-18 02:06:21 +02:00
|
|
|
The default keybindings in the aerial window. You can remove these by setting
|
|
|
|
`g:aerial_default_bindings = 0`, and add your own in `.vim/ftplugin/aerial.vim`
|
2021-06-17 05:33:06 +02:00
|
|
|
|
|
|
|
Key | Command
|
|
|
|
--- | -------
|
|
|
|
`<CR>` | Jump to the symbol under the cursor
|
|
|
|
`<C-v>` | Jump to the symbol in a vertical split
|
|
|
|
`<C-s>` | Jump to the symbol in a horizontal split
|
|
|
|
`<p>` | Scroll to the symbol (stay in aerial buffer)
|
|
|
|
`<C-j>` | Go down one line and scroll to that symbol
|
|
|
|
`<C-k>` | Go up one line and scroll to that symbol
|
2021-06-18 01:26:13 +02:00
|
|
|
`{` | Jump to the previous symbol
|
|
|
|
`}` | Jump to the next symbol
|
|
|
|
`[[` | Jump to the previous symbol at the same tree level
|
|
|
|
`]]` | Jump to the next symbol at the same tree level
|
2021-06-17 05:33:06 +02:00
|
|
|
`q` | Close the aerial window
|
2021-06-18 06:02:44 +02:00
|
|
|
`o` | Toggle the symbol under the cursor open/closed
|
|
|
|
`O` | Recursive toggle the symbol under the cursor open/closed
|
|
|
|
`zx` | Sync code folding to the tree (useful if they get out of sync)
|
|
|
|
`za` | Toggle the symbol under the cursor open/closed
|
|
|
|
`zA` | Recursive toggle the symbol under the cursor open/closed
|
|
|
|
`zo` | Open the symbol under the cursor
|
|
|
|
`zO` | Recursive open the symbol under the cursor
|
|
|
|
`zc` | Close the symbol under the cursor
|
|
|
|
`zC` | Recursive close the symbol under the cursor
|
2021-06-17 05:33:06 +02:00
|
|
|
|
|
|
|
## Highlight
|
|
|
|
|
|
|
|
There are highlight groups created for each `SymbolKind`. There will be one for
|
|
|
|
the name of the symbol (`Aerial<SymbolKind>`, and one for the icon
|
|
|
|
(`Aerial<SymbolKind>Icon`). For example:
|
|
|
|
|
2021-06-17 18:54:37 +02:00
|
|
|
```vim
|
|
|
|
hi link AerialClass Type
|
|
|
|
hi link AerialClassIcon Special
|
|
|
|
hi link AerialFunction Special
|
|
|
|
hi AerialFunctionIcon guifg=#cb4b16 guibg=NONE guisp=NONE gui=NONE cterm=NONE
|
2021-06-17 05:33:06 +02:00
|
|
|
|
2021-06-17 18:54:37 +02:00
|
|
|
" There's also this group for the cursor position
|
|
|
|
hi link AerialLine QuickFixLine
|
|
|
|
```
|