qmk.nvim

qmk.nvim is a 100% lua plugin for Neovim that formats QMK and ZMK keymaps, used in a large number of mechanical and hobbyist keyboards.

Features

• automatically align your keymaps
• create a comment string of your keymap
• use inline JSON comments to make quick easy changes
• supports QMK and ZMK* (though I highly recommend keymap-editor)
  • note any preprocessor macros must start with _ if they are to be identified as the start of a key, e.g

    #define _AS(keycode) &as LS(keycode) keycode
    // ...etc
    default_layer {
    &kp TAB        _AS(Q) SOME_OTHER
    }

  • ZMK is still experiemental, please report any bugs

For a simple example of the following keymap

const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
  [_QWERTY] = LAYOUT_preonic_grid(
  KC_1 ,      K2,
      K3 , K4,     // notice the white space
    KC_5  , HERE_BE_A_LONG_KEY // and how this doesn't line up at all
  )
};

Setup your layout:

local qmk = require 'qmk'
qmk.setup {
    name = 'LAYOUT_preonic_grid', -- identify your layout name
    comment_preview = {
        keymap_overrides = {
            HERE_BE_A_LONG_KEY = 'Magic', -- replace any long key codes
        },
    },
    layout = { -- create a visual representation of your final layout
        'x ^xx', -- including keys that span multple rows (with alignment left, center or right)
        '_ x x', -- pad empty cells
        '_ x x',
    },
}

Save the file and it will automaticlly be nicely aligned, with a pretty comment string

const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
//    ┌───┬────────────┐
//    │ 1 │     K2     │
//    └───┼────┬───────┤
//        │ K3 │  K4   │
//        ├────┼───────┤
//        │ 5  │ Magic │
//        └────┴───────┘
[_QWERTY] = LAYOUT_preonic_grid(
  KC_1 , K2                       ,
         K3   , K4                ,
         KC_5 , HERE_BE_A_LONG_KEY
)
};

Requirements

• Neovim >= 0.10
• QMK: Treesitter c parser available (e.g through nvim-treesitter)
• ZMK: Treesitter devicetree parser available (e.g through nvim-treesitter)
  • this can be used for .keymap files with set ft=dts

Installation

• install with your favourite package manager, e.g packer
• call setup with your layout name and your layout configuration

e.g:

use {
    'codethread/qmk.nvim',
    config = function()
        ---@type qmk.UserConfig
        local conf = {
            name = 'LAYOUT_preonic_grid',
            layout = {
                '_ x x x x x x _ x x x x x x',
                '_ x x x x x x _ x x x x x x',
                '_ x x x x x x _ x x x x x x',
                '_ x x x x x x _ x x x x x x',
                '_ x x x x x x _ x x x x x x',
            }
        }
        require('qmk').setup(conf)
    end
}

Configuration

qmk.nvim takes the following configuration (---@type qmk.UserConfig):

examples

Here are some example configurations:

Layout

The layout config describes your layout as expected by qmk_firmware. As qmk_firmware is simply expecting an array of key codes, the layout is pretty much up to you.

A layout is a list of strings, where each string in the list represents a single row. Rows must all be the same width, and you'll see they visually align to what your keymap looks like.

Valid keys are

• x: indicates presence of key
• : space used to separate keys (must be used, and only use single spaces)
• _: indicates an empty space (e.g to split left and right, or adding padding)
• x^x: a key spanning multiple slots on the keyboard, the ^ indicates alignment. (NOTE vertically sized keys, like some thumb clusters are net yet supported)
  • ^xx: left align across two columns
  • x^x: center align
  • xx^: right align
  • xx^xx: center align but across three columns

examples

_there is also a test file with a great many examples_

Usage

Commands

• QMKFormat: format the current buffer

lua

• :lua require('qmk').setup( <config> ): setup qmk using your config (must be called before format, can be called repeatedly)
• :lua require('qmk').format( <buf id ?> ): format a given buffer, or the current if is not provided

Autocommands

• A BufWritePre autocmd will format buffers on save matching config.auto_format_pattern (defaults to *keymap.c, set to nil to disable)

Debugging

Getting your layout right may be a slightly iterative process, so I recommend the following:

• open a scratch buffer next to your keymap.c file
• get the buffer id of your keymap.c file with :lua print(vim.api.nvim_get_current_buf())
• in your scratch buffer, call qmk.setup { .. your config } and qmk.format(<buf id>)
• from within your scratch buffer evaluate with luafile %

e.g:

-- scratch buffer (:enew)
local qmk = require('qmk')
qmk.setup({
    name = 'Some_layout',
    layout = { 'x x' },
    comment_preview = {
        position = 'inside'
    },
})

qmk.format(43) -- the result of calling :lua print(vim.api.nvim_get_current_buf()) in my keymap.c file

Errors:

I have tried to create useful errors when something is wrong with the config, layout or your current keymap, but please raise an issue if something isn't clear (or you get an QMK: E00, as that's definitely on me).

Thanks

• go-qmk-keymap: this looks cool but still alpha.
• this excellent nvim intro by TJ DeVries on how to use a powerful set of neovim's builtin features (which inspired and taught me how to make this).