zmk/docs/docs/customization.md

title	sidebar_label
Customizing ZMK/`zmk-config` folders	Customizing ZMK

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

After verifying you can successfully flash the default firmware, you will probably want to begin customizing your keymap and other keyboard options. In the initial setup tutorial, you created a Github repository called zmk-config. This repository is a discrete filesystem which works with the main zmk firmware repository to build your desired firmware. The main advantage of a discrete configuration folder is ensuring that the working components of ZMK are kept separate from your personal keyboard settings, reducing the amount of file manipulation in the configuration process. This makes flashing ZMK to your keyboard much easier, especially because you don't need to keep an up-to-date copy of zmk on your computer at all times.

On default zmk-config folder should contain two files:

• <shield>.conf
• <shield>.keymap

However, your config folder can also be modified to include a boards/ directory for keymaps and configurations for multiple boards/shields outside of the default keyboard setting definitions.

Configuration Changes

The setup script creates a config/<shield>.conf file that allows you to add additional configuration options to control what features and options are built into your firmware. Opening that file with your text editor will allow you to see the various config settings that can be commented/uncommented to modify how your firmware is built.

Keymap

Once you have the basic user config completed, you can find the keymap file in config/<shield>.keymap and customize from there. Refer to the Keymap documentation to learn more.

Testing features

Testing features will require you to modify the west.yml file. You will need to add a new remote for the pull request you would like to test, and change the selected remote and revision for the zmk project.

<Tabs defaultValue="zmk" values={[ {label: 'Default', value: 'zmk'}, {label: 'PR685: Macros', value: 'macros'}, {label: 'PR649: Add &sleep behavior', value: 'sleep'}, ]}>

manifest:
  remotes:
    - name: zmkfirmware
      url-base: https://github.com/zmkfirmware
  projects:
    - name: zmk
      remote: zmkfirmware
      revision: main
      import: app/west.yml
  self:
    path: config

manifest:
  remotes:
    - name: zmkfirmware
      url-base: https://github.com/zmkfirmware
    - name: okke-formsma
      url-base: https://github.com/okke-formsma
  projects:
    - name: zmk
      remote: okke-formsma
      revision: macros
      import: app/west.yml
  self:
    path: config

manifest:
  remotes:
    - name: zmkfirmware
      url-base: https://github.com/zmkfirmware
    - name: mcrosson
      url-base: https://github.com/mcrosson
  projects:
    - name: zmk
      remote: mcrosson
      revision: feat-behavior-sleep
      import: app/west.yml
  self:
    path: config

Publishing

After making any changes you want, you should commit the changes and then push them to GitHub. That will trigger a new GitHub Actions job to build your firmware which you can download once it completes.

:::note If you need to, a review of Learn The Basics Of Git In Under 10 Minutes will help you get these steps right. :::

Building from a local zmk fork using zmk-config

As outlined here, firmware comes in the form of .uf2 files, which can be built locally using the command west build. Normally, west build will default to using the in-tree .keymap and .conf files found in your local copy of the zmk repository. However, you can append the command, -DZMK_CONFIG="C:/the/absolute/path/config" to west build in order to use the contents of your zmk-config folder instead of the default keyboard settings. Notice that this path should point to the folder labelled config within your zmk-config folder.

For instance, building kyria firmware from a user myUser's zmk-config folder on Windows 10 may look something like this:

west build -b nice_nano -- -DSHIELD=kyria_left -DZMK_CONFIG="C:/Users/myUser/Documents/Github/zmk-config/config"

Flashing Your Changes

For normal keyboards, follow the same flashing instructions as before to flash your updated firmware.

For split keyboards, only the central (left) side will need to be reflashed if you are just updating your keymap. More troubleshooting information for split keyboards can be found here.