Skip to content

User Keybinds

github-actions[bot] edited this page Jun 25, 2022 · 118 revisions
Clone this wiki locally

The Keybinds Module

Module for managing keybindings with Neorg mode support.


Disabling Default Keybinds

By default when you load the core.keybinds module all keybinds will be enabled. If you want to change this, be sure to set default_keybinds to false:

["core.keybinds"] = {
    config = {
        default_keybinds = false,

Setting Up a Keybind Hook

Want to change some keybinds? You can set up a function that will allow you to tweak every keybind bit by bit.

["core.keybinds"] = {
    config = {
        hook = function(keybinds)
            -- Unmaps any Neorg key from the `norg` mode
            keybinds.unmap("norg", "n", "gtd")

            -- Binds the `gtd` key in `norg` mode to execute `:echo 'Hello'`
  "norg", "n", "gtd", "<cmd>echo 'Hello!'<CR>")

            -- Remap unbinds the current key then rebinds it to have a different action
            -- associated with it.
            -- The following is the equivalent of the `unmap` and `map` calls you saw above:
            keybinds.remap("norg", "n", "gtd", "<cmd>echo 'Hello!'<CR>")

            -- Sometimes you may simply want to rebind the Neorg action something is bound to
            -- versus remapping the entire keybind. This remap is essentially the same as if you
            -- did `keybinds.remap("norg", "n", "<C-Space>, "<cmd>Neorg keybind norg core.norg.qol.todo_items.todo.task_done<CR>")
            keybinds.remap_event("norg", "n", "<C-Space>", "core.norg.qol.todo_items.todo.task_done")

            -- Want to move one keybind into the other? `remap_key` moves the data of the
            -- first keybind to the second keybind, then unbinds the first keybind.
            keybinds.remap_key("norg", "n", "<C-Space>", "<Leader>t")


How to Apply

  • This module is already present in the core.defaults metamodule. You can load the module with:
    ["core.defaults"] = {},
    In your Neorg setup.
  • To manually load the module, place this code in your Neorg setup:
    ["core.keybinds"] = {
       config = { -- Note that this table is optional and doesn't need to be provided
           -- Configuration here
    Consult the configuration section to see how you can configure core.keybinds to your liking.


default_keybinds : Use the default keybinds provided in

Default value: true

neorg_leader : Prefix for some Neorg keybinds

Default value: "<LocalLeader>"

hook : Function to be invoked that allows the user to change their keybinds

Default value: nil

keybind_preset : The keybind preset to use

Default value: "neorg"

keybind_presets : An array of functions, each one corresponding to a separate preset

Default Value:

Developer Usage

Public API

This segment will detail all of the functions core.keybinds exposes. All of these functions reside in the public table.

  • request_keys
  • bind_all
  • register_keybind
  • sync
  • register_keybinds


Create keybinds in your module

-- The process of defining a keybind is only a tiny bit more involved than defining e.g. an autocommand. Let's see what differs in creating a keybind rather than creating an autocommand:

Attach some keys to the create keybind

-- To invoke a keybind, we can then use :Neorg keybind norg test.module.my_keybind.

Extra Info


This module supports at least version 0.0.9. The current Neorg version is 0.0.11.



  • core.neorgcmd - This module deals with handling everything related to the :Neorg command.
  • core.mode - Modes are a way of isolating different parts of Neorg based on the current mode.
  • core.autocommands - Handles the creation and management of Neovim's autocommands.

Required by