Wishlist for a "export keymap diagram"-type feature

[nickcoutsos]

I've gotten this request a few times, and it's a fair one. When using the keymap editor to reduce some of the manual effort (be that in looking up precise keycode names, manually fixing layer indices, or keeping bindings aligned) it makes sense to automate production of keymap diagrams as well.

Notable prior work here is keymap-drawer which has a lot of community buy-in and functionality. It's also worth noting, as it usually is when the feature request comes up, that it's entirely possible to integrate keymap-drawer's GitHub action into your repository to automatically generate diagrams when committing keymap changes via Keymap Editor (or manually as the case may be).

Keymap Editor can already render keymap data, but:

1. Generating diagrams server-side* would complicate things significantly due to extra dependencies needed to render HTML outside of a browser
   • Rendering SVG would help this and lends itself nicely to JSX but this would mean having an additional renderer to maintain and keep in sync.
2. The components used to render keymap data in the app are also coupled to components that handle editing. I've made a lot of progress recently that makes this unnecessary, but I still need to take the time to go in and properly separate things.

*I'm kind of focusing in on the GitHub integration because that's where automation makes the most sense. Image data could be generated client-side but I'm not OK with accepting arbitrarily large binary data to pipe through to a GitHub repo.

If I were to add a diagram output it would most likely be in the form of a standalone keymap parser and renderer that can be executed locally or via GitHub actions and would exist mainly to match the visual style of Keymap Editor.

That's great for rendering special symbols and RGB icons for layer binds, encoders, and combo diagrams, but what about things like macros and behaviors where there I don't really have a concise way to show just the important details? As a user what do you feel is "enough" information for your custom behaviors list? Or do you feel that your behaviors are "self documenting" already?

Please share any wishes or use cases you have! If nothing else, it helps to know that there's enough demand for something to make it a priority, but I'm eager to see some discussion.

[joshsurber]

The main things i personally need reminders about are single keys on seldom-used or extra full layers like symbols or bt settings. Just the actual keys would be good, though combos would be nice they are normally gonna be set to be more memorable, at least in my case. Honestly, I'm pretty good with the way everything displays in your tool which is why i thought of that before looking for a third party.

Another option would be to export json that could be read by http://keyboard-layout-editor.com/ which seems to be the standard for creating these images. Converting one data format to another is not as easy as it should be, but would be easier than generating images (though with svg i guess it's less of a hassle)

[nickcoutsos]

I hadn't considered the possibility of exporting to KLE, I think usually people are trying to import layout data from KLE into other tools. You're right, though, converting between formats is a challenge.

Some of it is that KLE has a really weird format, but in this particular case I think exporting from keymap editor would mean losing a lot of the flexibility that people may expect from it and still have a manual step to take the result and render.

[englmaxi]

A helpful feature would also be the possibility to give key combinations an alias. For example I use RA(N5) for the symbol "€" (US int layout). It would be nice to show "€" instead of "RA(5)" in the keyboard diagram.

Maybe this could be specified similar to 'info.json' in a separate file or as a comment, so preprocessor support would not be necessary.

[nickcoutsos]

Yeah... I do have some hesitations that aren't specific to this idea. One is that I'd rather avoid having the user create and maintain/synchronize multiple representations of the keymap (which is part of why I moved away from the keymap.json file), though I realize that this isn't quite that.

This would probably be worth a conversation of its own, if you're interested in starting a new discussion. I do see the use for a keymap export but at the same time, it would make sense to support the functionality in the app even without using that export.

Is RA(N5) something recognized from your operating system's keyboard input? Like RALT is AltGr? My understanding of keymaps for non North American locales is limited so having some more insight here would be super helpful. And, not to hyper focus on this one example but I do want make sure I'm leveraging existing solutions where possible, is this something that could be solved or partially solved via zmk-locale-generator?

I'm looking at the keys_us_international.h and seeing:

/* € */
#define USX_EURO (RA(ZMK_HID_USAGE(HID_USAGE_KEY, HID_USAGE_KEY_KEYBOARD_5_AND_PERCENT)))

If you're using the headers in your keymap and keymap editor is able to parse #include "keys_us_international.h" then it will add those symbols to the renderer already.

[englmaxi]

Is RA(N5) something recognized from your operating system's keyboard input? Like RALT is AltGr?

Yes exactly, my understanding is that RALT takes over the role of AltGr in most International layouts.

is this something that could be solved or partially solved via zmk-locale-generator?

I knew that zmk-locale-generator exists, but not that it is also supported by the keymap-editor. I just tested it out and it works great! Thanks for the suggestion!

Nevertheless, I find that the possibility to label some combinations could be helpful, e.g. for MEH and HYPER, although no longer as important.. :)

[nickcoutsos]

Hey, I was just looking at your repo and noticed the build failure. It looks like I had old data from zmk-locale-generator. I just pushed an update but you may need to either redo those bindings in the app or do a search and replace of USX_ with EN_ (I think it's just the prefix that changed) in the keymap code itself.

I've quietly had support for zmk-locale-generator headers for a little while now. I don't know enough about how well that works for people who actually need it for me to regard it as a real complete feature, but it is there. (now that you know about it, feel free to share your experiences)

I've seen requests for MEH/HYPER before as well, and I see it as a problem similar to custom preprocessor macros like AS(...) that are conventionally implemented the same way but can still be different enough that it won't work correctly for everyone. If MEH/HYPER get added to ZMK I can look at using that as a standard but otherwise I'd have to make sure it's not going to break things.

[paoloantinori]

Hi, thanks for your great project! Could you help me to better understand the code where you deal with zmk-locale-generator imports?
I'd like to undersand the strategy you are using to convert from a line like #define GB_B (ZMK_HID_USAGE(HID_USAGE_KEY, HID_USAGE_KEY_KEYBOARD_B)) to the correct b symbol.

I've looked around but it wasn't obvious to me. Would you be able to guide me?
thank you

[nickcoutsos]

That code isn't here, but I have a separate script that parses headers from zmk-locale-generator to generate additional keycodes. It's not dynamic, though, trying to support fetching files included by the keymap at runtime introduces huge complexity.

[paoloantinori]

I see, thanks. My hope was to add this support to keymap-drawer that at the moment doesn't support this and is quite unusable if those long defines are in use.

out of curiosity, what is the strategy you use?
just parsing the definition with a regexp and pick the last token after an underscore and before parenthesis?

[nickcoutsos]

It's even easier than that. If you're willing to do a little Python scripting the zmk_locale_generator package does most of the heavy lifting for you.

This gist is my script to create the metadata for my app, you can adapt it to generate a mapping suitable for your keymap-drawer config.

[pamitabh]

Hi I just got into this wonderful world of zmk! I mainly use keymap-editor to do all the zmk keymap editing. Yes, keymap-drawer can be integrated into github actions but that's an additional step.

As keymap-editor is already a gui/browser app, wouldn't it be possible to add a simple option to just export the displayed keymaps? I like the the keymap-editor's gui very much and like the behaviors displayed in tiny text (eg. '&mt' etc.) Maybe also add a opt-in option to save the screenshots/rendered images to the github repo while committing the changes.