{"id":13479754,"url":"https://github.com/Yilin-Yang/vim-markbar","last_synced_at":"2025-03-27T10:30:44.824Z","repository":{"id":37431204,"uuid":"142402068","full_name":"Yilin-Yang/vim-markbar","owner":"Yilin-Yang","description":"Display all accessible marks and their surrounding lines in a collapsible sidebar.","archived":false,"fork":false,"pushed_at":"2024-05-10T21:47:52.000Z","size":461,"stargazers_count":190,"open_issues_count":7,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-30T13:38:19.053Z","etag":null,"topics":["bookmarks","sidebar","vim","vim-markbar","vim-plugin","viml","vimscript"],"latest_commit_sha":null,"homepage":"","language":"Vim Script","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Yilin-Yang.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-07-26T07:02:27.000Z","updated_at":"2024-10-12T18:00:16.000Z","dependencies_parsed_at":"2024-01-16T06:27:52.231Z","dependency_job_id":"5b996bf4-6c7f-4652-80b1-64859456d66b","html_url":"https://github.com/Yilin-Yang/vim-markbar","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yilin-Yang%2Fvim-markbar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yilin-Yang%2Fvim-markbar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yilin-Yang%2Fvim-markbar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yilin-Yang%2Fvim-markbar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Yilin-Yang","download_url":"https://codeload.github.com/Yilin-Yang/vim-markbar/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245826698,"owners_count":20678843,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bookmarks","sidebar","vim","vim-markbar","vim-plugin","viml","vimscript"],"created_at":"2024-07-31T16:02:22.467Z","updated_at":"2025-03-27T10:30:44.469Z","avatar_url":"https://github.com/Yilin-Yang.png","language":"Vim Script","funding_links":[],"categories":["Vim Script"],"sub_categories":[],"readme":"[![Build Status](https://app.travis-ci.com/Yilin-Yang/vim-markbar.svg?branch=master)](https://app.travis-ci.com/Yilin-Yang/vim-markbar)\n\nvim-markbar\n================================================================================\nOpen a sidebar that shows you every mark that you can access from your current\nbuffer, as well as the contexts in which those marks appear. Now with \"peekaboo\"\nsupport!\n\nFeatures\n--------------------------------------------------------------------------------\n\n### Demo\n![markbar](https://user-images.githubusercontent.com/23268616/47609602-2fbc4680-da10-11e8-9789-1ab6575d22d6.gif)\n\n[(asciinema Link)](https://asciinema.org/a/JY4F2AHb0PSBMINOQg6APFNa0)\n\n### List\n\n- **Remember** why you set those marks in the first place by looking at their context!\n- **Jump to marks** directly from the markbar.\n- **Open automatically on `` ` `` or `'`,** _à la_ [vim-peekaboo!](https://github.com/junegunn/vim-peekaboo)\n- **Assign names** to your marks that persist between vim sessions!\n- **(WIP) Synchronize those names** between concurrent vim instances!\n- **Heavily customizable!** See below for details.\n\nRequirements\n--------------------------------------------------------------------------------\nvim-markbar requires either:\n- **vim 8.1**, at least up through [patch 8.1.0039.](https://github.com/vim/vim/commit/d79a26219d7161e9211fd144f0e874aa5f6d251e)\n- **neovim 0.1.6** or newer.\n\nneovim 0.1.6 was released in November of 2016, so if you use neovim at all,\nyou're almost certainly fine. The vim packages included in the apt repositories\nfor [Ubuntu 20.04](https://packages.ubuntu.com/focal/vim) and [22.04](https://packages.ubuntu.com/jammy/vim)\nare compatible.\n\nInstallation\n--------------------------------------------------------------------------------\nWith [vim-plug,](https://github.com/junegunn/vim-plug)\n\n```vim\n\" .vimrc\ncall plug#begin('~/.vim/bundle')\n\" ...\nPlug 'Yilin-Yang/vim-markbar'\n\" ...\ncall plug#end()\n```\nAnd then run `:PlugInstall`.\n\n---\n\nWith [Vundle,](https://github.com/VundleVim/Vundle.vim)\n\n```vim\n\" .vimrc\ncall vundle#begin()\n\" ...\nPlugin 'Yilin-Yang/vim-markbar'\n\" ...\ncall vundle#end()\n```\nAnd then run `:PluginInstall`.\n\n---\n\nWith [pathogen,](https://github.com/tpope/vim-pathogen)\n\n```bash\ncd ~/.vim/bundle\ngit clone https://github.com/Yilin-Yang/vim-markbar.git\n```\n\nQuick Start\n--------------------------------------------------------------------------------\nAt a minimum, you should set the following in your `.vimrc`.\n\n```vim\nnmap \u003cLeader\u003em \u003cPlug\u003eToggleMarkbar\n\n\" the following are unneeded if ToggleMarkbar is mapped\nnmap \u003cLeader\u003emo \u003cPlug\u003eOpenMarkbar\nnmap \u003cLeader\u003emc \u003cPlug\u003eCloseMarkbar\n\n\" this is required for mark names to persist between editor sessions\nif has('nvim')\n    set shada+=!\nelse\n    set viminfo+=!\nendif\n\" let g:markbar_persist_mark_names = v:true\n\n\n\" this lets you write your custom mark names to ShaDa/viminfo on demand,\n\" rather than waiting until you :q to exit. That lets you sync mark names\n\" between (neo)vim editor instances without closing and reopening vim.\n\"\n\" this and the mapping below will trigger wshada[!]/wviminfo[!] and\n\" rshada[!]/rviminfo[!]. trigger this after setting custom mark names\nnmap \u003cLeader\u003ewww \u003cPlug\u003eWriteMarkbarRosters\n\n\" trigger this mapping in other vim instances to update the mark names in\n\" their markbars\nnmap \u003cLeader\u003errr \u003cPlug\u003eReadMarkbarRosters\n\n\" when set to true, this echomsg's when rosters are read or written\nlet g:markbar_print_time_on_shada_io = v:true\n```\n\nThese examples use the [leader key,](https://stackoverflow.com/questions/1764263/what-is-the-leader-in-a-vimrc-file)\nbut you can use any mapping that you prefer. **Note the use of `map` instead of\n`noremap`:** by definition, `noremap` mappings cannot trigger other mappings\nand won't work with the functions given above.\n\nYou can manipulate marks in the markbar by moving your cursor over the mark or\nits context and then activating a keymapping.\n\nBy default, you:\n\n- **Jump to marks** using `\u003cEnter\u003e`,\n- **Move the cursor to the next mark in the markbar** using `n`,\n- **Move the cursor to the previous mark in the markbar** using `N`,\n- **Rename marks** using `r`,\n- **Clear the name of a mark** using `c`,\n- **Delete marks entirely** using `d`.\n\n**Note** that deleted marks may reappear in subsequent editor sessions in\n[neovim](https://github.com/neovim/neovim/issues/4295) and [vim \u003c 8.2.0050](https://github.com/vim/vim/issues/1339).\nSet `g:markbar_force_clear_shared_data_on_delmark = v:true` as a heavy-handed\nworkaround.\n\nThese bindings only activate while you have a markbar window focused, so they\nshouldn't conflict with your other mappings. Note that the mappings for moving\nbetween marks in the markbar do shadow vim's \"repeat last search\" mappings: if\nyou plan to frequently `/` or `?` from inside the markbar, you may wish to\nchange those bindings.\n\nA few examples of how to remap these bindings are given below:\n\n```vim\n\" g, t to 'go to' the mark under the cursor\nlet g:markbar_jump_to_mark_mapping = 'gt'\n\n\" Ctrl-r, d to rename a mark\nlet g:markbar_rename_mark_mapping = '\u003cC-r\u003ed'\n\n\" Backspace to clear a mark's name\nlet g:markbar_reset_mark_mapping = '\u003cBS\u003e'\n```\n\n### The \"Peekaboo\" Markbar\nThe \"peekaboo\" markbar is meant to be used in the same fashion as vim's\nbuilt-in \"jump to mark\" functionality: to jump to a mark, the user\nonly needs to press `'` or `` ` ``, and then the key corresponding to their\ntarget mark. Pressing `'a` will open the peekaboo markbar and jump to mark `a`.\n\nBy default, pressing the apostrophe key (`'`) or the backtick key (`` ` ``)\nopens the peekaboo markbar with apostrophe-like or backtick-like behavior,\nrespectively. \"Apostrophe-like\" behavior moves the cursor to \"the first\nnon-blank character in the line of the specified location\" (see `:help\nmark-motions`), while \"backtick-like\" behavior moves the cursor to the exact\nline and column of the mark. See `:help 'a` for details.\n\nIf opened by accident, the peekaboo markbar can be closed by pressing `Escape`.\n\n#### Navigating the Peekaboo Markbar\nYou can scroll the peekaboo markbar using standard vim keymappings, provided\nthat they don't collide with markbar mappings (e.g. `Ctrl-D` will scroll down\nas expected, but `j` will jump to the mark `j`).\n\nThere also exist mappings to **select a mark,** i.e. move the cursor to\na particular mark's location in the markbar. By default, this is done by\nprefixing the target mark with the `\u003cleader\u003e` key, e.g. `'\u003cleader\u003ea` to open\nthe peekaboo markbar and _select_ mark `a`, rather than `'a` to open it and\n_jump to_ mark `a`.\n\nBy default, you can **jump to the selected mark** by pressing the `Enter` key.\n\nCustomization\n--------------------------------------------------------------------------------\n\n### Common Options\nThese are a few of the options that you're most likely to change. For full\ndocumentation on options (what they are, their default values, and what they\ndo), see `:help vim-markbar-options`.\n\n```vim\n\" for example\n\" only display alphabetic marks a-i and A-I\nlet g:markbar_marks_to_display = 'abcdefghiABCDEFGHI'\n\n\" width of a vertical split markbar\nlet g:markbar_width = 30\n\n\" indentation for lines of context\nlet g:markbar_context_indent_block = '  '\n\n\" number of lines of context to retrieve per mark\nlet g:markbar_num_lines_context = 3\n\n\" ditto, but more granularly (any may be omitted)\nlet g:markbar_num_lines_context = {\n    \\ 'around_local': 3,          \" for local marks, show 3 lines of context\n    \\ 'around_file': 0,           \" for file marks, show no context at all\n    \\ 'peekaboo_around_local': 4, \" like above, but for the peekaboo markbar\n    \\ 'peekaboo_around_file': 2,\n\\ }\n\n\" markbar-local mappings\nlet g:markbar_jump_to_mark_mapping  = 'G'\nlet g:markbar_next_mark_mapping     = '/'\nlet g:markbar_previous_mark_mapping = '?'\nlet g:markbar_rename_mark_mapping   = '\u003cF2\u003e'\nlet g:markbar_reset_mark_mapping    = 'r'\nlet g:markbar_delete_mark_mapping   = '\u003cDel\u003e'\n\n\" vim (not neovim) can behave weirdly when '\u003cEsc\u003e' is a mapping's LHS:\n\" vim-markbar tries to work around this, but if e.g. the arrow keys cause\n\" the peekaboo markbar to close erroneously, or if you prefer, you may want to\n\" change this.\nlet g:markbar_close_peekaboo_mapping = 'qq'\n\n\" when true, the peekaboo markbar only opens if the user waits for timeoutlen\n\" milliseconds after hitting ' or `\nlet g:markbar_explicitly_remap_mark_mappings = v:true\n\n\" to disable the peekaboo markbar entirely\n\" let g:markbar_enable_peekaboo = v:false\n\n\" Deleted marks may reappear in subsequent vim/neovim sessions. vim fixed\n\" this in patch 8.2.0050; this is still an issue in neovim,\n\" ref: https://github.com/neovim/neovim/issues/4295#issuecomment-544207151\n\" and https://github.com/Yilin-Yang/vim-markbar/issues/20\n\"\n\" This option works around that issue by running |:wviminfo!| or |:wshada!|\n\" whenever vim-markbar deletes a mark. Because that has side effects, this is\n\" disabled by default, but if you don't care/don't know what viminfo/shada are,\n\" then you can enable this to make mark deletion work as expected.\nlet g:markbar_force_clear_shared_data_on_delmark = v:true\n\n\" Whether to save user-set mark names in viminfo/shada. This is enabled by\n\" default.\n\" let g:markbar_persist_mark_names = v:true\n\n\" Persistent mark names requires viminfo-!/shada-!\nif has('nvim')\n    set shada+=!\nelse\n    set viminfo+=!\nendif\n\n\" open/close markbar mappings\nnmap \u003cLeader\u003em  \u003cPlug\u003eToggleMarkbar\nnmap \u003cLeader\u003emo \u003cPlug\u003eOpenMarkbar\nnmap \u003cLeader\u003emc \u003cPlug\u003eCloseMarkbar\n```\n\n### Peekaboo Customization\n\nThe peekaboo markbar has its own equivalents for most of the standard markbar's\ncustomization options, e.g. `g:markbar_section_separation \u003c--\u003e\ng:markbar_peekaboo_section_separation`. See `:help vim-markbar-options` for\ndetails.\n\nIf you want to use the peekaboo markbar without shadowing vim's built-in \"jump\nto marks\" functionality, you can set the following options:\n\n```vim\n\" open an 'apostrophe-like' peekaboo markbar with \u003cLeader\u003ea\nlet g:markbar_peekaboo_apostrophe_mapping = '\u003cleader\u003ea'\n\n\" open a 'backtick-like' peekaboo markbar with \u003cLeader\u003eb\nlet g:markbar_peekaboo_backtick_mapping = '\u003cleader\u003eb'\n```\n\nAlternatively, if you want to set your own explicit mappings, you can set the\nfollowing options:\n\n```vim\n\" leave peekaboo markbar enabled, but don't set default mappings\nlet g:markbar_set_default_peekaboo_mappings = v:false\n\nnmap \u003cleader\u003ea \u003cPlug\u003eOpenMarkbarPeekabooApostrophe\nnmap \u003cleader\u003eb \u003cPlug\u003eOpenMarkbarPeekabooBacktick\n```\n\n#### \"Select\" and \"Jump To\" Mappings\nThe plugin sets buffer-local \"select\" and \"jump to\" mappings for every possible\nmark on entering the peekaboo markbar. These mappings can be customized by\nsetting a **prefix** (e.g. `\u003cleader\u003e` for \"select\" mappings) or by setting\n**modifiers** (e.g. `Control`, `Shift`, `Meta`).\n\nThe use of modifiers is not recommended. vim's built-in support for modifiers\ncan be flaky at the best of times, and attempting to set multiple modifiers may\nlead to undefined behavior.\n\nFor example, you can set the following:\n\n```vim\n\" select a mark by pressing backslash, and then the target mark\nlet g:markbar_peekaboo_select_prefix = '\\'\n\n\" OR, select mark 'a' just by tapping the 'a' key\n\" NOTE: you'll have to change the 'jump_to_mark' mappings accordingly\nlet g:markbar_peekaboo_select_prefix = ''\n\n\" jump to mark 'a' by pressing Ctrl-Shift-Alt-a\n\" NOTE: this probably won't work in practice\nlet g:markbar_peekaboo_jump_to_mark_modifiers = 'control,shift,alt'\n```\n\n#### Known Issues\nAs of the time of writing, the peekaboo markbar isn't fully compatible with\noperator-pending mode, visual mode, or select mode. For instance, setting `vmap\n' \u003cPlug\u003eOpenMarkbarPeekabooApostrophe` will allow you to _open_ the\npeekaboo markbar from visual mode, but doing so will cancel your visual selection.\nFor this reason, the peekaboo markbar only opens from normal mode by default.\n\nIf you don't want to open the peekaboo markbar for quick jumps (e.g.\ndouble-tapping `'` to go to \"position before last jump\"), then see\n`:help g:markbar_explicitly_remap_mark_mappings`. Setting this option to\n`v:true` will let you \"short-circuit\" the peekaboo markbar if you already know\nwhich mark to jump to.\n\nIf you want to disable the peekaboo markbar entirely, you can set\n`g:markbar_enable_peekaboo` to `v:false`.\n\nWhen using vim (not neovim) with `g:markbar_persist_mark_names` set to `v:true`,\nvim-markbar will reorder and clobber the timestamps of your command, search\nstring, expression, etc. history in your `.viminfo` file. (See [Issue #56](https://github.com/Yilin-Yang/vim-markbar/issues/56).)\nThis may change the order of the command history that you see after typing `:`\nand using the Up and Down arrow keys. Unfortunately, the only way to fix this\n(while still using vim) is to set `g:markbar_persist_mark_names` to `v:false`,\nwhich will prevent you from setting mark names that persist between editor\nsessions. neovim users won't experience this issue.\n\n### Mark Header Customization\nvim-markbar shows a header for each mark. In addition to a name set by the\nuser, the default header consists of basic information about the mark,\ne.g. the file in which it resides, its line number, and its column number. If\nyou'd like, you can customize how vim-markbar constructs these default names.\n\nThe default name for a file mark is controlled by the options:\n```vim\nlet g:markbar_file_mark_format_string = '%s %s [l: %4d, c: %4d]'\nlet g:markbar_file_mark_arguments = ['name', 'fname', 'line', 'col']\n```\n\nWhich will produce a header name that looks like:\n```vim\n['A]: name_from_user test/30lines.txt [l:   10, c:    0]\n\"     ^ 'name'       ^ 'fname'              ^ 'line'  ^ 'col'\n```\n\nYou might decide to swap the line and column number, and also display them more\ncompactly, like so:\n\n```vim\n['A]: name_from_user test/30lines.txt (0, 10)\n\"                                'col' ^  ^ 'line'\n```\n\nYou can achieve this by setting the following options:\n```vim\nlet g:markbar_file_mark_format_string = '%s %s (%d, %d)'\nlet g:markbar_file_mark_arguments = ['name', 'fname', 'col', 'line'] \" note the swapped 'col' and 'line'\n```\n\nSee `:help printf` and `:help g:markbar_mark_name_format_string` for more details.\n\n#### Naming Marks with User-Provided Functions\nIf you would like additional flexibility, you can provide vim-markbar with a\nreference to a \"mark naming\" function that you've written yourself. vim-markbar\nwill call this function when generating mark headers, providing information\nabout the mark as arguments and taking a string (the name of the mark) as a\nreturn value.\n\nSee `:help vim-markbar-function-references` for more details.\n\n### Highlight Groups\nvim-markbar defines its own syntax file that it uses inside markbar buffers.\nThis syntax file defines the following highlight groups, which you can\ncustomize to your liking.\n\n| Highlight Group                 | Default Value (Linkage) | Description                           |\n|:--------------------------------|:-----------------------:|:--------------------------------------|\n|`markbarComment`                 | `Comment`               | Lines that start with `\"`.            |\n|`markbarSectionBrackets`         | `Type`                  | The square brackets in, e.g. `['A]`.  |\n|`markbarSectionLowercaseMark`    | `Type`                  | The quote and letter in, e.g. `['a]`. |\n|`markbarSectionSpecialLocalMark` | `Type`                  | The quote and symbol in, e.g. `['^]`. |\n|`markbarSectionNumberedMark`     | `Special`               | The quote and number in, e.g. `['5]`. |\n|`markbarSectionUppercaseMark`    | `Underlined`            | The quote and letter in, e.g. `['A]`. |\n|`markbarSectionName`             | `Title`                 | The text following the colon in, e.g. `['A]:    Section Name Here`\n|`markbarContext`                 | `NormalNC`              | The lines below the section headings, plucked from around the mark's actual location.\n|`markbarContextEndOfBuffer`      | `EndOfBuffer`           | The `~` character that appears when a mark's context is cut off by the top  or bottom of its parent file.\n|`markbarContextMarkHighlight`    | `TermCursor`            | Highlighting used to show a mark's location in its context.\n\nThese can be customized by linking them to other preexisting highlight groups\n(as is done by default), or by explicitly defining a colorscheme for the\nhighlight group to use.\n\n```vim\n\" 'reusing' an existing highlight group\nhi link markbarContext String\n\n\" explicitly defining which colors to use, see `:h highlight-args` for details\nhi markbarSectionNumberedMark cterm=bold ctermfg=green gui=bold guifg=green\n```\n\nContribution\n--------------------------------------------------------------------------------\nIf you encounter bugs while using vim-markbar, or if you think of features that\nyou would like to see in later versions, please feel free to report them on the\nrepository's [issues page](https://github.com/Yilin-Yang/vim-markbar/issues).\n\nIf you'd like to try your hand at patching bugs or writing features yourself,\nyou're also free to fork the repository and to submit pull requests. If you do,\nmake sure that your code passes the existing [vader.vim](https://github.com/junegunn/vader.vim)\ntest suite, and make sure to write new tests as is appropriate.\n\nSee the [test README](test/README.md).\n\nIf you're fixing a bug, try to replicate the bug (using the old, \"broken\" code)\nin a test case. If you're adding a new feature, try to write unit tests for the\nnew feature.\n\nLicense\n--------------------------------------------------------------------------------\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FYilin-Yang%2Fvim-markbar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FYilin-Yang%2Fvim-markbar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FYilin-Yang%2Fvim-markbar/lists"}