Metadata-Version: 2.4
Name: qmk-layout-fmt
Version: 0.1.2
Summary: Formatter for QMK (https://qmk.fm/) keymap.c LAYOUT() blocks
Project-URL: Homepage, https://github.com/OneDeadKey/qmk-layout-fmt
Project-URL: Repository, https://github.com/OneDeadKey/qmk-layout-fmt
Project-URL: Issues, https://github.com/OneDeadKey/qmk-layout-fmt/issues
Author: OneDeadKey
License-Expression: Unlicense
License-File: LICENSE
Keywords: formatter,keyboard,keymap,layout,qmk
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: The Unlicense (Unlicense)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# qmk-layout-fmt

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

[QMK](https://docs.qmk.fm/) 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](https://docs.astral.sh/uv/):

```bash
uv tool install qmk-layout-fmt
```

With [pipx](https://pipx.pypa.io/):

```bash
pipx install qmk-layout-fmt
```

Or directly from the repository:

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

## Development

```bash
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](https://github.com/casey/just):

```bash
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

```bash
# 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:

```bash
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):

```toml
[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`                             |

