v0.18.0: ZMK modules support and layer key styling

[caksoylar]

This release adds support for parsing ZMK configs that use modules like zmk-helpers with additional config options, along with adding special styling to layer key legends and making them clickable.

Edit: zmk-helpers now have docs on using keymap-drawer with it using below changes.

Features

Drawing

• Breaking change: Add new config option draw_config.style_layer_activators which defaults to true. This marks layer activators legends by adding a link that goes to the corresponding layer (might not work for embedded SVGs), and adding an underline by default.

  • If you want to restore the old behavior, this setting can be disabled in the config file: draw_config: { style_layer_activators: false }
  • You can change the styling, e.g. if you want italic instead of underlined:

    draw_config:
      svg_extra_style: |
        text.layer-activator { text-decoration: none; font-style: italic }

• Add a new CSS class alternate so you can define separate styling for extra activators marked by the parse_config.mark_alternate_layer_activators config (no styling defined by default) (Feature request: Display multiple keys that could activate a layer #98)

  • Example:

    parse_config:
      mark_alternate_layer_activators: true
    draw_config:
      svg_extra_style: |
        rect.held.alternate { fill: #478583; }
        @media (prefers-color-scheme: dark) { rect.held.alternate { fill: #478583; } }  # some other color here

• Add hidden property to the combo spec, so you can avoid drawing certain combos that the parser outputs by adding hidden: true (for instance through parse_config.zmk_combos) (Feature request: toggle rendering in ComboSpec #104)

  • Example:

    parse_config:
      zmk_combos: 
        combo_esc: { hidden: true }

• Support using underscore instead of space as split separator for the cols+thumbs notation spec in order to reduce command line quoting issues

  • Example: keymap draw -n 33333+2_3+233331 my_asymmetric_keymap.yaml

• Implement support for layout_aliases in qmk_keyboard physical layout definitions

Parsing

• Add parse_config.zmk_additional_includes to augment the preprocessor include path (allow additional includes to be specified in the parse config #105)
  • This can be used to be able to parse keymaps using zmk-helpers using the module functionality, since #includes aren't using relative paths in that case. Example:

    parse_config:
      zmk_additional_includes: [ "zmk-helpers/include" ]

  • If you want to use it in the automated ZMK drawing workflow, use the new west_config_path argument to the workflow (Feature/add west config path to workflow #107) so that the modules defined in the west.yml file are automatically fetched. (You still need the above value in the config.) Example:

    jobs:
      draw:
        uses: caksoylar/keymap-drawer/.github/workflows/draw-zmk.yml@main
        permissions:
          contents: write  # allow workflow to commit to the repo
        with:
          [...]
          west_config_path: 'config'  # this folder contains west.yml with module definitions

  • Module fetching is not (yet) supported in the ZMK URL parse option of the web app
• Add parse_config.zmk_preamble config option which is text inserted at the beginning of the keymap, usually used to modify preprocessor behavior. It defaults to #define KEYMAP_DRAWER (Allow me to pass custom preprocessor flags to the "keymap" CLI #103)
  • The default value exposes the existing behavior which was being defined internally before this change
• Restore support for using modified keycodes like LC(LEFT) in parse_config.*_keycode_map that was removed in v0.16 (Bug(?): LS(LC(LALT)) type mappings in zmk_keycode_map stopped working #106)

Fixes

• More robust devicetree parsing because of a few fixes involving parsing phandle arrays, such as when elements can have commas or split to multiple <...>, <...>; blocks (Can't map "&rgb_ug RGB_COLOR_HSB(0, 0, 60)" using "raw_binding_map" on the config #102)
• More robust QMK keymap.json parsing, for cases where the keycodes can contain extra spaces

Misc

• Add a physical layout definition for hummingbird keyboard
• For unibody keyboards like fingerpunch/ffkb and rufous, change the default physical layout to avoid all keys being rotated. This should improve readability by sacrificing faithfulness to the actual layout
  • The older rotated versions are available using fingerpunch/ffkb_rotated and rufous_rotated

Full Changelog: v0.17.0...v0.18.0

---

This discussion was created from the release v0.18.0: ZMK modules support and layer key styling.