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.

A binding starts at each token beginning with &, and takes every token after it as a parameter until the next binding starts. So &kp A, &trans and &lt 1 SPACE are each one binding, whatever behavior they name.

  • A name the keymap file itself #defines to a binding, such as #define XXX &none, also starts a binding. A name defined in an included file is read as a parameter.
  • A parameter that is itself a behavior, as in &hmr &caps_word RALT, stays inside its binding only for the behaviors named in MULTI_PARAM_BEHAVIORS in src/keymap_align/align.py. Under any other behavior it starts a binding of its own.

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.5

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.5
File Size Uploaded Provenance Actions
keymap_align-0.2.5.tar.gz 67.9 kB Without provenance Details for keymap_align-0.2.5.tar.gz

Built distribution (wheel)

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

Total release size: 87.6 kB

Release files / keymap_align-0.2.5.tar.gz

Download URL keymap_align-0.2.5.tar.gz
Size 67.9 kB
Tags Source
SHA-256 checksum
How to use checksums
8ae8b2abeb0940bc021a585d95b1ea346bda4386a0242767641d6b9496a59795
BLAKE2b-256 checksum
How to use checksums
bde8abe40cee2b21df90c2304e1106c7d733b52739787b11bc024b472270e9e5
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.5-py3-none-any.whl

Download URL keymap_align-0.2.5-py3-none-any.whl
Size 19.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
49f1e701103214391fa31488a694934e3b61ea9987d46082097fe79c5eba12af
BLAKE2b-256 checksum
How to use checksums
c6d8241b835dbb05b132abd9f11fa224ebcd677afb996ae10b4225c2145b8081
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.5

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