Layer documentation is unclear

[notfed]

The layer documentation [1] does not clearly explain how layers are numbered. Also, it seems to give conflicting information: it explicitly gives a metaphor of layers as numbered by "[reverse-indexed] top-to-bottom" [1], but then the very first example of a keymap uses the exact opposite order with no clarification. [2]

For example: since the "layers" page is where users will go to if they're confused about how to define layers, it would help to say something like:

Layers will be automatically assigned numbers, beginning with 0 (usually referred to as the 'default layer'), and increasing sequentially by 1 in the order they are defined in the keymap file. <<It would also help to clarify again the confusing fact that layers must be defined in the opposite order as was just explained in [1]>>

But AFAICT no such explanation exists, and so the ZMK user is left to head scratching and assumptions based off the very small number of examples.

And regarding the examples: consider that this is the official ZMK "Layers" documentation, and it gives only a measly 2-layer example. Adding an example with 3 or more will drive home the fact that layers are sequentially ordered; something that I, as a new ZMK user setting up a board for the first time, am still confused about.

[1] https://zmk.dev/docs/features/keymaps [2] https://zmk.dev/docs/behaviors/layers

[butterdori]

This is helpful. I couldn't find out how ZMK found the correct layer. Thanks to you, it seems that they are referred to in the order they are written out in the keymap, and therefore the order of the layers in the keymap is important. I agree that an example with more than 3 layers would be more helpful.

[zaddok]

I am here from google, because the documentation is unclear. More examples would indeed be helpful.

[Auxnon]

Seconded, this is the first place I've found that clarified that the naming in the keymap file for layers is arbitrary and it's the order named that dictates their layer index. I was under the impression the layer name had to be defined elsewhere and couldn't find it. An example with 4 or more layers and clarifying this concept would be appreciated.

[tilliwilli]

Just to add something I just realized, coming from kmonad: In ZMK the layer ordering is fixed meaning you can't overlay e.g. your layer 1 over your layer 2 (using the "official" layer numbers here) in any way (by &mo'ing it from layer 2 or something).

In kmonad, when you activate a layer (either temporarily while holding a key or permanently toggling it on), it's put on top of the active layer stack, regardless of where it was defined or in which order. So I could have layer A on top of layer B or vice versa, just depending on the order I activate them. In ZMK, my layer 2 will always be on top of my layer 1 when both are active, and there is no way to change that. So if I want to be able to put both layer 1 on top of layer 2 and vice versa, I need to duplicate my layer 1 to at least number 3 and then be smart about where to put which &lt/&mo/….

The documentation does not make that clear at all, but that just might be me with the kmonad knowledge.

PS: QMK is apparently the same as ZMK when it comes to this topic, but at least they are very explicit about it: https://docs.qmk.fm/#/feature_layers?id=beginners

[totkeks]

Came here because I was looking for more layer information as well. :D

This might be a separate issue / feature request. Wouldn't it help if behaviors like &mo could reference labels by name/label? The example using defines isn't really articulate about the fact, that those defines have to be kept in sync with the order of the layers in the keymap tree.

Like when I change the order of my layers or add a new one between existing ones.

[joelspadin]

Wouldn't it help if behaviors like &mo could reference labels by name/label?

It would, but that's not possible with the devicetree format, at least not without requiring something like

/ { 
  behaviors {
    mo_nav: mo_nav {
      compatible = "zmk,behavior-momentary-layer";
      #binding-cells = <0>;
      layer = <&nav>;
    };
    mo_media: mo_media {
      compatible = "zmk,behavior-momentary-layer";
      #binding-cells = <0>;
      layer = <&media>;
    };
  };
  
  keymap {
    compatible = "zmk,keymap";
    default_layer {
      bindings = <&mo_nav &mo_media>;
    };
    nav: nav_layer {
      bindings = <&trans &kp HOME>;
    };
    media: media_layer {
      bindings = <&kp C_PLAY_PAUSE &trans>;
    };
  };
};

where you'd have to manually define a new behavior for each layer you want to go to. The parameters following a behavior in a bindings list can only be numbers.