This repository contains community-maintained data. Currently that means layouts for keyboards where layout data cannot be generated, or refinements where the autogenerated layouts were insufficient.
All of these layouts are meant for use with Keymap Editor, but the layout data
conforms to QMK's info.json schema (with some custom additions) so it can be
used with other tools.
If you're loading your keymap(s) from the:
- GitHub integration: if the file you want to use matches the name of your
keyboard (i.e.
<keyboard>.jsonand<keyboard>.keymap, notmy_<keyboard>.keymapor<keyboard>_v2.keymap) it should be picked up automatically by the app. If that is not the case you can copy the relevant file into your repository'sconfig/folder. - Clipboard integration: all of these keyboards should have their metadata listed already in the New Keyboard dialog. If you need a customized version, or if I just haven't updated the app, copy the contents of the relevant JSON file and paste it into the metadata field when selecting Custom in the new keyboard dialog.
- Filesystem integration: similar to the clipboard integration, except if you need to use custom metadata then open an issue on the Keymap Editor repo, because at the time of this writing I still haven't gotten around to adding that. Letting me know that this matters is a great way to encourage me.
You can hand-edit the JSON files if you're familiar with the format. I've also written about it in Keymap Editor Wiki: Defining Keyboard Layouts.
I've been putting together tooling to render/manipulate/import layout data to try and remove some of the hurdles.
Often the best way is to start by importing layout data from a Kicad PCB file if you have that available, or from a ZMK keyboard DTS, or from a Keyboard Layout Editor export in the worst case.
There would still probably be some manual tweaks to make from this point, but if you want some help why not make an issue or draft pull request on this repo? I have been through a lot of this and can help you through the process.
I'm happy to include customizations. I mainly use a handwired custom Dactyl so there are an endless number of keyboards I don't recognize and wouldn't be able to validate layout data for.
Some guidelines:
- focus on supporting common/widely available layouts: it's not so important that the keyboard be mass-produced or even a PCB, but it gets more complicated when looking at keyboards like the Dactyl and Dactyl-manuform where much of the point is customizability. I may organize things into incomplete layout "templates" that offer a simpler starting point.
- focus on ZMK compatibility: when a keyboard definition already exists in the ZMK main repository, make sure that the layout matches it. If multiple matrix transformations exist, the metadata should provide multiple layouts keyed to those matrix transform labels.
- keymap editor compatibility: this layout data is used to format key bindings
in the ZMK devicetree code as well as to render it in the browser. This means
the layout data should include proper
rowandcolproperties.