### Get keymap-drawer help

Source: https://github.com/caksoylar/keymap-drawer/blob/main/README.md

After installation, you can view the available commands and options for the keymap-drawer tool by running 'keymap --help'.

```sh
keymap --help
```

--------------------------------

### Layout Specification Examples

Source: https://github.com/caksoylar/keymap-drawer/blob/main/KEYMAP_SPEC.md

Examples demonstrate various ways to specify the physical keyboard layout using different sources like QMK, ZMK, JSON, DTS, or parameterized ortholinear definitions.

```yaml
layout: {qmk_keyboard: crkbd/rev1}
```

```yaml
layout: {zmk_keyboard: corne}
```

```yaml
layout: {qmk_info_json: my_special_layout.json}
```

```yaml
layout: {dts_layout: my_keyboard-layouts.dtsi}
```

```yaml
layout: {zmk_keyboard: corne, layout_name: foostan_corne_5col_layout}
```

```yaml
layout: {qmk_keyboard: crkbd/rev1, layout_name: LAYOUT_split_3x5_3}
```

```yaml
layout: {ortho_layout: {split: true, rows: 3, columns: 5, thumbs: 3}}
```

```yaml
layout: {cols_thumbs_notation: 33333+1 2+33332}
```

--------------------------------

### Install Project with Pip

Source: https://github.com/caksoylar/keymap-drawer/blob/main/README.md

If you prefer not to use Poetry, you can install the project in an editable mode using pip.

```sh
pip install --editable .
```

--------------------------------

### Install Keymap Drawer in a virtual environment

Source: https://context7.com/caksoylar/keymap-drawer/llms.txt

Installs the keymap-drawer tool within a Python virtual environment.

```sh
pip install keymap-drawer
```

--------------------------------

### Install Project Dependencies with Poetry

Source: https://github.com/caksoylar/keymap-drawer/blob/main/README.md

Use this command to install project dependencies, including optional development and LSP dependencies. Ensure Poetry is installed first.

```sh
git clone https://github.com/caksoylar/keymap-drawer.git
cd keymap-drawer
poetry install  # -E dev -E lsp (optional dependencies)
```

--------------------------------

### Install keymap-drawer with pipx

Source: https://github.com/caksoylar/keymap-drawer/blob/main/README.md

Use pipx to install the keymap-drawer package, which isolates the installation and makes the 'keymap' command available in your PATH.

```sh
pipx install keymap-drawer
```

--------------------------------

### Automated Drawing Workflow Setup

Source: https://github.com/caksoylar/keymap-drawer/blob/main/README.md

This YAML snippet shows how to set up a GitHub Actions workflow to automatically parse and draw keymaps for a ZMK configuration repository. It references a reusable workflow for keymap-drawer.

```yaml
# prettier-ignore
```yaml

```

--------------------------------

### Keymap YAML Combo Specification Examples

Source: https://context7.com/caksoylar/keymap-drawer/llms.txt

Shows various ways to define combos in the keymap YAML. Supports minimal definitions, trigger by legend, non-mid alignment, custom box sizes, slide effects, separate drawing, and hidden combos.

```yaml
combos:
  # Minimal: two adjacent keys producing Tab on all layers
  - {p: [0, 1], k: Tab}

  # Trigger by legend values instead of indices
  - {tk: [J, K], k: Esc, l: [Base, Nav]}

  # Non-mid alignment with offset and dendrons
  - {p: [3, 13], k: BOOT, a: top, offset: 0.5, dendron: true}

  # Positioned to the left with arc scaling
  - {p: [0, 10, 20], k: RST, a: left, arc_scale: 1.5}

  # Custom combo box size and rotation
  - {p: [5, 6], k: ENT, width: 40, height: 30, rotation: 45}

  # Slide combo box between two keys
  - {p: [4, 5], k: BOOT, a: top, slide: -0.5}

  # Layer-specific combo drawn in a separate mini-diagram
  - {p: [2, 3], k: "( )", l: [Sym], draw_separate: true}

  # Hidden combo: parsed but not drawn
  - {p: [9, 10], k: RESET, hidden: true}

```

--------------------------------

### QMK Keyboard Mapping Example

Source: https://github.com/caksoylar/keymap-drawer/blob/main/resources/README.md

Maps QMK keyboard values to other QMK keyboard values, used to prioritize specific physical layout definitions. Trailing slashes indicate prefix matching.

```yaml
corne:
  # Maps all Corne variants to use the extra_layouts/corne_rotated.json file
  # instead of the QMK default layout for crkbd/rev1.
  crkbd/rev1/: extra_layouts/corne_rotated.json
```

--------------------------------

### Full Keymap YAML Structure Example

Source: https://context7.com/caksoylar/keymap-drawer/llms.txt

Defines the physical layout, all layers with per-key legends, combo definitions, and optional per-file draw configuration overrides. Supports simple strings, hold-tap mappings, shifted legends, SVG glyphs, and ghost keys.

```yaml
# Full keymap YAML example (e.g., showcase.yaml)
layout:
  qmk_keyboard: corne_rotated
  layout_name: LAYOUT_split_3x5_3

layers:
  Base:
    # Row 1: simple string keys
    - [Q, W, F, P, B,  J, L, U, Y, "'"]
    # Row 2: hold-tap keys using {t: tap, h: hold} mapping
    - [{h: Ctrl, t: A}, {h: Gui, t: R}, {h: Alt, t: S}, {h: Shift, t: T}, G,
       M, {h: Shift, t: N}, {h: Alt, t: E}, {h: Gui, t: I}, {h: Ctrl, t: O}]
    # Row 3: key with shifted legend
    - [Z, X, C, D, V,  K, H, {t: ',', s: '<'}, {t: '.', s: '>'}, {t: '/', s: '?'}]
    # Thumb row with SVG glyphs and ghost key
    - {h: Gui,   t: $$mdi:keyboard-tab$$, type: ghost}
    - {h: Ctrl,  t: $$mdi:keyboard-esc$$}
    - {h: NAV,   t: $$mdi:backspace-outline$$}
    - {h: SYM,   t: $$mdi:keyboard-space$$}
    - {h: Shift, t: $$mdi:keyboard-return$$}
    - {h: Alt,   t: $$mdi:backspace-reverse-outline$$, type: ghost}

  Nav:
    - ['', '', '', '', '',  PGUP, HOME, UP,   END,  VOLU]
    - ['', '', '', '', '',  PGDN, LEFT, DOWN, RGHT, VOLD]
    - ['', '', '', '', '',  '',   '',   '',   '',   '']
    - ['', {type: held}, '', '', '']

combos:
  # Position-based combo using key indices
  - {p: [0, 1], k: Tab, l: [Base]}
  # trigger_keys-based combo (matches by tap legend)
  - {tk: [J, K], k: Esc, l: [Base]}
  # Non-adjacent combo with explicit positioning
  - {p: [0, 10, 20], k: RST, a: left}
  # Combo with SVG glyph output
  - {p: [14, 24], k: $$mdi:play-pause$$}
  # Combo with offset to avoid overlap
  - {p: [13, 16], k: Caps Wrd, a: top, offset: 0.5}

draw_config:
  glyph_tap_size: 18
  dark_mode: auto
  n_columns: 2

```

--------------------------------

### Keymap YAML Key Definition Examples

Source: https://context7.com/caksoylar/keymap-drawer/llms.txt

Illustrates how to define keys within a layer in YAML. Supports simple string shorthand for tap-only keys and full mappings for keys with multiple legend positions and types like 'held', 'ghost', or 'trans'.

```yaml
layers:
  Example:
    # String shorthand: equivalent to {tap: "A"}
    - A
    # Full mapping with all legend positions
    - tap: Ctrl     # center legend (alias: t, center)
      hold: Ctrl    # bottom legend (alias: h, bottom)
      shifted: "~"  # top legend    (alias: s, top)
      left: "L"     # left-center legend
      right: "R"    # right-center legend
      tl: "TL"      # top-left corner
      tr: "TR"      # top-right corner
      bl: "BL"      # bottom-left corner
      br: "BR"      # bottom-right corner
      type: held    # CSS class: held | ghost | trans | (custom)
    # Transparent key (pass-through)
    - {t: "▽", type: trans}
    # Ghost key (optional/layout variant)
    - {t: DEL, type: ghost}

```

--------------------------------

### ZMK Keyboard Layout Mapping Example

Source: https://github.com/caksoylar/keymap-drawer/blob/main/resources/README.md

Maps ZMK keyboard names to physical layout specifications, including transformations for different layout types. Used by `keymap parse` to determine the physical layout spec.

```yaml
planck:
  layout_grid_transform: { qmk_keyboard: planck/rev6, layout_name: LAYOUT_ortho_4x12 }
  layout_mit_transform: { qmk_keyboard: planck/rev6, layout_name: LAYOUT_planck_1x2uC }
  layout_2x2u_transform: { qmk_keyboard: planck/rev6, layout_name: LAYOUT_planck_2x2u }
```

--------------------------------

### Cols+Thumbs Notation Example

Source: https://github.com/caksoylar/keymap-drawer/blob/main/PHYSICAL_LAYOUTS.md

Specifies an asymmetric 32-key split keyboard layout with 3 rows and 5 columns on the left, and a right-aligned thumb cluster. The right half has a left-aligned thumb cluster, 5 columns with 3 rows, and an extra outer pinky key.

```text
layout: {cols_thumbs_notation: 33333+3 2+333331}
```

--------------------------------

### Keymap Draw Configuration Parameters

Source: https://context7.com/caksoylar/keymap-drawer/llms.txt

Lists key drawing parameters that can be set via a `draw_config` block in the keymap YAML or as `KEYMAP_` prefixed environment variables. Example shows `glyph_tap_size`, `dark_mode`, and `n_columns`.

```yaml
draw_config:
  glyph_tap_size: 18
  dark_mode: auto
  n_columns: 2

```

--------------------------------

### ZMK Physical Layout Selection in DTS

Source: https://github.com/caksoylar/keymap-drawer/blob/main/resources/README.md

Example of how a physical layout is selected within a ZMK device tree source (dts) file using the `zmk,physical-layout` or `zmk,matrix-transform` chosen node.

```dts
/ {
    chosen {
        zmk,physical-layout = &layout_ortho_4x12_2x2u;

        // or, equivalently:
        // zmk,matrix-transform = &layout_2x2u_transform;
    };
    ...
};
```

--------------------------------

### Define Keymap Layers with Flattening

Source: https://github.com/caksoylar/keymap-drawer/blob/main/KEYMAP_SPEC.md

Use the `layers` field to define key layers. Nested lists within `layers` are automatically flattened, allowing for semantically divided rows. The two examples shown are functionally identical.

```yaml
layers:
  flat_layer: ["7", "8", "9", "4", "5", "6", "1", "2", "3", {t: "0", h: Fn}]
  nested_layer:
    - ["7", "8", "9"]
    - ["4", "5", "6"]
    - ["1", "2", "3"]
    - {t: "0", h: Fn}
```

--------------------------------

### Customizing Commit Message for Keymap Drawer

Source: https://github.com/caksoylar/keymap-drawer/blob/main/README.md

Modify the default commit message generated by the keymap-drawer workflow. This example shows how to use the triggering commit's message, prepended with a tag.

```yaml
jobs:
  draw:
    uses: caksoylar/keymap-drawer/.github/workflows/draw-zmk.yml@main
    with:
      # Use the triggering commit's message, prepending the "[Draw]" tag
      commit_message: "[Draw] ${{ github.event.head_commit.message }}"
      # …other inputs
```

--------------------------------

### Advanced Cols+Thumbs Notation with Alignment Modifiers

Source: https://github.com/caksoylar/keymap-drawer/blob/main/PHYSICAL_LAYOUTS.md

Demonstrates advanced 'cols+thumbs' notation using alignment modifiers ('v', 'd', '^', 'u' for vertical; '>', '<', 'r', 'l' for horizontal) to precisely position columns and thumb rows. This example results in a complex physical layout with offset elements.

```text
2v333+2> 3+13332^ 33
```

--------------------------------

### Export and Use Default Keymap Configuration

Source: https://context7.com/caksoylar/keymap-drawer/llms.txt

Demonstrates how to dump the default configuration to a YAML file using `keymap dump-config`, edit it, and then use the modified configuration with `keymap parse` and `keymap draw` commands.

```bash
# Dump default config to file
keymap dump-config > my_config.yaml

# Edit the file, then use with parse and draw
keymap -c my_config.yaml parse -z config/cradio.keymap > cradio.yaml
keymap -c my_config.yaml draw cradio.yaml > cradio.svg

```

--------------------------------

### Python API — `KeymapDrawer`

Source: https://context7.com/caksoylar/keymap-drawer/llms.txt

Programmatically use the `keymap-drawer` library in Python to parse firmware files or render SVG from keymap data structures. Supports ZMK and QMK keymaps.

```APIDOC
## Python API — `KeymapDrawer`

Use `keymap-drawer` programmatically in Python to parse firmware files or render SVG from keymap data structures.

```python
import yaml
from io import StringIO

from keymap_drawer.config import Config, DrawConfig
from keymap_drawer.draw import KeymapDrawer
from keymap_drawer.parse import ZmkKeymapParser, QmkJsonParser

# --- Parse a ZMK keymap file ---
config = Config()
with open("config/cradio.keymap", "rt", encoding="utf-8") as f:
    parsed_keymap = ZmkKeymapParser(
        config.parse_config,
        columns=10,           # group keys into rows of 10
        layer_names=None,     # use names from firmware
        virtual_layers=None,
    ).parse(f)

# Dump the parsed result to YAML
yaml.safe_dump(
    parsed_keymap,
    stream=open("cradio.yaml", "wt"),
    width=160,
    sort_keys=False,
    default_flow_style=None,
    allow_unicode=True,
)

# --- Draw SVG from a keymap YAML ---
with open("cradio.yaml", "rt", encoding="utf-8") as f:
    keymap_data = yaml.safe_load(f)

# Optionally customize drawing config
draw_cfg_overrides = {"dark_mode": "auto", "n_columns": 2, "glyph_tap_size": 18}
config.draw_config = DrawConfig.parse_obj(
    config.draw_config.model_dump() | draw_cfg_overrides
)

output = StringIO()
drawer = KeymapDrawer(
    config=config,
    out=output,
    layers=keymap_data["layers"],
    layout=keymap_data["layout"],      # e.g. {"qmk_keyboard": "ferris/sweep"}
    combos=keymap_data.get("combos", []),
)
drawer.print_board()
svg_content = output.getvalue()

with open("cradio.svg", "wt", encoding="utf-8") as f:
    f.write(svg_content)
```
```

--------------------------------

### Parse QMK Keymap from VIA backup

Source: https://github.com/caksoylar/keymap-drawer/blob/main/README.md

Parses a QMK keymap from a VIA backup JSON file into YAML format. Specify the keyboard and layout with `-kb` and the backup file. Use `-c` for columns, `-q` for quiet mode, and `-` for stdout.

```sh
qmk via2json -kb ferris/sweep sweep_via_backup.json | keymap parse -c 10 -q - >sweep_keymap.yaml
```

--------------------------------

### Parse QMK Keymap from .c file

Source: https://github.com/caksoylar/keymap-drawer/blob/main/README.md

Parses a QMK keymap from a `.c` file into YAML format. Use the `-c` flag to specify the total number of columns. The `-q` flag enables quiet mode, and `-` directs output to stdout.

```sh
qmk c2json ~/qmk_firmware/keyboards/ferris/keymaps/username/keymap.c | keymap parse -c 10 -q - >sweep_keymap.yaml
```

--------------------------------

### Dump Default Configuration

Source: https://github.com/caksoylar/keymap-drawer/blob/main/README.md

Use this command to generate a default configuration file that can be edited for custom settings.

```sh
keymap dump-config >my_config.yaml
```

--------------------------------

### Local QMK Info.json Layout Specification

Source: https://context7.com/caksoylar/keymap-drawer/llms.txt

Define a keyboard layout by referencing a local QMK `info.json` file. The `layout_name` specifies which layout to use from the file.

```yaml
# Method 3: Local QMK info.json file
layout:
  qmk_info_json: my_custom_keyboard.json
  layout_name: LAYOUT_default
```

--------------------------------

### Draw Keymap with Different Layout Options

Source: https://context7.com/caksoylar/keymap-drawer/llms.txt

Use the `keymap draw` command with various layout notations to generate keymap visualizations. Supports ortho-layout, column-thumb notation, and advanced column offset modifiers.

```bash
keymap draw planck_keymap.yaml --ortho-layout '{split: false, rows: 4, columns: 12, thumbs: MIT}'
```

```bash
keymap draw sweep_keymap.yaml -n '33333+3 2+33331'
```

```bash
keymap draw my_keymap.yaml -n '2v333+2> 3+13332^ 33'
```

--------------------------------

### Automate ZMK Keymap Drawing with GitHub Actions

Source: https://context7.com/caksoylar/keymap-drawer/llms.txt

This reusable workflow automates the parsing and drawing of ZMK keymaps on push events. It commits SVG and YAML outputs back to the repository. Configure `keymap_patterns`, `config_path`, and optional arguments for parsing and drawing.

```yaml
# .github/workflows/draw-keymaps.yml in your ZMK config repo
name: Draw ZMK keymaps
on:
  workflow_dispatch:
  push:
    paths:
      - "config/*.keymap"
      - "config/*.dtsi"
      - "keymap_drawer.config.yaml"

jobs:
  draw:
    uses: caksoylar/keymap-drawer/.github/workflows/draw-zmk.yml@main
    permissions:
      contents: write
    with:
      keymap_patterns: "config/*.keymap"
      config_path: "keymap_drawer.config.yaml"
      output_folder: "keymap-drawer"
      # Per-keyboard extra args:
      parse_args: "corne:'--layer-names Def Lwr Rse Fun'"
      draw_args:  "corne:'-k corne_rotated -l LAYOUT_split_3x5_3'"
      # Customize commit message
      commit_message: "[Draw] ${{ github.event.head_commit.message }}"
      # Or amend the triggering commit instead:
      # amend_commit: true
      # Pin to a specific keymap-drawer version:
      # install_version: "0.22.0"
      # Upload as artifact instead of committing:
      # destination: artifact
      # artifact_name: keymap-drawings
```

--------------------------------

### Select QMK Layout Name

Source: https://github.com/caksoylar/keymap-drawer/blob/main/PHYSICAL_LAYOUTS.md

When using `qmk_keyboard` or `qmk_info_json`, `layout_name` specifies the layout macro to use from the QMK info file. If omitted, the first defined layout is used.

```dts
layout: {qmk_keyboard: crkbd/rev1, layout_name: LAYOUT_split_3x5_3}
```

--------------------------------

### Override Configuration with Environment Variables

Source: https://github.com/caksoylar/keymap-drawer/blob/main/README.md

Configuration settings, particularly 'raw_binding_map', can be overridden using environment variables with the 'KEYMAP_' prefix. This is useful for quick changes or CI/CD pipelines.

```sh
KEYMAP_raw_binding_map='{"&bootloader": "BOOT"}' keymap parse -z zmk-config/config/cradio.keymap >cradio.yaml
```

--------------------------------

### Apply Custom Configuration to Parse and Draw

Source: https://github.com/caksoylar/keymap-drawer/blob/main/README.md

Pass a custom configuration file to the 'parse' and 'draw' subcommands using the -c or --config flag. The configuration file path must precede the subcommand.

```sh
keymap -c my_config.yaml parse [...] >my_keymap.yaml
```

```sh
keymap -c my_config.yaml draw [...] my_keymap.yaml >my_keymap.svg
```

--------------------------------

### Basic Keymap Structure

Source: https://github.com/caksoylar/keymap-drawer/blob/main/KEYMAP_SPEC.md

A typical keymap includes optional physical layout specifications, ordered layers with key mappings, optional combo definitions, and optional drawing configuration overrides.

```yaml
layout:      # physical layout specs, optional if used in CLI
  ...
layers:      # ordered mapping of layer name to contents
  layer_1:   # list of (lists of) key specs
    - [Q, W, ...]
    ...
  layer_2:
    ...
combos:      # list of combo specs, optional
  - ...
draw_config: # config overrides for drawing, optional
  ...
```

--------------------------------

### Automated GitHub Actions Workflow for ZMK Configs

Source: https://context7.com/caksoylar/keymap-drawer/llms.txt

A reusable GitHub Actions workflow to automatically draw ZMK keymaps on push events. It parses keymaps, generates SVGs, and commits the output back to your repository.

```APIDOC
## Automated GitHub Actions Workflow for ZMK Configs

A reusable GitHub Actions workflow that automatically parses and draws ZMK keymaps on push, committing SVG and YAML outputs back to the repository.

```yaml
# .github/workflows/draw-keymaps.yml in your ZMK config repo
name: Draw ZMK keymaps
on:
  workflow_dispatch:
  push:
    paths:
      - "config/*.keymap"
      - "config/*.dtsi"
      - "keymap_drawer.config.yaml"

jobs:
  draw:
    uses: caksoylar/keymap-drawer/.github/workflows/draw-zmk.yml@main
    permissions:
      contents: write
    with:
      keymap_patterns: "config/*.keymap"
      config_path: "keymap_drawer.config.yaml"
      output_folder: "keymap-drawer"
      # Per-keyboard extra args:
      parse_args: "corne:'--layer-names Def Lwr Rse Fun'"
      draw_args:  "corne:'-k corne_rotated -l LAYOUT_split_3x5_3'"
      # Customize commit message
      commit_message: "[Draw] ${{ github.event.head_commit.message }}"
      # Or amend the triggering commit instead:
      # amend_commit: true
      # Pin to a specific keymap-drawer version:
      # install_version: "0.22.0"
      # Upload as artifact instead of committing:
      # destination: artifact
      # artifact_name: keymap-drawings
```
```

--------------------------------

### Parse QMK keymap.json to YAML

Source: https://context7.com/caksoylar/keymap-drawer/llms.txt

Converts a QMK keymap.json file to the keymap YAML format. Use the -c flag to set the column count for better key grouping and -q for quiet operation. Output can be redirected to a file or stdout.

```sh
qmk c2json ~/qmk_firmware/keyboards/ferris/keymaps/myuser/keymap.c \
  | keymap parse -c 10 -q - > sweep_keymap.yaml
```

```sh
qmk via2json -kb ferris/sweep sweep_via_backup.json \
  | keymap parse -c 10 -q - > sweep_keymap.yaml
```

```sh
keymap parse -c 10 -q keymap.json --layer-names Base Sym Nav Fun > sweep_keymap.yaml
```

```sh
keymap parse -c 10 -q keymap.json -o sweep_keymap.yaml
```

--------------------------------

### ZMK Specific Parsing and Include Paths

Source: https://context7.com/caksoylar/keymap-drawer/llms.txt

Configure ZMK-specific parsing for combos, including alignment and offsets, and specify additional include paths for the preprocessor.

```yaml
  # Augment parsed ZMK combo positioning/alignment
  zmk_combos:
    combo_esc:
      align: top
      offset: 0.5
    combo_tab:
      align: left

  # Extra include paths for ZMK preprocessor (e.g., for zmk-helpers)
  zmk_additional_includes:
    - "/path/to/zmk-helpers/include"
```

--------------------------------

### Draw SVG from Keymap YAML using QMK Physical Layout

Source: https://context7.com/caksoylar/keymap-drawer/llms.txt

Generates an SVG from a keymap YAML file. Automatically fetches the physical layout from QMK's metadata API using a QMK keyboard name. The physical layout can be overridden on the CLI or by providing a local info.json file.

```sh
keymap draw sweep_keymap.yaml > sweep_keymap.svg
```

```sh
keymap draw sweep_keymap.yaml -k splitkb/kyria/rev1 -l LAYOUT_split_3x6_5 > kyria_keymap.svg
```

```sh
keymap draw sweep_keymap.yaml -j my_custom_keyboard.json > custom_keymap.svg
```

```sh
keymap draw sweep_keymap.yaml --select-layers Base Nav Sym > subset_keymap.svg
```

```sh
keymap draw sweep_keymap.yaml -o sweep_keymap.svg
```

--------------------------------

### Specify DTS Layout File

Source: https://github.com/caksoylar/keymap-drawer/blob/main/PHYSICAL_LAYOUTS.md

Use `dts_layout` to point to a local devicetree file containing ZMK physical layouts. This is equivalent to the command-line `-d` or `--dts-layout` option.

```dts
layout: {dts_layout: my_keyboard-layouts.dtsi}
```

--------------------------------

### Keycode Parsing and Label Mapping in parse_config

Source: https://context7.com/caksoylar/keymap-drawer/llms.txt

Control how firmware keymaps are parsed, including preprocessor behavior, raw binding substitutions, and display label mappings.

```yaml
parse_config:
  # Run C preprocessor on ZMK keymaps (default: true)
  preprocess: true

  # Skip all keycode parsing except raw_binding_map entries
  skip_binding_parsing: false

  # Direct substitutions applied before any other processing
  raw_binding_map:
    "&bootloader": "BOOT"
    "&sys_reset": "RST"
    "QK_BOOT": "BOOT"

  # Labels for special key behaviors
  sticky_label: "sticky"
  toggle_label: "toggle"
  tap_toggle_label: "tap-toggle"

  # Transparent key representation
  trans_legend:
    t: "▽"
    type: trans

  # Map layer names to shorter display forms on layer-activator keys
  layer_legend_map:
    Navigation: Nav
    Symbols: Sym

  # Mark ALL sequences that activate a layer as held (not just first)
  mark_alternate_layer_activators: false
```

--------------------------------

### Parse ZMK keymap file to YAML

Source: https://context7.com/caksoylar/keymap-drawer/llms.txt

Parses a ZMK .keymap file, including preprocessor expansion, into keymap YAML. Automatically extracts combos, hold-taps, and layer names. Use -b to preserve manual tweaks when re-parsing.

```sh
keymap parse -c 10 -z ~/zmk-config/config/cradio.keymap > sweep_keymap.yaml
```

```sh
keymap parse -z ~/zmk-config/config/cradio.keymap -b old_sweep_keymap.yaml > new_sweep_keymap.yaml
```

```sh
keymap -c my_config.yaml parse -z ~/zmk-config/config/cradio.keymap > sweep_keymap.yaml
```

```sh
KEYMAP_raw_binding_map='{"&bootloader": "BOOT", "&sys_reset": "RST"}' \
  keymap parse -z ~/zmk-config/config/cradio.keymap > sweep_keymap.yaml
```

--------------------------------

### Configuring Keymap Drawer to Remove Locale Prefixes

Source: https://github.com/caksoylar/keymap-drawer/blob/main/README.md

This YAML configuration snippet shows how to use the `zmk_remove_keycode_prefix` option to strip locale prefixes from keycodes, facilitating easier conversion by keymap-drawer.

```yaml
parse_config:
  zmk_remove_keycode_prefix: ["DE_"]
```

--------------------------------

### Parse ZMK Keymap

Source: https://github.com/caksoylar/keymap-drawer/blob/main/README.md

Parses a ZMK `.keymap` file into YAML format. This command preprocesses ZMK files, expanding defines and includes. Use `-c` to specify columns and `-z` to indicate a ZMK keymap.

```sh
keymap parse -c 10 -z ~/zmk-config/config/cradio.keymap >sweep_keymap.yaml
```

--------------------------------

### Key Dimensions and Styling in draw_config

Source: https://context7.com/caksoylar/keymap-drawer/llms.txt

Configure the visual dimensions of keys, gaps, and rounded corners. Also sets dark mode preference and legend shrinking behavior.

```yaml
draw_config:
  # Key dimensions (px); non-ortho layouts use key_h for both axes
  key_w: 60
  key_h: 56

  # Gap between split halves (ortho layouts only)
  split_gap: 30

  # Combo box dimensions
  combo_w: 28
  combo_h: 26

  # Rounded rectangle corner radii
  key_rx: 6
  key_ry: 6

  # Dark mode: false | true | "auto" (follows OS/browser preference)
  dark_mode: auto

  # Lay out layers in 2 columns side-by-side
  n_columns: 2

  # Draw combos in separate mini-diagrams instead of overlaying on layers
  separate_combo_diagrams: false
  combo_diagrams_scale: 2

  # Padding between keys and between layers
  inner_pad_w: 2
  inner_pad_h: 2
  outer_pad_w: 30
  outer_pad_h: 56

  # Shrink font for legends longer than N chars (0 = disable)
  shrink_wide_legends: 7

  # Draw keycap profile "key sides"
  draw_key_sides: true
  key_side_pars:
    rel_x: 0
    rel_y: 4
    rel_w: 12
    rel_h: 12
    rx: 4
    ry: 4

  # SVG glyph sizes per legend position (px)
  glyph_tap_size: 14
  glyph_hold_size: 12
  glyph_shifted_size: 10
```

--------------------------------

### QMK Keyboard Layout Specification

Source: https://context7.com/caksoylar/keymap-drawer/llms.txt

Specify a keyboard layout using its QMK name. An optional `layout_name` can be provided to select a specific layout if the keyboard has multiple defined.

```yaml
# Method 1: QMK keyboard name (fetched from QMK API or resources/extra_layouts/)
layout:
  qmk_keyboard: splitkb/kyria/rev1
  layout_name: LAYOUT_split_3x6_5   # optional; uses first layout if omitted
```

--------------------------------

### Draw ZMK Keymaps Workflow

Source: https://github.com/caksoylar/keymap-drawer/blob/main/README.md

This GitHub Actions workflow automatically draws ZMK keymaps on changes to keymap or configuration files. It uses the keymap-drawer action to generate SVG and YAML files.

```yaml
name: Draw ZMK keymaps
on:
  workflow_dispatch:  # can be triggered manually
  push:               # automatically run on changes to following paths
    paths:
      - "config/*.keymap"
      - "config/*.dtsi"
      - "keymap_drawer.config.yaml"
      # - 'boards/*/*/*.keymap'

jobs:
  draw:
    uses: caksoylar/keymap-drawer/.github/workflows/draw-zmk.yml@main
    permissions:
      contents: write  # allow workflow to commit to the repo
    with:
      keymap_patterns: "config/*.keymap"        # path to the keymaps to parse
      config_path: "keymap_drawer.config.yaml"  # config file, ignored if not exists
      output_folder: "keymap-drawer"            # path to save produced SVG and keymap YAML files
      parse_args: ""  # map of extra args to pass to `keymap parse`, e.g. "corne:'-l Def Lwr Rse' cradio:''"
      draw_args: ""   # map of extra args to pass to `keymap draw`, e.g. "corne:'-k corne_rotated' cradio:'-k paroxysm'"
```

--------------------------------

### Draw SVG with Ortholinear Parametric Layout

Source: https://context7.com/caksoylar/keymap-drawer/llms.txt

Generates an SVG by creating a physical layout on-the-fly using row, column, and thumb parameters. This avoids the need for separate QMK or ZMK layout files.

```sh
keymap draw sweep_keymap.yaml --ortho-layout '{split: true, rows: 3, columns: 5, thumbs: 3}'
```

--------------------------------

### Define Keymap Combos

Source: https://github.com/caksoylar/keymap-drawer/blob/main/KEYMAP_SPEC.md

Use this format to define keymap combos, specifying trigger keys and associated layers. Fields like 'p' (key positions) and 'tk' (trigger keys) are used to identify the keys involved in the combo.

```yaml
combos:
  - { p: [0, 1], k: Tab, l: [Qwerty] }
  - { tk: [J, K], k: Esc, l: [Qwerty] }
```

--------------------------------

### Handling ZMK Locale Headers with Keymap Drawer

Source: https://github.com/caksoylar/keymap-drawer/blob/main/README.md

This C code snippet demonstrates how to conditionally include locale headers using a define guard to prevent them from being processed by keymap-drawer. This ensures keycode names are parsed correctly.

```c
#ifndef KEYMAP_DRAWER
#include "keys_de.h"
#endif
```

--------------------------------

### Generate Parametrized Ortholinear Layout

Source: https://github.com/caksoylar/keymap-drawer/blob/main/PHYSICAL_LAYOUTS.md

Use `ortho_layout` to define parameters for automatically generating a split or non-split ortholinear keyboard layout. This is equivalent to the `--ortho-layout` command-line option.

```dts
layout: {ortho_layout: {split: true, rows: 3, columns: 5, thumbs: 3}}
```

--------------------------------

### Preserve Manual Modifications during Parsing

Source: https://github.com/caksoylar/keymap-drawer/blob/main/README.md

Re-parses a firmware file while preserving manual tweaks from a previous parse output. Use the `-b` flag followed by the old keymap YAML file.

```sh
keymap parse -b old_keymap.yaml ... >new_keymap.yaml
```

--------------------------------

### Select ZMK Layout Name

Source: https://github.com/caksoylar/keymap-drawer/blob/main/PHYSICAL_LAYOUTS.md

When using `zmk_keyboard` or `dts_layout`, `layout_name` specifies a ZMK physical layout node label within the definition. If omitted, the first defined layout is used.

```dts
layout: {zmk_keyboard: corne, layout_name: foostan_corne_5col_layout}
```

--------------------------------

### Parse ZMK Keymap and Dump to YAML using Python API

Source: https://context7.com/caksoylar/keymap-drawer/llms.txt

Programmatically parse a ZMK keymap file using `ZmkKeymapParser`. Configure parsing options like column grouping and layer name handling. The parsed data can then be dumped to a YAML file.

```python
import yaml
from io import StringIO

from keymap_drawer.config import Config, DrawConfig
from keymap_drawer.draw import KeymapDrawer
from keymap_drawer.parse import ZmkKeymapParser, QmkJsonParser

# --- Parse a ZMK keymap file ---
config = Config()
with open("config/cradio.keymap", "rt", encoding="utf-8") as f:
    parsed_keymap = ZmkKeymapParser(
        config.parse_config,
        columns=10,           # group keys into rows of 10
        layer_names=None,     # use names from firmware
        virtual_layers=None,
    ).parse(f)

# Dump the parsed result to YAML
yaml.safe_dump(
    parsed_keymap,
    stream=open("cradio.yaml", "wt"),
    width=160,
    sort_keys=False,
    default_flow_style=None,
    allow_unicode=True,
)
```

--------------------------------

### Cols+Thumbs Notation Layout Specification

Source: https://context7.com/caksoylar/keymap-drawer/llms.txt

Define a keyboard layout using a compact notation string representing columns and thumb cluster key counts. Supports column shift modifiers.

```yaml
# Method 6: Cols+thumbs notation string
layout:
  cols_thumbs_notation: "33333+3 2+33331"
  # With column shift modifiers: v/d=down, ^/u=up, >/r=right, </l=left
  # cols_thumbs_notation: "2v333+2> 3+13332^ 33"
```

--------------------------------

### Draw SVG from Keymap Data using Python API

Source: https://context7.com/caksoylar/keymap-drawer/llms.txt

Render an SVG visualization from keymap data loaded from a YAML file. Optionally customize drawing configurations like dark mode, number of columns, and glyph sizes. The generated SVG content is written to a file.

```python
# --- Draw SVG from a keymap YAML ---
with open("cradio.yaml", "rt", encoding="utf-8") as f:
    keymap_data = yaml.safe_load(f)

# Optionally customize drawing config
draw_cfg_overrides = {"dark_mode": "auto", "n_columns": 2, "glyph_tap_size": 18}
config.draw_config = DrawConfig.parse_obj(
    config.draw_config.model_dump() | draw_cfg_overrides
)

output = StringIO()
drawer = KeymapDrawer(
    config=config,
    out=output,
    layers=keymap_data["layers"],
    layout=keymap_data["layout"],      # e.g. {"qmk_keyboard": "ferris/sweep"}
    combos=keymap_data.get("combos", []),
)
drawer.print_board()
svg_content = output.getvalue()

with open("cradio.svg", "wt", encoding="utf-8") as f:
    f.write(svg_content)
```

--------------------------------

### Parse Kanata config file to YAML

Source: https://context7.com/caksoylar/keymap-drawer/llms.txt

Parses a Kanata .cfg keyboard configuration file into the keymap YAML format. Supports specifying column count and custom layer names.

```sh
keymap parse -k ~/kanata/my_keyboard.cfg > kanata_keymap.yaml
```

```sh
keymap parse -c 10 -k my_keyboard.cfg --layer-names Base Nav Sym > kanata_keymap.yaml
```

--------------------------------

### Parametric Ortholinear Layout Specification

Source: https://context7.com/caksoylar/keymap-drawer/llms.txt

Define an ortholinear keyboard layout parametrically by specifying the number of rows, columns, and thumb cluster configuration.

```yaml
# Method 5: Parametric ortholinear layout
layout:
  ortho_layout:
    split: true
    rows: 3
    columns: 5
    thumbs: 3          # int, or "MIT" / "2x2u" for non-splits
    drop_pinky: false
    drop_inner: false
```

--------------------------------

### DTS Physical Layout Specification

Source: https://context7.com/caksoylar/keymap-drawer/llms.txt

Specify a keyboard layout using a ZMK devicetree (`.dtsi`) file. The `layout_name` parameter selects the specific layout definition within the DTS file.

```yaml
# Method 4: ZMK devicetree physical layout file
layout:
  dts_layout: my_keyboard-layouts.dtsi
  layout_name: my_keyboard_layout
```

--------------------------------

### ZMK Keyboard Layout Specification

Source: https://context7.com/caksoylar/keymap-drawer/llms.txt

Specify a keyboard layout using its ZMK name. The `layout_name` parameter is used to select a specific layout definition.

```yaml
# Method 2: ZMK keyboard name (resolved via internal lookup table)
layout:
  zmk_keyboard: corne
  layout_name: foostan_corne_5col_layout
```

--------------------------------

### Amending Triggering Commit with Keymap Drawer

Source: https://github.com/caksoylar/keymap-drawer/blob/main/README.md

Configure the keymap-drawer workflow to amend the triggering commit instead of creating a new one. The `amend_commit: true` option is used, and the `commit_message` input is ignored.

```yaml
jobs:
  draw:
    uses: caksoylar/keymap-drawer/.github/workflows/draw-zmk.yml@main
    with:
      amend_commit: true
      # …other inputs
```

--------------------------------

### Custom SVG Glyphs with Remote Icon Sources

Source: https://context7.com/caksoylar/keymap-drawer/llms.txt

Embed icons from popular libraries directly into your keymap legends using the `$$source:id$$` syntax. Fetched SVGs are cached locally for performance.

```APIDOC
## Custom SVG Glyphs with Remote Icon Sources

Use the `$$source:id$$` syntax in any legend field (`tap`, `hold`, `shifted`, `left`, `right`, `tl`, `tr`, `bl`, `br`) to embed icons fetched from popular icon libraries. Fetched SVGs are cached locally.

```yaml
layers:
  Media:
    # Material Design Icons (mdi / mdil)
    - $$mdi:volume-mute$$
    - $$mdi:volume-plus$$
    - $$mdil:brightness-6$$

    # Google Material Symbols (use Android tab value)
    - $$material:settings$$

    # Tabler Icons (outline style)
    - $$tabler:player-play$$

    # Phosphor Icons (weight/name)
    - $$phosphor:bold/lock$$
    - $$phosphor:regular/keyboard$$

    # Font Awesome (type/name)
    - $$fa:brands/apple$$
    - $$fa:solid/star$$

    # Hold-tap with SVG glyph in tap position
    - {h: Media, t: $$mdi:play-pause$$}

    # Custom inline glyph defined in draw_config.glyphs
    - $$vol_up$$

draw_config:
  glyph_tap_size: 18      # height in px for tap-position glyphs
  glyph_hold_size: 12     # height in px for hold-position glyphs
  glyph_shifted_size: 10  # height in px for shifted-position glyphs
  use_local_cache: true   # cache downloaded SVGs locally
```
```

--------------------------------

### Generate SVG Keymap

Source: https://github.com/caksoylar/keymap-drawer/blob/main/README.md

Generates an SVG representation of the keymap from a YAML file. The output is redirected to an SVG file. This command uses the layout information within the YAML file.

```sh
keymap draw sweep_keymap.yaml >sweep_keymap.ortho.svg
```