Skip to main content

keymap-align

ZMK keymap alignment tool for custom mechanical keyboards. Parses .keymap files and aligns bindings according to physical keyboard layout definitions, producing consistently formatted keymaps.

Overview

keymap-align reads ZMK keymap files and a JSON layout definition, then reformats the bindings = <...> blocks so that each key binding aligns to its physical column position on the keyboard. This makes keymaps easier to read and maintain across different layer definitions.

Supports:

  • Simple bindings: &kp A, &trans, &none
  • Multi-parameter behaviors: &hml LCTRL A, &lt 1 SPACE
  • Nested behaviors such as &hmr &caps_word RALT, for the behaviors named in MULTI_PARAM_BEHAVIORS in src/keymap_align/align.py
  • Names the keymap file #defines to a binding, such as XXX for &none
  • Split keyboard layouts with empty positions
  • In-place file modification or separate output

Installation

uv tool install keymap-align

keymap-align update installs the newest release.

Quick Start

# Align a keymap in place, using a board that ships with the tool
keymap-align format -k config/corne.keymap --layout corne42

# Use a layout file of your own, and write to a separate file
keymap-align format -k config/glove80.keymap -l my_layout.json -o aligned.keymap

# Debug mode: show the layout and each layer's grid without writing
keymap-align format -k config/piantor.keymap --layout piantor --debug

keymap-align layouts list prints the boards that ship with the tool, one per line: the name --layout takes, its key count and its description, separated by tabs.

Config File

A keymap_align.toml saves passing the layout on every run:

layout = "corne42"   # a bundled board name, or a path to a layout JSON file
indent_size = 4      # spaces before each binding row
padding = 2          # spaces between columns
  • The search starts in the keymap file's directory and walks up to the git root, or to the filesystem root outside a repository. The working directory plays no part.
  • A layout value containing / or \, or ending in .json, is a path. A relative path resolves against the config file's directory. Any other value is a bundled board name.
  • --layout-file beats --layout, and either flag beats the config file.
  • indent_size and padding are set only here. No flag sets them.
  • A config file that fails to parse prints a warning, and the run continues without it.

The search lets an editor formatter pass nothing but the keymap. For conform.nvim:

keymap_align = {
  command = 'keymap-align',
  args = { 'format', '-k', '$FILENAME' },
  stdin = false,
},

Layout JSON Format

Layout files define the physical key matrix using "X" for key positions and "-" for empty spaces:

{
  "name": "Corne 42 Layout",
  "layout": [
    ["X", "X", "X", "X", "X", "X", "-", "-", "X", "X", "X", "X", "X", "X"],
    ["X", "X", "X", "X", "X", "X", "-", "-", "X", "X", "X", "X", "X", "X"],
    ["X", "X", "X", "X", "X", "X", "-", "-", "X", "X", "X", "X", "X", "X"],
    ["-", "-", "-", "-", "X", "X", "X", "X", "X", "X", "-", "-", "-", "-"]
  ]
}

The bundled boards are files in this format in src/keymap_align/layouts/. Adding a file there adds a board, named by the file stem.

How It Works

  1. Parse: Find each layer node inside the keymap's keymap { … } node, and read its bindings array
  2. Structure: Place each layer's bindings, in order, into the layout's "X" cells
  3. Calculate: Give each column the width of its widest binding across all layers, plus padding
  4. Rewrite: Replace the text between each array's < and > with the aligned rows. Each row is indented indent_size spaces, and the closing > goes on its own line at the indentation of the line holding bindings

Everything outside those arrays is kept byte for byte: comments, blank lines, node names, display-name, and every other property, such as sensor-bindings. A layer with fewer bindings than the layout has keys gets a blank cell for each one missing.

A run exits 1 and writes nothing when the keymap cannot be rewritten without losing text:

  • a layer holds more bindings than the layout has keys;
  • a bindings array holds a comment, or a token that does not belong to any binding, such as an undefined macro name before the first &;
  • two layer nodes share a name;
  • a bindings property holds more than one < > array.

Project Structure

keymap-align/
├── src/keymap_align/
│   ├── align.py            # Parsing, column widths and the in-place rewrite
│   ├── cli.py              # CLI entry point
│   ├── config.py           # keymap_align.toml discovery and loading
│   ├── layout_resolver.py  # Flag and config precedence, bundled board lookup
│   └── layouts/            # Bundled board layouts, one JSON file each
└── tests/
    ├── layouts/            # Test layout files
    ├── simple_tests/       # Simple test keymaps
    └── test_keymaps/
        ├── correct/        # Reference output files, compared byte for byte
        └── misaligned/     # Test input files

Development

git clone https://github.com/datapointchris/keymap-align
cd keymap-align
uv sync --all-groups
uv run pre-commit install  # every git commit then runs all the hooks

# Run tests
uv run pytest

# Code quality
uv run ruff check src/
uv run ruff format src/
uv run mypy src/

License

MIT License

Metadata

Release files for keymap-align 0.2.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for keymap-align 0.2.4
File Size Uploaded Provenance Actions
keymap_align-0.2.4.tar.gz 66.3 kB Without provenance Details for keymap_align-0.2.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for keymap-align 0.2.4
File Interpreter ABI Platform Actions
keymap_align-0.2.4-py3-none-any.whl Python 3 none any Details for keymap_align-0.2.4-py3-none-any.whl

Total release size: 85.9 kB

Release files / keymap_align-0.2.4.tar.gz

Download URL keymap_align-0.2.4.tar.gz
Size 66.3 kB
Tags Source
SHA-256 checksum
How to use checksums
b206e594d62a5969dd6571a74d72f3bf0582ec8e308ecdc53fc01611c6bf4422
BLAKE2b-256 checksum
How to use checksums
9c177b851fca2438308673d4e1548add5787b47d6646a9152da6703689eda3be
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.12.24 {"installer":{"name":"uv","version":"0.12.24","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / keymap_align-0.2.4-py3-none-any.whl

Download URL keymap_align-0.2.4-py3-none-any.whl
Size 19.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
36d2e086a65e3ed62802eaf291dd1fbc8bb146179ae12e9f063c899dd8b6782d
BLAKE2b-256 checksum
How to use checksums
80b53b4a2168a4950e5eb6460179ac9e66c0bc0f47288d4b67c76c4d8bd0fa7f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.12.24 {"installer":{"name":"uv","version":"0.12.24","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for keymap-align 0.2.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page