ZMK: remap with Keymap Editor and GitHub

This is ZMK's universal remapping route: your keymap lives in a .keymap file in your own GitHub repository, GitHub builds the firmware, and you flash it. It unlocks every ZMK feature (combos, macros, home row mods…) and works on keyboards without ZMK Studio.

The whole flow:

Fork config repo → edit in Keymap Editor → Commit → GitHub Actions builds → download firmware.zip → flash

You'll need

• ✅ A GitHub account
• ✅ The zmk-config repository from your keyboard's maker
• ✅ A data-capable USB cable

Step 1: fork the config repo

1. Open the maker's config repository and click Fork to copy it to your account.
2. In your fork, open the Actions tab and enable workflows if asked.

Step 2: edit with Keymap Editor

1. Open Keymap Editor and sign in with GitHub.
2. Choose your fork and branch; the layout loads automatically.
3. Pick a layer and click the position to change.
4. Choose a behavior (&kp key press, &mo momentary layer, &lt layer-tap, &mt mod-tap) and its parameters.
5. Click Save, then Commit to push the change to GitHub.

Or edit the .keymap file directly

Once comfortable, editing .keymap on GitHub is quick. A minimal example:

/ {
    keymap {
        compatible = "zmk,keymap";
        default_layer {
            bindings = <
                &kp Q   &kp W   &kp E
                &mo 1   &kp A   &lt 1 SPACE
            >;
        };
        number_layer {
            bindings = <
                &kp N1  &kp N2  &kp N3
                &trans  &kp N4  &kp N5
            >;
        };
    };
};

Layers are numbered from 0 in the order they appear. Syntax cheat sheet: Layers, keycodes and behaviors.

Step 3: download the firmware

1. After committing, open the Actions tab and wait for the latest build to turn green ✅.
2. Open the run and download firmware.zip under Artifacts; unzip it.

Step 4: flash

1. Put the keyboard in bootloader mode — usually double-tap the reset button, or press a key bound to &bootloader.
2. A USB drive appears (e.g. NICENANO).
3. Drag the matching .uf2 file onto it; the keyboard restarts when the copy finishes.

Details: Flash firmware.

Common problems

• The Actions build failed (red ❌): open the failed run to read the error — usually a .keymap syntax mistake. Revert your last change and commit again.
• No layout in Keymap Editor: make sure you picked your own fork, and it still has the maker's build.yaml and keymap files.
• Keys wrong after flashing: re-enter the bootloader and flash your last known-good firmware.

More → Troubleshooting