Open a sidebar that shows you every mark that you can access from your current buffer, as well as the contexts in which those marks appear. Now with "peekaboo" support!
- Remember why you set those marks in the first place by looking at their context!
- Jump to marks directly from the markbar.
- Open automatically on
`or', à la vim-peekaboo! - Assign names to your marks that persist between vim sessions!
- (WIP) Synchronize those names between concurrent vim instances!
- Heavily customizable! See below for details.
vim-markbar requires either:
- vim 8.1, at least up through patch 8.1.0039.
- neovim 0.1.6 or newer.
neovim 0.1.6 was released in November of 2016, so if you use neovim at all, you're almost certainly fine. The vim packages included in the apt repositories for Ubuntu 20.04 and 22.04 are compatible.
With vim-plug,
" .vimrc
call plug#begin('~/.vim/bundle')
" ...
Plug 'Yilin-Yang/vim-markbar'
" ...
call plug#end()And then run :PlugInstall.
With Vundle,
" .vimrc
call vundle#begin()
" ...
Plugin 'Yilin-Yang/vim-markbar'
" ...
call vundle#end()And then run :PluginInstall.
With pathogen,
cd ~/.vim/bundle
git clone https://github.com/Yilin-Yang/vim-markbar.gitAt a minimum, you should set the following in your .vimrc.
nmap <Leader>m <Plug>ToggleMarkbar
" the following are unneeded if ToggleMarkbar is mapped
nmap <Leader>mo <Plug>OpenMarkbar
nmap <Leader>mc <Plug>CloseMarkbar
" this is required for mark names to persist between editor sessions
if has('nvim')
set shada+=!
else
set viminfo+=!
endif
" let g:markbar_persist_mark_names = v:true
" this lets you write your custom mark names to ShaDa/viminfo on demand,
" rather than waiting until you :q to exit. That lets you sync mark names
" between (neo)vim editor instances without closing and reopening vim.
"
" this and the mapping below will trigger wshada[!]/wviminfo[!] and
" rshada[!]/rviminfo[!]. trigger this after setting custom mark names
nmap <Leader>www <Plug>WriteMarkbarRosters
" trigger this mapping in other vim instances to update the mark names in
" their markbars
nmap <Leader>rrr <Plug>ReadMarkbarRosters
" when set to true, this echomsg's when rosters are read or written
let g:markbar_print_time_on_shada_io = v:trueThese examples use the leader key,
but you can use any mapping that you prefer. Note the use of map instead of
noremap: by definition, noremap mappings cannot trigger other mappings
and won't work with the functions given above.
You can manipulate marks in the markbar by moving your cursor over the mark or its context and then activating a keymapping.
By default, you:
- Jump to marks using
<Enter>, - Move the cursor to the next mark in the markbar using
n, - Move the cursor to the previous mark in the markbar using
N, - Rename marks using
r, - Clear the name of a mark using
c, - Delete marks entirely using
d.
Note that deleted marks may reappear in subsequent editor sessions in
neovim and vim < 8.2.0050.
Set g:markbar_force_clear_shared_data_on_delmark = v:true as a heavy-handed
workaround.
These bindings only activate while you have a markbar window focused, so they
shouldn't conflict with your other mappings. Note that the mappings for moving
between marks in the markbar do shadow vim's "repeat last search" mappings: if
you plan to frequently / or ? from inside the markbar, you may wish to
change those bindings.
A few examples of how to remap these bindings are given below:
" g, t to 'go to' the mark under the cursor
let g:markbar_jump_to_mark_mapping = 'gt'
" Ctrl-r, d to rename a mark
let g:markbar_rename_mark_mapping = '<C-r>d'
" Backspace to clear a mark's name
let g:markbar_reset_mark_mapping = '<BS>'The "peekaboo" markbar is meant to be used in the same fashion as vim's
built-in "jump to mark" functionality: to jump to a mark, the user
only needs to press ' or `, and then the key corresponding to their
target mark. Pressing 'a will open the peekaboo markbar and jump to mark a.
By default, pressing the apostrophe key (') or the backtick key (`)
opens the peekaboo markbar with apostrophe-like or backtick-like behavior,
respectively. "Apostrophe-like" behavior moves the cursor to "the first
non-blank character in the line of the specified location" (see :help mark-motions), while "backtick-like" behavior moves the cursor to the exact
line and column of the mark. See :help 'a for details.
If opened by accident, the peekaboo markbar can be closed by pressing Escape.
You can scroll the peekaboo markbar using standard vim keymappings, provided
that they don't collide with markbar mappings (e.g. Ctrl-D will scroll down
as expected, but j will jump to the mark j).
There also exist mappings to select a mark, i.e. move the cursor to
a particular mark's location in the markbar. By default, this is done by
prefixing the target mark with the <leader> key, e.g. '<leader>a to open
the peekaboo markbar and select mark a, rather than 'a to open it and
jump to mark a.
By default, you can jump to the selected mark by pressing the Enter key.
These are a few of the options that you're most likely to change. For full
documentation on options (what they are, their default values, and what they
do), see :help vim-markbar-options.
" for example
" only display alphabetic marks a-i and A-I
let g:markbar_marks_to_display = 'abcdefghiABCDEFGHI'
" width of a vertical split markbar
let g:markbar_width = 30
" indentation for lines of context
let g:markbar_context_indent_block = ' '
" number of lines of context to retrieve per mark
let g:markbar_num_lines_context = 3
" ditto, but more granularly (any may be omitted)
let g:markbar_num_lines_context = {
\ 'around_local': 3, " for local marks, show 3 lines of context
\ 'around_file': 0, " for file marks, show no context at all
\ 'peekaboo_around_local': 4, " like above, but for the peekaboo markbar
\ 'peekaboo_around_file': 2,
\ }
" markbar-local mappings
let g:markbar_jump_to_mark_mapping = 'G'
let g:markbar_next_mark_mapping = '/'
let g:markbar_previous_mark_mapping = '?'
let g:markbar_rename_mark_mapping = '<F2>'
let g:markbar_reset_mark_mapping = 'r'
let g:markbar_delete_mark_mapping = '<Del>'
" vim (not neovim) can behave weirdly when '<Esc>' is a mapping's LHS:
" vim-markbar tries to work around this, but if e.g. the arrow keys cause
" the peekaboo markbar to close erroneously, or if you prefer, you may want to
" change this.
let g:markbar_close_peekaboo_mapping = 'qq'
" when true, the peekaboo markbar only opens if the user waits for timeoutlen
" milliseconds after hitting ' or `
let g:markbar_explicitly_remap_mark_mappings = v:true
" to disable the peekaboo markbar entirely
" let g:markbar_enable_peekaboo = v:false
" Deleted marks may reappear in subsequent vim/neovim sessions. vim fixed
" this in patch 8.2.0050; this is still an issue in neovim,
" ref: https://github.com/neovim/neovim/issues/4295#issuecomment-544207151
" and https://github.com/Yilin-Yang/vim-markbar/issues/20
"
" This option works around that issue by running |:wviminfo!| or |:wshada!|
" whenever vim-markbar deletes a mark. Because that has side effects, this is
" disabled by default, but if you don't care/don't know what viminfo/shada are,
" then you can enable this to make mark deletion work as expected.
let g:markbar_force_clear_shared_data_on_delmark = v:true
" Whether to save user-set mark names in viminfo/shada. This is enabled by
" default.
" let g:markbar_persist_mark_names = v:true
" Persistent mark names requires viminfo-!/shada-!
if has('nvim')
set shada+=!
else
set viminfo+=!
endif
" open/close markbar mappings
nmap <Leader>m <Plug>ToggleMarkbar
nmap <Leader>mo <Plug>OpenMarkbar
nmap <Leader>mc <Plug>CloseMarkbarThe peekaboo markbar has its own equivalents for most of the standard markbar's
customization options, e.g. g:markbar_section_separation <--> g:markbar_peekaboo_section_separation. See :help vim-markbar-options for
details.
If you want to use the peekaboo markbar without shadowing vim's built-in "jump to marks" functionality, you can set the following options:
" open an 'apostrophe-like' peekaboo markbar with <Leader>a
let g:markbar_peekaboo_apostrophe_mapping = '<leader>a'
" open a 'backtick-like' peekaboo markbar with <Leader>b
let g:markbar_peekaboo_backtick_mapping = '<leader>b'Alternatively, if you want to set your own explicit mappings, you can set the following options:
" leave peekaboo markbar enabled, but don't set default mappings
let g:markbar_set_default_peekaboo_mappings = v:false
nmap <leader>a <Plug>OpenMarkbarPeekabooApostrophe
nmap <leader>b <Plug>OpenMarkbarPeekabooBacktickThe plugin sets buffer-local "select" and "jump to" mappings for every possible
mark on entering the peekaboo markbar. These mappings can be customized by
setting a prefix (e.g. <leader> for "select" mappings) or by setting
modifiers (e.g. Control, Shift, Meta).
The use of modifiers is not recommended. vim's built-in support for modifiers can be flaky at the best of times, and attempting to set multiple modifiers may lead to undefined behavior.
For example, you can set the following:
" select a mark by pressing backslash, and then the target mark
let g:markbar_peekaboo_select_prefix = '\'
" OR, select mark 'a' just by tapping the 'a' key
" NOTE: you'll have to change the 'jump_to_mark' mappings accordingly
let g:markbar_peekaboo_select_prefix = ''
" jump to mark 'a' by pressing Ctrl-Shift-Alt-a
" NOTE: this probably won't work in practice
let g:markbar_peekaboo_jump_to_mark_modifiers = 'control,shift,alt'As of the time of writing, the peekaboo markbar isn't fully compatible with
operator-pending mode, visual mode, or select mode. For instance, setting vmap ' <Plug>OpenMarkbarPeekabooApostrophe will allow you to open the
peekaboo markbar from visual mode, but doing so will cancel your visual selection.
For this reason, the peekaboo markbar only opens from normal mode by default.
If you don't want to open the peekaboo markbar for quick jumps (e.g.
double-tapping ' to go to "position before last jump"), then see
:help g:markbar_explicitly_remap_mark_mappings. Setting this option to
v:true will let you "short-circuit" the peekaboo markbar if you already know
which mark to jump to.
If you want to disable the peekaboo markbar entirely, you can set
g:markbar_enable_peekaboo to v:false.
When using vim (not neovim) with g:markbar_persist_mark_names set to v:true,
vim-markbar will reorder and clobber the timestamps of your command, search
string, expression, etc. history in your .viminfo file. (See Issue #56.)
This may change the order of the command history that you see after typing :
and using the Up and Down arrow keys. Unfortunately, the only way to fix this
(while still using vim) is to set g:markbar_persist_mark_names to v:false,
which will prevent you from setting mark names that persist between editor
sessions. neovim users won't experience this issue.
vim-markbar shows a header for each mark. In addition to a name set by the user, the default header consists of basic information about the mark, e.g. the file in which it resides, its line number, and its column number. If you'd like, you can customize how vim-markbar constructs these default names.
The default name for a file mark is controlled by the options:
let g:markbar_file_mark_format_string = '%s %s [l: %4d, c: %4d]'
let g:markbar_file_mark_arguments = ['name', 'fname', 'line', 'col']Which will produce a header name that looks like:
['A]: name_from_user test/30lines.txt [l: 10, c: 0]
" ^ 'name' ^ 'fname' ^ 'line' ^ 'col'You might decide to swap the line and column number, and also display them more compactly, like so:
['A]: name_from_user test/30lines.txt (0, 10)
" 'col' ^ ^ 'line'You can achieve this by setting the following options:
let g:markbar_file_mark_format_string = '%s %s (%d, %d)'
let g:markbar_file_mark_arguments = ['name', 'fname', 'col', 'line'] " note the swapped 'col' and 'line'See :help printf and :help g:markbar_mark_name_format_string for more details.
If you would like additional flexibility, you can provide vim-markbar with a reference to a "mark naming" function that you've written yourself. vim-markbar will call this function when generating mark headers, providing information about the mark as arguments and taking a string (the name of the mark) as a return value.
See :help vim-markbar-function-references for more details.
vim-markbar defines its own syntax file that it uses inside markbar buffers. This syntax file defines the following highlight groups, which you can customize to your liking.
| Highlight Group | Default Value (Linkage) | Description |
|---|---|---|
markbarComment |
Comment |
Lines that start with ". |
markbarSectionBrackets |
Type |
The square brackets in, e.g. ['A]. |
markbarSectionLowercaseMark |
Type |
The quote and letter in, e.g. ['a]. |
markbarSectionSpecialLocalMark |
Type |
The quote and symbol in, e.g. ['^]. |
markbarSectionNumberedMark |
Special |
The quote and number in, e.g. ['5]. |
markbarSectionUppercaseMark |
Underlined |
The quote and letter in, e.g. ['A]. |
markbarSectionName |
Title |
The text following the colon in, e.g. ['A]: Section Name Here |
markbarContext |
NormalNC |
The lines below the section headings, plucked from around the mark's actual location. |
markbarContextEndOfBuffer |
EndOfBuffer |
The ~ character that appears when a mark's context is cut off by the top or bottom of its parent file. |
markbarContextMarkHighlight |
TermCursor |
Highlighting used to show a mark's location in its context. |
These can be customized by linking them to other preexisting highlight groups (as is done by default), or by explicitly defining a colorscheme for the highlight group to use.
" 'reusing' an existing highlight group
hi link markbarContext String
" explicitly defining which colors to use, see `:h highlight-args` for details
hi markbarSectionNumberedMark cterm=bold ctermfg=green gui=bold guifg=greenIf you encounter bugs while using vim-markbar, or if you think of features that you would like to see in later versions, please feel free to report them on the repository's issues page.
If you'd like to try your hand at patching bugs or writing features yourself, you're also free to fork the repository and to submit pull requests. If you do, make sure that your code passes the existing vader.vim test suite, and make sure to write new tests as is appropriate.
See the test README.
If you're fixing a bug, try to replicate the bug (using the old, "broken" code) in a test case. If you're adding a new feature, try to write unit tests for the new feature.
MIT