{"id":28547074,"url":"https://github.com/skywind3000/vim-navigator","last_synced_at":"2025-07-07T07:31:41.580Z","repository":{"id":176699585,"uuid":"659271083","full_name":"skywind3000/vim-navigator","owner":"skywind3000","description":":rocket: Navigate Your Commands Easily !!","archived":false,"fork":false,"pushed_at":"2024-06-21T03:21:41.000Z","size":134,"stargazers_count":33,"open_issues_count":2,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-06-10T00:09:07.462Z","etag":null,"topics":["gui","navigator","neovim","neovim-plugin","neovim-plugins","productivity","quickui","terminal","tui","user-interface","vim","vim-navigator","vim-plugin","vim-plugins","vim-quickui","vim-whichkey","whichkey"],"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/skywind3000.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":"2023-06-27T13:31:46.000Z","updated_at":"2025-02-08T05:35:09.000Z","dependencies_parsed_at":"2024-02-23T09:30:04.686Z","dependency_job_id":"fc7e5679-1ab8-4b28-8294-c2d0a3f0e92b","html_url":"https://github.com/skywind3000/vim-navigator","commit_stats":null,"previous_names":["skywind3000/vim-navigator","skywind3000/vim-quickui-navigator"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/skywind3000/vim-navigator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skywind3000%2Fvim-navigator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skywind3000%2Fvim-navigator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skywind3000%2Fvim-navigator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skywind3000%2Fvim-navigator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/skywind3000","download_url":"https://codeload.github.com/skywind3000/vim-navigator/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skywind3000%2Fvim-navigator/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264034499,"owners_count":23547220,"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":["gui","navigator","neovim","neovim-plugin","neovim-plugins","productivity","quickui","terminal","tui","user-interface","vim","vim-navigator","vim-plugin","vim-plugins","vim-quickui","vim-whichkey","whichkey"],"created_at":"2025-06-10T00:09:15.545Z","updated_at":"2025-07-07T07:31:41.567Z","avatar_url":"https://github.com/skywind3000.png","language":"Vim Script","readme":"# What is it ?\n\n![](https://skywind3000.github.io/images/p/misc/2023/vim-menu2.png)\n\nVim has got several **whichkey** like plugins for keymap hints and I've tried each of them one by one and found them always lacking in some way. As a result, I've made the decision to create my own plugin, which is similar to whichkey but with some exciting enhancements.\n\n## Features\n\n- Better layout: each column can have different width. Columns with short texts will not occupy a lot of space.\n- Fully customizable: separator style and visibility, bracket (around key character) visibility, spacing, padding, highlighting, and position.\n- Zero timeout mode and adaptive window size.\n- Buffer local keymaps for different file types.\n- Unambiguity syntax to define a command or key sequence.\n- Runtime keymap generation, items can be decided at runtime.\n- Can use popup for vim 8.2+ and floatwin for nvim 0.6.0+\n- Legacy Vim compatibility (only requires Vim 7.4.2364).\n\n## Installation\n\n```VimL\nPlug 'skywind3000/vim-quickui'\nPlug 'skywind3000/vim-navigator'\n```\n\n[vim-quickui](https://github.com/skywind3000/vim-quickui) is required, because it provides unified API to access popup in Vim and floatwin in NVim.\n\n## Quick start\n\nPut this in you `.vimrc`:\n\n```VimL\n\" initialize global keymap and declare prefix key\nlet g:navigator = {'prefix':'\u003ctab\u003e\u003ctab\u003e'}\n\n\" buffer management\nlet g:navigator.b = {\n            \\ 'name' : '+buffer' ,\n            \\ '1' : [':b1'        , 'buffer 1']        ,\n            \\ '2' : [':b2'        , 'buffer 2']        ,\n            \\ 'd' : [':bd'        , 'delete-buffer']   ,\n            \\ 'f' : [':bfirst'    , 'first-buffer']    ,\n            \\ 'h' : [':Startify'  , 'home-buffer']     ,\n            \\ 'l' : [':blast'     , 'last-buffer']     ,\n            \\ 'n' : [':bnext'     , 'next-buffer']     ,\n            \\ 'p' : [':bprevious' , 'previous-buffer'] ,\n            \\ '?' : [':Leaderf buffer'   , 'fzf-buffer']      ,\n            \\ }\n\n\" tab management\nlet g:navigator.t = {\n            \\ 'name': '+tab',\n            \\ '1' : ['\u003ckey\u003e1gt', 'tab-1'],\n            \\ '2' : ['\u003ckey\u003e2gt', 'tab-2'],\n            \\ '3' : ['\u003ckey\u003e3gt', 'tab-3'],\n            \\ 'c' : [':tabnew', 'new-tab'],\n            \\ 'q' : [':tabclose', 'close-current-tab'],\n            \\ 'n' : [':tabnext', 'next-tab'],\n            \\ 'p' : [':tabprev', 'previous-tab'],\n            \\ 'o' : [':tabonly', 'close-all-other-tabs'],\n            \\ }\n\n\" Easymotion\nlet g:navigator.m = ['\u003cplug\u003e(easymotion-bd-w)', 'easy-motion-bd-w']\nlet g:navigator.n = ['\u003cplug\u003e(easymotion-s)', 'easy-motion-s']\n```\n\nBy default, I prefer not to use leader key timeout method to trigger Navigator. Let's assign a dedicated key, hit `\u003ctab\u003e` twice:\n\n```VimL\nnnoremap \u003csilent\u003e\u003ctab\u003e\u003ctab\u003e :Navigator g:navigator\u003ccr\u003e\n```\n\nCommand `:Navigator` will find the following variable `g:navigator` and read its keymap configuration.\n\nRestart your vim and hit `\u003ctab\u003e` twice, you may see the Navigator window in the screen bottom:\n\n![](https://skywind3000.github.io/images/p/misc/2023/vim-menu5.png)\n\nAll the items defined previously will be listed in the navigator window, you can press a key to execute its command, enter a sub-group, or press ESC to quit without performing any action.\n\n## Commands\n\nDefault command:\n\n```VimL\n:Navigator {varname}\n```\n\nThis command will open navigator window and read keymap from `{varname}`. So, if you have your navigator keymap in the variable `g:my_keymap`, the command `:Navigator g:my_keymap` will read keymap from it.\n\nVisual mode command:\n\n```VimL\n:NavigatorVisual {varname}\n```\n\nSame as `:Navigator` command but dedicated for visual mode, and can be used with `vmap` or `vnoremap`:\n\n```VimL\nvnoremap \u003csilent\u003e\u003ctab\u003e\u003ctab\u003e :NavigatorVisual g:keymap_visual\u003ccr\u003e\n```\n\nThe `{varname}` in both `:Navigator` and `:NavigatorVisual` is a standard VimScript variable name with a slight extension: if the `{varname}` starts with a star and a colon (`*:`), navigator will search for the variable name in both the global scope (`g:`) and the buffer local scope (`b:`).\n\n\n## Buffer local keymaps\n\nJust define a `b:navigator` variable for certain buffer:\n\n```VimL\nlet g:_navigator_cpp = {...}\nlet g:_navigator_python = {...}\n\nautocmd FileType c,cpp let b:navigator = g:_navigator_cpp\nautocmd FileType python let b:navigator = g:_navigator_python\n```\n\nAnd run `:Navigator` command and replace the original varname `g:navigator` with `*:navigator`\n\n```VimL\nnnoremap \u003csilent\u003e\u003ctab\u003e\u003ctab\u003e :Navigator *:navigator\u003ccr\u003e\n```\n\nDifferent from the previous command, here we have a `*:` before the variable name. After that `:Navigator` will find variables named `navigator` in both global scope and buffer local scope (`g:navigator` and `b:navigator`) and evaluate them, then merge the result into one dictionary.\n\n\n## Keybinding\n\nOnce Navigator window is open,\n\n![](https://skywind3000.github.io/images/p/misc/2023/vim-menu3.png)\n\nit accepts these keybinding:\n\n| Key | Action |\n|-|-|\n| `\u003cc-j\u003e` | next page |\n| `\u003cc-k\u003e` | previous page |\n| `\u003cPageDown\u003e` | next page |\n| `\u003cPageUp\u003e` | previous page |\n| `\u003cbs\u003e` | return to parent level |\n| `\u003cesc\u003e` | exit navigator |\n\nIf there are too many items cannot be displayed in one window, they will be splited into different pages. From the left bottom corner, you will see:\n\n    (page 1/1)\n\nIt represents the total page number and current page index. \n\n\n## Configuration\n\nInitialize an empty keymap configuration:\n\n```vimL\nlet g:keymap = {'prefix': \"\u003cspace\u003e\"}\n```\n\nYou can describe the prefix keys like this, but it is optional.\n\nAfter that you can defined an item:\n\n```VimL\nlet g:keymap.o = [':tabonly', 'close-other-tabpage']\n```\n\nEach item is a list of command and description, where the first element represents the command. For convenience, the command has several forms:\n\n| Prefix | Meaning | Sample |\n|-|-|-|\n| `:` | Ex command | `:wincmd p` |\n| `\u003ckey\u003e` | Key sequence | `\u003ckey\u003e\u003cc-w\u003ep` (this will feed `\u003cc-w\u003ep` to vim) |\n| `\u003cKEY\u003e` | Key sequence | `\u003ckey\u003e\u003cc-w\u003ep` (feed `\u003cc-w\u003ep` without remap) |\n| `^[a-zA-Z0-9_#]\\+(.*)$` | Function call | `MyFunction()` |\n| `\u003cplug\u003e` | Plug trigger | `\u003cplug\u003e(easymotion-bd-w)` |\n\nA group is a subset to hold items and child groups:\n\n```VimL\nlet g:keymap.w = {\n    \\ 'name': '+window',\n\t\\ 'p': [':wincmd p', 'jump-previous-window'],\n\t\\ 'h': [':wincmd h', 'jump-left-window'],\n\t\\ 'j': [':wincmd j', 'jump-belowing-window'],\n\t\\ 'k': [':wincmd k', 'jump-aboving-window'],\n\t\\ 'l': [':wincmd l', 'jump-right-window'],\n\t\\ 'x': {\n\t\\       'name': '+management',\n\t\\       'o': ['wincmd o', 'close-other-windows'],\n\t\\   },\n\t\\ }\n```\n\nIn the \"Quick start\" section, we defined a `g:navigator` variable to store keymaps and paired with the command:\n\n```VimL\n:Navigator g:navigator\n```\n\nHere we use another variable `g:keymap` so its command will be:\n\n```VimL\n:Navigator g:keymap\n```\n\n## Visual mode\n\nSetup a keymap for visual mode only and use it with `:NavigatorVisual`:\n\n```VimL\nlet g:keymap_visual = {'prefix':'\u003ctab\u003e\u003ctab\u003e'}\nlet g:keymap_visual['='] = ['\u003ckey\u003e=', 'indent-block']\nlet g:keymap_visual.q = ['\u003ckey\u003egq', 'format-block']\n\nvnoremap \u003csilent\u003e\u003ctab\u003e\u003ctab\u003e :NavigatorVisual *:keymap_visual\u003ccr\u003e\n```\n\nWhen you hit `\u003ctab\u003e\u003ctab\u003eq` in visual mode, the `gq` will be feed into vim and the selected text will be formatted.\n\n## Runtime evaluation\n\nConfiguration can be generated at runtime by providing a function name like this:\n\n```VimL\nfunction! GenerateSubKeymap() abort\n    return {\n        \\ 'name': '+coding',\n        \\ 'a': [':echo 1', 'command-a'],\n        \\ 'b': [':echo 2', 'command-b'],\n        \\ 'c': [':echo 3', 'command-c'],                \n        \\ }\nendfunc\n\nlet keymap.c = '%{GenerateSubKeymap()}'\n```\n\nThe function will be called each time before opening Navigator window, it should returns the latest configuration.\n\nThis allows you generate context sensitive keymaps.\n\n## Customize\n\nAvailable options:\n\n| Global | Local | Default Value | Description |\n|-|-|-|-|\n| g:navigator_icon_separator | icon_separator | `'=\u003e'` | separator style, can be set to an empty string |\n| g:navigator_bracket | bracket | `0` | set to 1 to display brackets around key character |\n| g:navigator_spacing | spacing | `3` | horizontal spaces between items |\n| g:navigator_padding | padding | `[2,0,2,0]` | left, top, right, bottom padding to the window edge |.\n| g:navigator_vertical | vertical | `0` | set to 1 to use a vertical split window |\n| g:navigator_position | position | `'botright'` | split position |\n| g:navigator_fallback | fallback | `0` | set to 1 to allow fallback to native keymap if key does not exist |\n| g:navigator_max_height | max_height | `20` | maximum horizontal window height |\n| g:navigator_min_height | min_height | `5` | minimal horizontal window height |\n| g:navigator_max_width | max_width | `60` | maxmum vertical window width |\n| g:navigator_min_width | min_width | `20` | minimal vertical window width |\n| g:navigator_popup | popup | `0` | set to 1 to use popup or floatwin if available |\n| g:navigator_popup_position | popup_position | `'bottom'` | can be set to `'bottom'`, `'top'`, and `'center'` |\n| g:navigator_popup_width | popup_width | `'60%'` | centered popup window width |\n| g:navigator_popup_height | popup_height | `'20%'` | centered popup window height |\n| g:navigator_popup_border | popup_border | `1` | centered popup window border, set to 0 for borderless window, and 2-4 for unicode border |\n| g:navigator_char_display | char_display | `{}` | change display char like `{'\u003cbar\u003e': '\\|', '\u003cbslash\u003e': '\\'}` |\n\nGlobal options can be directly defined like:\n\n```VimL\nlet g:navigator_icon_separator = '→'\n```\n\nLocal options have higher priority than the global options with same name. They can be defined as a `config` member of your keymap dictionary variable:\n\n```VimL\nlet g:my_keymap.config = {\n    \\ 'icon_separator': '→',\n    \\ 'popup': 1,\n    \\ 'popup_position': 'center',\n    \\ 'popup_width': '60%',\n    \\ 'popup_height': '20%',\n    \\ }\n```\n\nThe local settings defined above will override the corresponding global settings when you are using:\n\n```VimL\n:Navigator g:my_keymap\n```\n\nThere can be multiple navigator keymaps existing simultaneously with different window sizes and positions.\n\n\n## TODO\n\n- [ ] Polish documentation.\n- [ ] Vim help file.\n- [ ] Preset keymaps.\n\n\n\n## Credit\n\n- [vim-quickui](https://github.com/skywind3000/vim-quickui)\n- [vim-which-key](https://github.com/liuchengxu/vim-which-key)\n\n\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskywind3000%2Fvim-navigator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fskywind3000%2Fvim-navigator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskywind3000%2Fvim-navigator/lists"}