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.
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 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
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
Dimensions of combo boxes that are drawn on layer diagrams.
Type: float
Default: 28, 26
Curvature of rounded key rectangles, used both for key and combo boxes
Type: float
Default: 6
Turn on dark mode which applies the CSS overrides in svg_style_dark config.
Setting it to "auto" enables adapting to the web page or OS light/dark theme setting.
Type: bool | "auto"
Default: false
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
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
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
The amount of padding between adjacent keys, in two axes.
Type: float
Default: 2, 2
Padding amount between layer diagrams, in two axes.
Type: float
Default: 30, 56
Spacing between multi-line text in key labels in units of em.
Type: float
Default: 1.2
Radius of the curve for combo dendrons that are drawn from the combo box to the key positions.
Type: float
Default: 6
Whether to add a colon after layer name while printing the layer header.
Type: bool
Default: true
Padding from edge of a key representation to top ("shifted"), bottom ("hold"), "left" and "right" legends.
Type: float
Default: 2
Position of center ("tap") and "left"/"right" key legends 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" on key representations, which can be made to look like keycap profiles.
The shape is determined by key_side_pars.
Type: bool
Default: false
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_style_dark1
The set of CSS overrides that are added when dark_mode is enabled, and conditionally added with @media (prefers-color-scheme: dark) when it is "auto".
Type: string
Default: See config.py
Extra CSS that will be appended to svg_style, enabling augmenting and overriding properties.
Type: string
Default: Empty
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 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
Detect layer names in legends and style them specially: By default they are underlined and
link to the corresponding layer. Styling can be customized using the layer-activator CSS class.
Type: bool
Default: true
Height in px for SVG glyphs, in different key fields.
Type: int
Default: 14, 12, 10
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
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.
Run C preprocessor on ZMK keymaps.
Type: bool
Default: true
Do not do any keycode/binding parsing (except as specified by raw_binding_map).
Type: bool
Default: false
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: {}
Display text to place in hold field for sticky/one-shot keys.
Type: str
Default: "sticky"
Display text to place in hold field for toggled keys.
Type: str
Default: "toggle"
Display text to place in hold field for tap-toggle (TT) keys.
Type: str
Default: "tap-toggle"
Legend to output for transparent keys.2
Type: str | dict
Default: {"t": "▽", "type": "trans"}
For layer names specified, replace their representation on keys with the specified string.
The layer names should match the form that they would normally be displayed as, i.e. the
provided names if keymap parse --layer-names is used, otherwise the layer names inferred during parsing.
Type: dict[str, str]
Default: {}
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).
The additional keys that are added by enabling this option get the key type "held alternate",
so that you can override their styling in svg_extra_style with CSS selector .held.alternate.
Type: bool
Default: false
Convert modifiers in modifier functions (used in keycodes with built-in modifiers like LC(V)
in ZMK or LCTL(KC_V) in QMK) to given symbols -- set to null to disable the mapping. Valid fields:
-
left_ctrl,right_ctrl,left_shift,right_shift,left_alt,right_alt,left_gui,right_gui(type:str): Mapping of each modifier to their corresponding display forms.Default:
"Ctl","Ctl","Sft","Sft","Alt","AGr","Gui","Gui" -
keycode_combiner(type:str): Pattern to join modifier functions with the modified keycode, must contain{mods}and{key}.Default:
"{mods}+ {key}" -
mod_combiner(type:str): Pattern to join multiple modifier function strings, must contain{mod_1}and{mod_2}.Default:
"{mod_1}+{mod_2}" -
special_combinations(type:dict[str, str]): Special look-up for combinations of mods, mod order is ignored. Keys must be modifier names joined by+.Default:
{"left_ctrl+left_alt+left_gui+left_shift": "Hyper", "left_ctrl+left_alt+left_shift": "Meh"}
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_"]
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
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: []
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
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: {}
A string to prepend to ZMK keymaps before parsing that can be used to influence the parsed content.
Also used for parsing DTS format physical layouts specified with --dts-layout.
The default defines a KEYMAP_DRAWER symbol which can be used for checks with preprocessor directives.
Type: string
Default: "#define KEYMAP_DRAWER"
A list of paths to add as search paths to the preprocessor for #include directives.
This can be needed if you use Zephyr modules such as zmk-helpers since they require augmenting the search path.
Also used for parsing DTS format physical layouts specified with --dts-layout.
Type: list[str]
Default: []