Configuration options
April 9, 2024 · View on GitHub
This page details the configuration options available for parsing and drawing, which can be provided to the CLI or can be set in the web UI in the "Configuration" box. Also see the customization section in the README for usage.
Draw Configuration
These settings are nested under the draw_config field and applies to keymap draw subcommand in the CLI, as well as the conversion from keymap YAML input to SVG in the web app.
In addition to the configuration file, this field can also be set in the keymap YAML which overrides the former.
key_w, key_h
Key dimensions. Non-ortho layouts (e.g. via qmk_keyboard) use key_h for both width and height, whereas ortho_layout and cols_thumbs_notation use both.
Type: float
Default: 60, 56
split_gap
The gap between two halves of a split keyboard, only used for physical layouts specified via ortho_layout and cols_thumbs_notation.
Type: float
Default: 30
combo_w, combo_h
Dimensions of combo boxes that are drawn on layer diagrams.
Type: float
Default: 28, 26
key_rx, key_ry
Curvature of rounded key rectangles, used both for key and combo boxes
Type: float
Default: 6
n_columns
Number of layer columns in the output drawing. For example if this is set to 2, two layers will be shown side-by-side and layers will go right then down.
Type: int
Default: 1
separate_combo_diagrams
When set, visualize combos using separate mini-layout diagrams rather than drawing them on layers.
This sets the default behavior, which can be overridden by the draw_separate field of the ComboSpec.
Type: bool
Default: false
combo_diagrams_scale
For combos visualized separate from layers, this is the scale factor for the mini-layout used to show their key positions.
Type: int
Default: 2
inner_pad_w, inner_pad_h
The amount of padding between adjacent keys, in two axes.
Type: float
Default: 2, 2
outer_pad_w, outer_pad_h
Padding amount between layer diagrams, in two axes.
Type: float
Default: 30, 56
line_spacing
Spacing between multi-line text in key labels in units of em.
Type: float
Default: 1.2
arc_radius
Radius of the curve for combo dendrons that are drawn from the combo box to the key positions.
Type: float
Default: 6
append_colon_to_layer_header
Whether to add a colon after layer name while printing the layer header.
Type: bool
Default: true
small_pad
Padding from edge of a key representation to top ("shifted") and bottom ("hold") legends.
Type: float
Default: 2
legend_rel_x, legend_rel_y
Position of center ("tap") key legend relative to the center of the key.
Can be useful to tweak when draw_key_sides is used.
Type: float
Default: 0, 0
draw_key_sides
Draw "key sides" on key representations, which can be made to look like keycap profiles.
The shape is determined by key_side_pars.
Type: bool
Default: false
key_side_pars
A mapping of certain field names to their values, characterizing key side drawing. Valid fields:
rel_x,rel_y(type:float): Position of internal key rectangle relative to the center of the key. Default:0,4rel_w,rel_y(type:float): Delta dimension between external key rectangle and internal key rectangle. Default:12,12rx,ry(type:float): Curvature of the rounded internal key rectangle. Default:4,4
svg_style1
The CSS used for the SVG styling. This includes font settings, styling of key and combo rectangles and texts within them, along with some tweaks for external SVG glyphs.
Users are encouraged to not change the default value and use svg_extra_style to specify overrides instead.
Type: string
Default: See config.py
svg_extra_style
Extra CSS that will be appended to svg_style, enabling augmenting and overriding properties.
Type: string
Default: Empty
footer_text
Footer text that will be displayed at the bottom of the drawing, right aligned.
The value will be placed inside <text> tags and can have certain SVG elements in it.
Type: string
Default: Empty
shrink_wide_legends
Shrink font size for legends wider than this many chars, set to 0 to disable.
Ideal value depends on the font size defined in svg_style/svg_extra_style and width of the boxes.
Type: int
Default: 7
glyph_tap_size, glyph_hold_size, glyph_shifted_size
Height in px for SVG glyphs, in different key fields.
Type: int
Default: 14, 12, 10
glyphs
Mapping of glyph names to be used in key fields to their SVG definitions.
Type: dict[str, str]
Default: Empty
glyph_urls1
Mapping of sources to (possibly templated) URLs for fetching SVG glyphs.
For instance, $$material:settings$$ will use the value for material and replace {} in the value with settings.
Type: dict[str, str]
Default: See config.py
use_local_cache1
Use a local filesystem cache on an OS-specific location for downloaded QMK keyboard jsons and SVG glyphs.
Type: bool
Default: true
Parse configuration
These settings are nested under the parse_config field and applies to keymap parse subcommand in the CLI, as well as the conversion from "Parse from..." input forms to the keymap YAML text area in the web app.
preprocess
Run C preprocessor on ZMK keymaps.
Type: bool
Default: true
skip_binding_parsing
Do not do any keycode/binding parsing (except as specified by raw_binding_map).
Type: bool
Default: false
raw_binding_map
Convert raw keycode/binding strings specified as keys to the representations given by their values.2
If a conversion was made, shortcut any further processing.
E.g. {"QK_BOOT": "BOOT", "&bootloader": "BOOT"}.
Type: dict[str, str | dict]
Default: {}
sticky_label
Display text to place in hold field for sticky/one-shot keys.
Type: str
Default: "sticky"
toggle_label
Display text to place in hold field for toggled keys.
Type: str
Default: "toggle"
tap_toggle_label
Display text to place in hold field for tap-toggle (TT) keys.
Type: str
Default: "tap-toggle"
trans_legend
Legend to output for transparent keys.2
Type: str | dict
Default: {"t": "▽", "type": "trans"}
mark_alternate_layer_activators
Rather than only marking the first sequence of key positions to reach a layer as "held", mark all of the sequences to reach a given layer. this is disabled by default because it creates ambiguity: you cannot tell if all the marked keys need to be held down while a layer is active (which is the default behavior) or any of them (with this option).
Type: bool
Default: false
qmk_remove_keycode_prefix
Remove these prefixes from QMK keycodes before further processing.
Can be augmented with other locale prefixes, e.g. "DE_" for German locale headers.
Type: list[str]
Default: ["KC_"]
qmk_keycode_map
Mapping to convert QMK keycodes to their display forms, applied after removing prefixes in qmk_remove_keycode_prefix.2
Type: dict[str, str | dict]
Default: See config.py
zmk_remove_keycode_prefix
Remove these prefixes from ZMK keycodes before further processing.
Can be augmented with other locale prefixes, e.g. "DE_" for German locale headers generated by zmk-locale-generator.
Type: list[str]
Default: []
zmk_keycode_map
Mapping to convert ZMK keycodes to their display forms, applied after removing prefixes in zmk_remove_keycode_prefix.2
Type: dict[str, str | dict]
Default: See config.py
zmk_combos
Mapping to augment the output field for parsed combos. The key names are the devicetree node names for
combos in the keymap and the value is a dict containing fields from the ComboSpec.
E.g. {"combo_esc": {"align": "top", "offset": 0.5}} would add these two fields to the output for combo that has node name combo_esc.
Type: dict[str, dict]
Default: {}