v0.11.0: New drawing features

This release introduces a few major drawing features, automated ZMK workflow improvements and a major internal refactor to improve the project structure.

Features

• Multiple output columns!

  • Set the draw_config.n_columns variable to e.g. 3 to output with three layer columns

  

• Separate combo diagrams! For those of you who use thumb+alpha combos or steno-like keymaps, there is now the option
  to draw each combo in a separate minified layer diagram, showing the output key and the triggering key positions.

  • Set draw_config.separate_combo_diagrams: true to enable, and draw_config.combo_diagrams_scale to tweak the scaling factor (default 2)
  • Currently the layers property of the combos are ignored and not visualized, might be added in the future if there is a clean way to show it
  • Key corner radii are currently not scaled, so the keys will look rounder for higher scale factors

  

• Add key sides to drawn keys to give a keycap "profile" appearance, by @riccardoflp

  • draw_config.draw_key_sides: true to enable, tweak the appearance via draw_config.key_side_pars
  • Currently may not render well on Safari, looking into workarounds

  

Fixes

• Sort SVG glyph defs before writing to avoid non-deterministic output
• Tweak Tabler-related CSS to hide the outline boxes in Safari, by @bryanforbes
• Fix font size issue in hold/shifted fields due to draw_config.shrink_wide_legends, by inxi (at MoErgo Discord)
• Fix issue creating unnecessarily long dendrons for certain combo types

ZMK drawing workflow

• Add option to amend the last commit and also commit parse output YAML, by @minusfive
• Recursively checkout the repo to support git submodules like zmk-nodefree-config, by @shroomist

Misc

• Tweak classes for output SVG elements to allow for better customization via CSS
  • Assign key/combo classes to rect+text elements for layout keys/combos
  • Assign keypos-N/combopos-N classes to key/combo elts. to allow addressing via position index N
• Add a proper physical layout for slicemk_ergodox, by @xudongzheng
• Round SVG coordinate/size values for better readability and smaller output size, by @art4ride and me

Note that future updates might unfortunately include more CSS changes, such as converting to the descendants selector syntax, e.g. .held rect { ... } from rect.held { ... }. Thanks to the folks at LowProKB and MoErgo for helpful discussions.

I will also prioritize a better documentation organization in the short term, possibly hosted on Github pages.

Full Changelog: v0.10.0...v0.11.0

v0.10.0: ZMK matrix transforms and more

This release adds support for parsing alternative matrix transforms in ZMK like five_column_transform for Corne variants and other improvements.

Also check out the new "Community" section for nice projects using keymap-drawer to get inspired from!

Features

• Add ability to parse selected ZMK matrix transforms in a chosen node and update ZMK layout mappings to support different matrix-transform-to-physical-layout mappings
• Breaking change: Convert draw_config.arc_scale config param to be a per-combo setting instead of a global parameter
• Change the default styling of ghost keys to have a dashed outline rather than a dark gray fill
  • You can restore it to the old style in draw_config.svg_style if needed
• Make params of &bt such as BT_SEL mappable in parse_config.zmk_keycode_map by @minusfive in #28
  • Warning: This will be refactored and these parameters will likely be supported under a different section soon, and zmk_keycode_map be reserved for keycodes only
• Add a new -g/--ghost-keys option to keymap draw to programmatically assign type: ghost to given key positions before drawing

Fixes

• Devicetree parser now uses the last value if a property is defined multiple times, like Zephyr
• Devicetree parser no longer fails with parse_config.preprocess: false

Misc

• The web app code is moved to a different project, https://github.com/caksoylar/keymap-drawer-web
  • As a result the Streamlit URL changed as well; note that https://caksoylar.github.io/keymap-drawer will always redirect to the latest, so I encourage using that link
• Overhaul examples to use more combo-related features and SVG glyphs
• Add and use lily58_rotated physical layout with properly rotated thumb keys, by @Nicell
• Default to corne_rotated physical layout for all Corne variants
• Add mappings for custom shields in https://github.com/JonMuller/gerbers, lpgalaxy_war_driver, lpgalaxy_blank_slate, technikable and a few more
• Improve physical layouts coverage for boards/shields in the ZMK repo

Full Changelog: v0.9.0...v0.10.0

v0.9.0: Improved ZMK parsing addendum

This release builds upon v0.8.0 to further improve ZMK parsing with conditional layers support and a bug fix.

Features

• Add conditional layers parsing for ZMK keymaps, so that held keys are automatically inferred for the target layers as well

Fixes

• Parse the built-in ZMK mod-morph &gresc

Misc

• For the reusable ZMK workflow: discover matching layout data in config/ by @nickcoutsos in #26
  • This is for config repos that have .json file(s) used by keymap-editor next to the keymap files: the drawing workflow will automatically use that file for determining the physical layout
• Fix adv360 layout definition to be consistent with upstream changes removing dummy key positions

New Contributors

• @nickcoutsos made their first contribution in #26

Full Changelog: v0.8.0...v0.9.0

v0.8.0: Improved ZMK parsing

This release has a few improvements mainly related to ZMK keymap parsing, including support for mod-morphs and custom sticky keys.

Features

• Refactored ZMK parsing to use compatible fields to determine nodes of interest
  • Previously we relied on other heuristics based on node names, which were usually satisfied by convention. Current approach emulates Zephyr's parsing so any keymap that works with ZMK should now be parsed correctly
  • The new dts.py module is a parser that can be used standalone for other ZMK-related projects
• Added parsing for mod-morphs, which assigns the morphed behavior to the shifted field
• Added parsing for custom sticky key behaviors, in addition to the built-ins &sk/&sl
• Made hold-taps parse its bindings recursively (similar to the above two), so that its output is more accurate
  • Previously this also relied on heuristics that mostly worked for &kp/&kp and &mo/&kp hold-taps
• Added a new drawing config draw_config.shrink_wide_legends (enabled by default) to automatically shrink legends that are too wide
  • This is currently not designed ideally, since the optimal value depends on the font size and rect/combo box width. The default value should work well with other defaults, but it is not ideal for combo boxes. I thought it is still a good improvement but I will re-implement this if I can come up with a better way. Feedback is welcome!

Fixes

• Run the keys of parse_config.raw_binding_map through the preprocessor before using them (#11)
  • This fixes cases like raw_binding_map: {"&lt NUM ESC": "my hold-tap"} where NUM gets replaced by a preprocessor define

Full Changelog: v0.7.1...v0.8.0

v0.7.1

This is a bug fix release for the changes related to features introduced in v0.7.0.

Fixes

• Allow unicode characters in dumped YAMLs, e.g. to output ▽ instead of "\u25BD"
• Do not clear legends for held keys during keymap parsing unless it is transparent (#23)
  • Outputs for inferred held keys are now as it was before v0.7.0
• Increase compatibility of embedded custom SVGs with Inkscape 1.2.2 and before

Web app

• Expand the configuration section by default, to work around the issue where the configuration text box is occasionally empty

Full Changelog: v0.7.0...v0.7.1

v0.7.0: Custom SVG glyphs support

This is a large and overdue update, with various improvements to both parsing and drawing functionality. Highlight of this update is the ability to integrate custom SVG glyphs which can be automatically fetched from a number of fixed sources like Tabler or MDI.

Features

• Added the ability to use custom SVG glyphs as key legends by @lugoues, see the README section for details and showcase.yaml for an example
  • SVG glyphs can be defined in the draw_config.glyphs field of the configuration, or fetched from URLs
  • Four icon sources are currently supported for automated fetching with a short-hand, e.g. $$tabler:volume$$
  • Fetched SVGs are cached in a user cache folder to speed up consequent runs
• Added a slide field to the combo definitions to allow more flexible combo positioning, with expected value between -1 and 1
  • Changing this value "slides" the combo box along an axis between keys -- can be used for moving top/bottom combo boxes left/right, left/right boxes up/down, or mid combos between two keys
• keymap parse now outputs a symbol ▽ for transparent keys and assigns it a CSS class that grays out the legend by default
  • Configurable via parse_config.trans_legend value
• Added a reusable Github workflow to automatically generate keymap SVGs in ZMK user config repos
  • See the section in README on how to integrate to your own config repo

Fixes

• Fixed unnecessary drawing of combo arcs, which are usually hidden behind the combo box

Misc

• Added physical layouts for dao, glove80 and adv360, latter using the 84 binding transform used in the official config
• Added a devcontainer for development in VS Code, by @lugoues

New Contributors

• Various contributions detailed above by @lugoues
• @calumy made their first contribution in #19

Full Changelog: v0.6.0...v0.7.0

v0.6.0: Parsing improvements

This release focuses mostly on improvements to keymap parsing, to reduce the amount of manual tweaking necessary before drawing and better accomodate an end-to-end, parse-then-draw workflow.

Fixes

• Fixed layout size calculation so that the dimensions of drawn layers in the SVG are properly adjusted when using rotated keys

Features

• Made parsing smarter to automatically determine held keys using momentary layer keys on the keymap, so the user should no longer need to manually add type: held specs after parsing
  • Does not currently support the conditional layers feature in ZMK, or more than one way to activate the same layer
• Added a base keymap -b/--base-keymap parameter to keymap parse. This will make the parser try its best to copy your manual modifications from the base keymap to the updated one after parsing, including combo align and offset values and type specifiers in layer keys
• Added a -l/--layer-names parameter to keymap parse that lets you override layer names, especially useful for QMK parsing where there is no layer name information in the parse input json
• Added parse_config.zmk_combos configuration to let the user automatically augment the parse output for combos, specified by the node name in the ZMK keymap, e.g. combo_esc: {align: top, offset: 0.5}
• Added parse_config.sticky_label configuration to let the user change the "sticky" display text for sticky/one-shot keys

Misc

• Added a simple Github workflow for linting
• Added fingerpunch/ffkb and fingerpunch/luakeeb physical layouts

Looking forward, @lugoues is working on integrating custom SVG glyphs to be used a legends in the drawing output in #12 and #17 so users will no longer be limited to using unicode text and symbols!

Full Changelog: v0.5.0...v0.6.0

v0.5.0: ZMK physical layouts update

The highlight of this release is automatic physical layout detection for most ZMK keyboards, as determined by the keymap filename. For instance parsing corne.keymap will add a layout: {qmk_keyboard: crkbd/rev1, qmk_layout: LAYOUT_split_3x6_3} field to the output keymap YAML, so you won't have to manually specify it during keymap draw. (There is no support yet for determining the correct qmk_layout via the chosen matrix transform.)

To support more ZMK (and custom QMK) keyboards, I also started maintaining some extra physical layout definitions under the resources folder. If a qmk_keyboard name matches one of the files here then that will be used rather than checking QMK keyboards API. For example, if you use keymap draw -k corne_rotated instead of crkbd/rev1 you will get a Corne layout with nicely rotated thumb keys.

See the newly updated layout section in the keymap spec for details.

Features

• Automatically determine physical layouts for most ZMK keyboards during parsing
  • Mapped from keymap filename using the mapping file
  • Contributions welcome to add mappings for custom ZMK keyboards/shields!
• Add custom physical layout definitions for non-QMK-upstream keyboards
  • Maintained under resources/qmk_layouts
  • Contributions welcome to support more keyboards! See Keymap Layout Helper and other resources to help generate new layouts.
• Make qmk_keycode_map/zmk_keycode_map support key spec dicts (e.g. including hold or shifted fields), e.g. SLASH: {t: '/', shifted: '?'}
• Assign CSS class layer-<layer_name> to each layer so they can be styled individually through svg_style (thanks @manna-harbour!)

Full Changelog: v0.4.0...v0.5.0

v0.4.0: Rotation update

This release adds rotation center rx, ry support to QMK-format physical layouts, consistent with the handling of keymap-editor and Keymap Layout Helper (and KLE). Note that at the moment the default rotation center is key center if former are not specified, different from aforementioned tools which use top left corner, or 0, 0 origin that KLE uses (related issue).

There is also an important bug fix for parsing with the columns specifier and contributions by @jbarr21 for improved parsing of QMK keymaps (thanks!).

Fixes

• Fix keymap parse dumping when -c/--columns value is specified to a non-default value
• Ignore labels label: nodename when looking for keymap, behaviors etc. nodes in ZMK keymaps

Features

• Support rx, ry fields in QMK info.json for specifying the point around which the angle r will be used to rotate
• Replace underscores with spaces in unmapped QMK keys by @jbarr21 in #5
• Add parsing for QMK one-shot mods & layers by @jbarr21 in #4

New Contributors

• @jbarr21 made their first contribution in #5

Full Changelog: v0.3.0...v0.4.0

v0.3.0: Styling update

This update focuses on cleaning up the styling of the drawn elements by refactoring the CSS classes+other DrawConfig settings, and how the elements are assigned classes in the CSS. Thanks to @manna-harbour for significant contributions on the design and implementation!

Features

• Overhaul CSS classes and allow specifying custom key types
  • Make SVG classes used for <rect>'s and <text>'s better composable by splitting key types and label types
  • Remove literal restrictions from type field and add the same field to combo specs. This allows users to specify a custom type for keys/combos and define it in the CSS if they want to customize certain keys/combos.
  • This is a breaking change due to draw_config.svg_style being rewritten, along draw_config.line_spacing getting repurposed. If you have any existing configuration files you need to adapt them: See the changes in the default configuration here.
• Auto-align tap labels inside a key up/down to when it has 2 lines and either hold or shifted label is present
• Add a new config draw_config.append_colon_to_layer_header to be able to disable appending colons after layer names
• Darken default key outline by 5% to improve contrast

Web app

• Move to streamlit 0.18, update caching and button styling using new functionality
• Read example keymaps with a different method to reduce random loading problems at startup

Full Changelog: v0.2.0...v0.3.0