- JavaScript 78%
- Nix 10.7%
- CSS 8.4%
- HTML 2.9%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| nix | ||
| public | ||
| server | ||
| tools | ||
| .gitignore | ||
| flake.lock | ||
| flake.nix | ||
| package-lock.json | ||
| package.json | ||
| README.md | ||
keymap-editor (Forgejo)
WYSIWYG editor for ZMK keymaps, wired to a Forgejo instance instead of GitHub. A Forgejo port of nickcoutsos/keymap-editor: the upstream frontend, unchanged apart from its API base URL, talking to a small backend written here against the Forgejo API.
The frontend is the deployed keymap-editor bundle (mirrored into public/, API
base URL patched to window.location.origin) and the backend re-implements the
small API surface it talks to on top of the Forgejo API. Keymap parsing,
layout generation and serialization are the bundle's own modules, loaded
headless in Node (tools/bundle.mjs).
Requirements
- A Forgejo instance (tested against 16.0.6)
- Node 22+ for local development
Run locally
npm install
FORGEJO_CLIENT_ID=... FORGEJO_CLIENT_SECRET=... PUBLIC_URL=http://localhost:3000 npm start
Open http://localhost:3000, then log in against your Forgejo instance.
Environment
| Variable | Default | Meaning |
|---|---|---|
FORGEJO_CLIENT_ID |
required | OAuth2 client id |
FORGEJO_CLIENT_SECRET |
required | OAuth2 client secret |
FORGEJO_URL |
https://git.notthebe.ee |
Forgejo base URL |
PUBLIC_URL |
http://localhost:$PORT |
External URL, must match the OAuth redirect |
PORT |
3000 |
Listen port |
DATA_DIR |
.data |
Session storage |
KEYMAP_PATHS |
config |
Comma separated repo dirs holding *.keymap |
Forgejo OAuth application
Create an OAuth2 application on your Forgejo instance (Settings → Applications → OAuth2 Applications) with:
- Redirect URI:
<PUBLIC_URL>/github/authorize/callback - Confidential client: yes
The editor only needs the instance-level /user, /user/repos, /repos/* and
/git/* endpoints of the logged-in user, so no extra scopes are required.
Keyboard definitions
Bundled metadata for 89 keyboards ships in public/keyboard-data/: say
corne in the picker and it renders. For your own board, add
<KEYMAP_PATHS>/<keyboard>.json (the standard keymap-editor keyboard
definition) next to the .keymap file; it takes precedence over the bundled
definition.
Save behaviour
Saving serializes the edited model back into the original devicetree source
with the bundle's own formatter and commits through the Forgejo contents API
using the sha the editor loaded — a concurrent change aborts with
commitMismatch instead of clobbering it.
NixOS deployment
{
inputs.keymap-editor.url = "git+https://git.notthebe.ee/notthebee/keymap-editor";
# in your host config
imports = [ inputs.keymap-editor.nixosModules.default ];
services.keymap-editor.enable = true;
services.keymap-editor.publicUrl = "https://keymap.example.com";
services.keymap-editor.environmentFile = config.age.secrets.keymap-editor.path;
}
The service listens on 127.0.0.1:3000-ish plain HTTP; put a reverse proxy in
front (any nginx/caddy with websocket upgrade for /github/events). The
environmentFile must define FORGEJO_CLIENT_ID and FORGEJO_CLIENT_SECRET.
Standalone:
nix run . # needs the env vars above
nix build .#default
Checks
npm run check # parse → layout → serialize round trip
npm test # full API flow against a stubbed Forgejo
nix build .#checks.x86_64-linux.self-check
Layout
public/— mirrored frontend bundle with the API base URL patchedserver/index.mjs— HTTP API, static hosting, websocket build eventsserver/lib/{auth,forgejo,keymaps,zmk}.mjs— OAuth, Forgejo client, keymap files, bundle module bridgetools/bundle.mjs— runs the mirrored webpack bundle insidenode:vmtools/self-check.mjs— offline round-trip checknix/module.nix— NixOS module
Upstream / credits
This project is a Forgejo port of nickcoutsos/keymap-editor
(MIT). The frontend bundle in public/ — editor UI, keymap parser, layout
generator, devicetree serializer, keyboard metadata — is upstream's build, used
unmodified apart from the API base URL and UI wording. All credit for it goes to
Nick Coutsos and its contributors; that project is the place to report editor
bugs and to send donations.
The backend in server/ and the Forgejo integration are the work of this
repository.