{"id":21071870,"url":"https://github.com/iron-e/nvim-cartographer","last_synced_at":"2025-09-11T00:33:46.486Z","repository":{"id":44611738,"uuid":"383562059","full_name":"Iron-E/nvim-cartographer","owner":"Iron-E","description":"Create Neovim `:map`pings in Lua with ease!","archived":false,"fork":false,"pushed_at":"2023-06-19T14:56:48.000Z","size":37,"stargazers_count":55,"open_issues_count":0,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-07-31T20:51:28.005Z","etag":null,"topics":["keybindings","keymap","lua","mapping","neovim","neovim-configuration","neovim-plugin","plugin"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Iron-E.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}},"created_at":"2021-07-06T18:19:58.000Z","updated_at":"2024-07-01T06:09:49.000Z","dependencies_parsed_at":"2024-01-07T12:05:00.671Z","dependency_job_id":null,"html_url":"https://github.com/Iron-E/nvim-cartographer","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Iron-E%2Fnvim-cartographer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Iron-E%2Fnvim-cartographer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Iron-E%2Fnvim-cartographer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Iron-E%2Fnvim-cartographer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Iron-E","download_url":"https://codeload.github.com/Iron-E/nvim-cartographer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254474478,"owners_count":22077292,"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":["keybindings","keymap","lua","mapping","neovim","neovim-configuration","neovim-plugin","plugin"],"created_at":"2024-11-19T18:54:28.649Z","updated_at":"2025-05-16T05:32:04.659Z","avatar_url":"https://github.com/Iron-E.png","language":"Lua","readme":"# nvim-cartographer\n\nThis is a plugin for Neovim which aims to simplify setting and deleting with keybindings / mappings in Lua The target audience is users who are trying to port from an `init.vim` to an `init.lua` following the release of Neovim 0.5.\n\nHere is an example:\n\n```lua\n-- This is how you map with the Neovim API\nvim.api.nvim_set_keymap('n', 'gr', '\u003cCmd\u003elua vim.lsp.buf.references()\u003cCR\u003e', {noremap=true, silent=true})\n\n-- This is how you do that with `nvim-cartographer`\nmap.n.nore.silent['gr'] = '\u003cCmd\u003elua vim.lsp.buf.references()\u003cCR\u003e'\n```\n\n## Installation\n\nThis plugin can be installed with any plugin manager and used with Neovim 0.7+. I use [packer.nvim](https://github.com/wbthomason/packer.nvim):\n\n```lua\nlocal fn = vim.fn\n\nlocal install_path = fn.stdpath('data')..'/site/pack/packer/opt/packer.nvim'\n\nif not vim.loop.fs_stat(fn.glob(install_path)) then\n\tos.execute('git clone https://github.com/wbthomason/packer.nvim '..install_path)\nend\n\nvim.api.nvim_command 'packadd packer.nvim'\n\nreturn require('packer').startup {function(use)\n\tuse {'wbthomason/packer.nvim', opt=true}\n\tuse 'Iron-E/nvim-cartographer'\nend}\n```\n\n## Usage\n\nTo import this plugin, add the following line to the top of any file you wish to use this plugin in:\n\n```lua\nlocal map = require 'cartographer'\n```\n\nThis plugin implements a builder to make toggling options as easy as possible. You may specify zero to one of `nvim_set_keymap`'s `mode` argument (i.e. you can `map.x` or `map`). It also supports all of the `:h :map-arguments`. `nore` is used to perform a non-recursive `:map`. The ordering of arguments is not important:\n\n```lua\nassert(vim.deep_equal(map.n.nore.silent.unique, map.silent.n.unique.nore))\n```\n\nHere is an example:\n\n```lua\n-- `:map` 'gt' in normal mode to searching for symbol references with the LSP\nmap.n.nore.silent.unique['gr'] = '\u003cCmd\u003elua vim.lsp.buf.references()\u003cCR\u003e'\n```\n\nThe above is equivalent to the following VimL:\n\n```vim\n\" This is how you bind `gr` to the builtin LSP symbol-references command\nnnoremap \u003csilent\u003e\u003cunique\u003e gr \u003cCmd\u003elua vim.lsp.buf.references()\u003cCR\u003e\n```\n\n### Buffer-Local Mapping\n\nYou can create mappings for specific buffers:\n\n```lua\nlocal nnoremap = require('cartographer').n.nore.silent\n\n-- Only buffer sets map to current buffer\nnnoremap.buffer['gr'] = '\u003cCmd\u003elua vim.lsp.buf.references()\u003cCR\u003e'\n\n-- You can specify bufnr like \u003cbufer=n\u003e\n-- This keymap will be set for buffer 3\nnnoremap.buffer3['gr'] = '\u003cCmd\u003elua vim.lsp.buf.references()\u003cCR\u003e'\n```\n\n### Hooks\n\nYou can register a function to be called when mapping or unmapping. This function has the same parameters as `nvim_buf_set_keymap`.\n\n```lua\nlocal map = require 'cartographer'\nmap:hook(function(buffer, mode, lhs, rhs, opts)\n\t-- setup which-key, etc\n\tprint(vim.inspect(lhs)..' was mapped to '..vim.inspect(rhs))\nend)\nmap['zxpp'] = vim.lsp.buf.definition\n```\n\nThe `buffer` parameter will be `nil` when the mapping is not [buffer-local](#buffer-local-mapping).\n\n### Lua Functions\n\nYou can also register `local` lua `function`s to mappings, rather than attempt to navigate `v:lua`/`luaeval` bindings:\n\n```lua\nlocal map = require 'cartographer'\n\nlocal function float_term()\n\tlocal buffer = vim.api.nvim_create_buf(false, true)\n\tlocal window = vim.api.nvim_open_win(buffer, true,\n\t{\n\t\trelative = 'cursor',\n\t\theight = math.floor(vim.go.lines / 2),\n\t\twidth = math.floor(vim.go.columns / 2),\n\t\tcol = 0,\n\t\trow = 0,\n\t})\n\tvim.api.nvim_command 'terminal'\nend\n\nmap.n.nore.silent['\u003cTab\u003e'] = float_term\n```\n\n### Multiple Modes\n\nYou can `:map` to multiple `mode`s if necessary.\n\n```lua\n-- Map `gr` to LSP symbol references in 'x' and 'n' modes.\nmap.n.x.nore.expr['\u003cTab\u003e'] = 'pumvisible() ? \"\\\\\u003cC-n\u003e\" : check_backspace() ? \"\\\\\u003cTab\u003e\" : compe#complete()'\n```\n\n### Unmapping\n\nYou can `:unmap` as well by setting a `\u003clhs\u003e` to `nil` instead of any `\u003crhs\u003e`:\n\n```lua\n-- `:unmap` 'zfo' in `x` mode\nmap.x['zfo'] = nil\n```\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Firon-e%2Fnvim-cartographer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Firon-e%2Fnvim-cartographer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Firon-e%2Fnvim-cartographer/lists"}