The goal of the QMK software project is to develop a completely customizable, powerful, and enjoyable firmware experience for any project - keyboard or otherwise - and to provide helpful, encouraging, and kind support and feedback for people with any software development experience.
This project is maintained by QMK collaborators and contributors like you!
Hosted on GitHub Pages — Theme by orderedlist
Language:With the merging of #1609, we’ve added the layouts/
folder - it contains collections of keymaps sorted by physical key layouts that different keyboards can use, and is organised like this:
layouts/
+ default/
| + 60_ansi/
| | + readme.md
| | + layout.json
| | + a_good_keymap/
| | | + keymap.c
| | | + readme.md
| | | + config.h
| | | + rules.mk
| | + <keymap folder>/
| | + ...
| + <layout folder>/
+ community/
| + <layout folder>/
| + ...
The layouts/default/
and layouts/community/
are two examples of layout “repositories” - currently default
will contain all of the information concerning the layout, and one default keymap named default_<layout>
, for users to use as a reference. community
contains all of the community keymaps, with the eventual goal of being split-off into a separate repo for users to clone into layouts/
. QMK searches through all folders in layouts/
, so it’s possible to have multiple reposistories here.
Each layout folder is named ([a-z0-9_]
) after the physical aspects of the layout, in the most generic way possible, and contains a readme.md
with the layout to be defined by the keyboard:
# 60_ansi
LAYOUT_60_ansi
New names should try to stick to the standards set by existing layouts, and can be discussed in the PR/Issue.
For a keyboard to support a layout, the variable ([a-z0-9_]
) must be defined in it’s <keyboard>.h
, and match the number of arguments/keys (and preferrably the physical layout):
#define LAYOUT_60_ansi KEYMAP_ANSI
The folder name must be added to the keyboard’s rules.mk
:
LAYOUTS = 60_ansi
LAYOUTS
can be appended in the subproject’s rules.mk
:
LAYOUTS += 60_iso
but the LAYOUT_<layout>
variable must be defined in <subproject>.h
as well.
Instead of using #include "planck.h"
, you can use this line to include whatever <keyboard>.h
file that is being compiled:
#include QMK_KEYBOARD_H
In your config.h, you can also use this variable to include the keyboard’s This is no longer needed, as the config.h files are included automatically.config.h
:
If you want to keep some keyboard-specific code, you can use these variables to escape it with an #ifdef
statement:
KEYBOARD_<keyboard_folder1>_<keyboard_folder2>
For example:
#ifdef KEYBOARD_planck
#ifdef KEYBOARD_planck_rev4
planck_rev4_function();
#endif
#endif
Note that the names are lowercase and match the folder/file names for the keyboard/revision exactly.