qmk-layout-fmt 0.1.2

Formatter for QMK (https://qmk.fm/) keymap.c LAYOUT() blocks

qmk-layout-fmt

Formatter for QMK keymap.c LAYOUT() blocks.

QMK is an open-source firmware for custom keyboards. Keymaps are defined in C files using LAYOUT() macros that map physical keys to actions across multiple layers.

This tool aligns columns within those layer definitions so that keys line up vertically across rows, making keymaps easier to read and review.

Works with any QMK LAYOUT macro — auto-detects shape from standard names (LAYOUT_split_3x6_3, LAYOUT_ortho_4x12, etc.) and supports custom macros via config file.

Installation

With uv:

uv tool install qmk-layout-fmt

With pipx:

pipx install qmk-layout-fmt

Or directly from the repository:

uv tool install git+https://github.com/OneDeadKey/qmk-layout-fmt

Development

git clone https://github.com/OneDeadKey/qmk-layout-fmt.git
cd qmk-layout-fmt
uv sync
uv run qmk-layout-fmt keymap.c

Maintainer tasks

Requires just:

just build          # build the package
just publish        # build + publish to PyPI
just bump 0.2.0     # update version everywhere
just run keymap.c   # run the formatter locally

Usage

# Format in place (default)
qmk-layout-fmt keymap.c

# Check formatting without modifying (exit code 1 if unformatted, useful for CI)
qmk-layout-fmt keymap.c --check

# All layers share the same column widths (default: each layer aligns independently)
qmk-layout-fmt keymap.c --uniform

Layout shape override

For standard QMK macros (LAYOUT_split_3x6_3, LAYOUT_ortho_4x12, LAYOUT_planck_grid, etc.), the shape is auto-detected from the macro name.

For custom macros, use CLI flags:

qmk-layout-fmt keymap.c --main-rows 4 --cols-per-side 6 --thumb-per-side 3

Or create a .qmk-layout-fmt.toml config file in your project (searched upward from the input file):

[layouts.MY_CUSTOM_LAYOUT]
main_rows = 4
cols_per_side = 6
thumb_per_side = 3

Supported layouts

Macro pattern	Auto-detected	Example
LAYOUT_split_{R}x{C}_{T}	rows, cols per side, thumbs per side	LAYOUT_split_3x6_3 → 3 rows of 6+6, thumb 3+3
LAYOUT_ortho_{R}x{C}	rows, cols split in half	LAYOUT_ortho_4x12 → 4 rows of 6+6
LAYOUT_planck_grid	4 rows of 6+6
Custom macros	via .qmk-layout-fmt.toml or CLI flags	ONEDEADKEY_LAYOUT