Keymap Editor

This community fork adds a first-class, self-hostable Forgejo integration. See FORGEJO.md for OAuth setup and container deployment.

Forgejo fork status

This fork now reads the real ZMK .keymap source instead of treating keymap.json as canonical. Existing and custom bindings such as home-row mods can be edited, while comments, macros, combos, conditional layers, sensors, and unknown future ZMK syntax are preserved. Saves use the loaded file revision and stop on conflicts rather than overwriting newer Forgejo changes.

Repositories without the legacy config/info.json metadata are supported with an approximate layout generated from the default layer's key count.

The Forgejo workspace includes guided sections for keys and layers, combos, macros, custom behaviors (including home-row mods and tap dance), conditional layers, and rotary sensors. It can create safe starter definitions, exposes common settings in plain language, and keeps a validated full-source editor as an escape hatch for ZMK syntax that does not have a visual control yet. Layers can be created, renamed, and deleted without rewriting unrelated nodes.

The key picker is searchable by meaning (for example volume, escape, or arrow), groups common key categories, and displays human-readable names next to ZMK codes. The physical key selector for combos uses the repository layout when matching .json metadata is available.

QMK foundation

Forgejo repositories now have a visible Auto / ZMK / QMK firmware selector and a persisted target picker. QMK discovery supports complete firmware forks, External Userspace layouts, keymap.c, keymap.json, and standalone Configurator exports. Mixed repositories always require an explicit target.

QMK C and JSON documents use one firmware-neutral workspace contract. Visual key and layer edits patch concrete source byte ranges; comments, preprocessor branches, custom macros, callbacks, unknown JSON fields, and formatting outside the edited ranges remain untouched. Ambiguous C automatically becomes source-only instead of risking a rewrite. Optional rules.mk, config.h, and qmk.json files carry sha: null revisions so concurrent creation is detected before one atomic Forgejo commit.

The QMK feature catalog is pinned to revision 9caa5f871ddb9813c7370708be62d7a3e1cfeb75. Every eligible official catalog entry has a UI category, documentation link, adapter, and compatibility rule; hardware-definition-only work is shown as a requirement rather than changing pins, matrices, MCUs, bootloaders, or drivers.

Set ENABLE_QMK=false to remove QMK discovery, workspace mutation, workflow, build, log, and artifact routes immediately. Existing ZMK routes and the ZMK workspace do not depend on that flag.

A browser app to edit ZMK keymaps. The guided interface covers common changes without requiring keycode knowledge; the advanced source view remains useful for firmware-specific or newly introduced ZMK features.

Try it now! Go to the Keymap Editor and try it out with the built-in keymap-editor-demo-crkbd before setting up your own repo.

Talk to me! 🗣

I'd love to know how the Keymap Editor is working out for you! Has it helped you with managing your own keymaps, are you struggling with functionality, have you created your own keyboard and directed users here?

I want to know about all of that. I'm not taking any donations, the only thing driving this work forward is knowing what is or isn't helping people.

Note

Source code updates are no longer shared here

I have been developing this application on and off since August 2020, but more recent source changes have not been published and this isn't likely to change any time soon. For more information see Wiki: Source Code Updates

If you do want to use the available source code as-is, you may wish to review the original README.

Features

• WYSIWYG keymap editing
• Multiple keymap sources:
  • GitHub repositories
  • Clipboard
  • File system*
• Dark mode!
• Conditional Layers
• Combo editing
• Macro editing (including support for creating/using parameterized macros)
• Behavior editing (creation and re-configuration)
• Auto-generated layouts for ZMK's supported keyboards**
• Rotary encoders
• Multiple keymaps

_{*File system web APIs are currently only supported in Chromium-based browsers}

_{**Auto-generated layouts are meant as a starting-off point and are provided for most keyboards available in the ZMK repo and may need customization -- I own exactly one keyboard, I don't know all the layouts.}

Read more: Wiki:Features

Usage

Local

This project runs as a web application, but there are still options for working with offline ZMK keymaps:

In the editor you can choose the Clipboard keymap source and paste in the contents of your ZMK .keymap file, and if you're using a Chromium-based web browser you can alternatively use the FileSystem source to read and make changes to select .keymap files directly.

Actual firmware builds are outside of the scope of this project, so if you're working on local keymap data it is assumed that you have a local ZMK development environment or some other means of running builds.

Web Integrations

This editor includes a GitHub integration. You can load the web app and grant it access to your public or private zmk-config repos. Changes to your keymap are committed right back to the repository so you only ever need to leave the app to download and flash firmware.

License

The code in this repo is available under the MIT license.

The collection of ZMK keycodes is taken from the ZMK documentation under the MIT license as well.