QMK keyboard layouts written in Markdown, see example.
This is a work-in-progress prototype I'm experimenting with to find an easier way to represent QMK keyboard layout.
A keyboard layout will be represented by a markdown file with multiple types of code blocks:
-
Structure - defines the structure of the grid (the way it is structured in the keymap.c file). e.g.
```structure 37 38 39 40 41 42 || 43 44 45 46 47 48 49 1 2 3 4 5 || 6 7 8 9 10 50 51 11 12 13 14 15 || 16 17 18 19 20 52 53 21 22 23 24 25 54 || 55 26 27 28 29 30 56 31 32 33 || 34 35 36 ```
This block has to be perfectly indented, each cell is exactly 3 characters (2 for the key index + space). For split keyboards we add
||
between the halfs. -
Layout - defines each layout in the keyboard, basically a shorter, easier-to-read representation of a call to
LAYOUT()
in QMK. e.g.```layer:base esc 1 2 3 4 5 || 6 7 8 9 0 bs tab q w e r t || y u i o p \ lgui lctl/a lalt/s lgui/d l(f)/f g || h l(j)/j rgui/k ralt/l rctl/; ' lsft z x c l(v)/v b home || end n m , . / rsft lctl osm(lgui) spc || osm(rsft) ent bs ```
-
Aliases - to keep the layer short you can create aliases, e.g.
```aliases # Previous tab tabp = g+s+[ # Next tab tabn = g+s+] ```
You can also enter QMK strings directly:
```aliases # Previous tab tabp = LGUI(S(KC_LBRC)) # Next tab tabn = LGUI(S(KC_RBRC)) ```
Instead of using QMK KC_* we use a shorter format (haven't decided on all of them yet).
For now the easiest way to install it is to clone the repo and add the bin
subdirectory to your path, e.g.
git clone https://github.com/elentok/qmkmd ~/.qmkmd
echo 'PATH=$PATH:~/.qmkmd' >> ~/.zshrc
(change to .bashrc
if you're using bash)
To build a markdown file into a header file you can import in keymap.c run:
qmkmd build layout.md
It will create generated-layout.h
which you can then import into your keymap.c
using:
#include "generated-layout.h"
If your keyboard layout uses another function other than LAYOUT
you can
override it in the options
block:
```options
layoutFn = MY_LAYOUT
```
To automatically align the layer columns in the layout.md file:
qmkmd format layout.md
If you're using Neovim you can use my format-on-save plugin to format the file whenever you save, e.g.
local function markdown_kb_layout_formatter()
if vim.fn.expand("%:t"):match("layout.md") then
return formatters.shell({ cmd = { "qmkmd", "format", "%" }, tempfile = "random" })
end
end
format_on_save.setup({
formatter_by_ft = vim.tbl_extend("force", {
markdown = {
formatters.prettierd,
markdown_kb_layout_formatter,
},
},
})