zephyr
/
zmk
mirror of https://github.com/zmkfirmware/zmk.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

feat(leader-key): Update docs

This commit is contained in:
Nick Conway 2025-06-16 12:32:37 -04:00
parent 9bed79a543
commit ee4a63be8f
No known key found for this signature in database
GPG Key ID: AA850592E4C1D453
6 changed files with 60 additions and 155 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
docs/docs/config/leader.md
View File

@ -3,7 +3,7 @@ title: Leader Configuration
sidebar_label: Leader
---
See the [Leader feature page](../features/leader.md) for more details and examples.
See the [Leader key behavior page](../keymaps/behaviors/leader-key.md) for more details and examples.
See [Configuration Overview](index.md) for instructions on how to change these settings.
@ -11,30 +11,11 @@ See [Configuration Overview](index.md) for instructions on how to change these s
Definition file: [zmk/app/Kconfig](https://github.com/zmkfirmware/zmk/blob/main/app/Kconfig)
| Config | Type | Description | Default |
| ----------------------------------------- | ---- | ----------------------------------------------------------------- | ------- |
| `CONFIG_ZMK_LEADER_MAX_KEYS_PER_SEQUENCE` | int | Maximum number of leader sequences that use the same key position | 4 |
| `CONFIG_ZMK_LEADER_MAX_SEQUENCES_PER_KEY` | int | Maximum number of keys to press to activate a leader sequence | 5 |
| Config | Type | Description | Default |
| ----------------------------------------- | ---- | --------------------------------------------------- | ------- |
| `CONFIG_ZMK_LEADER_MAX_KEYS_PER_SEQUENCE` | int | Maximum number of key positions per leader sequence | 4 |
| `CONFIG_ZMK_LEADER_MAX_SEQUENCES_PER_KEY` | int | Maximum number of sequences allowed per leader key | 5 |
`CONFIG_ZMK_LEADER_MAX_KEYS_PER_SEQUENCE` sets the maximum length of a leader sequence.
If `CONFIG_ZMK_LEADER_MAX_SEQUENCES_PER_KEY` is 5, you can have 5 separate leader sequences that start with position `0`, 5 leader sequences that start with position `1`, and so on.
## Devicetree
Applies to: `compatible = "zmk,leader-sequences"`
Definition file: [zmk/app/dts/bindings/zmk,leader-sequences.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/dts/bindings/zmk%2Cleader-sequences.yaml)
The `zmk,leader-sequences` node itself has no properties. It should have one child node per leader sequence.
Each child node can have the following properties:
| Property | Type | Description | Default |
| ------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `bindings` | phandle-array | A [behavior](../features/keymaps.md#behaviors) to run when the leader sequence is triggered | |
| `key-positions` | array | A list of key position indices for the keys which should trigger the leader sequence | |
| `immediate-trigger` | bool | Triggers the leader sequence when all keys are pressed instead of waiting for the timeout (only applicable when one leader sequence overlaps another) | false |
| `layers` | array | A list of layers on which the leader sequence may be triggered. `-1` allows all layers. | `<-1>` |
The `key-positions` array must not be longer than the `CONFIG_ZMK_LEADER_MAX_KEYS_PER_SEQUENCE` setting, which defaults to 4. If you want a leader sequence that triggers when pressing 5 keys, then you must change the setting to 5.
If `CONFIG_ZMK_LEADER_MAX_SEQUENCES_PER_KEY` is 5, you can have up to 5 separate leader sequences each for each leader key.

39
docs/docs/features/leader.md
View File

@ -1,39 +0,0 @@
---
title: Leader Sequences
---
## Summary
Leader sequences are a way to have a sequence of key presses to output a different key. For example, you can hit the leader key followed by Q, then W to output escape.
### Configuration
Leader sequences configured in your `.keymap` file, but are separate from the `keymap` node found there, since they are processed before the normal keymap. They are specified like this:
```
/ {
leader_sequences {
compatible = "zmk,leader-sequences";
seq_esc {
key-positions = <0 1>;
bindings = <&kp ESC>;
};
};
};
```
- The `compatible` property should always be `"zmk,leader-sequences"` for leader sequences.
- `key-positions` is an array of key positions. See the info section below about how to figure out the positions on your board.
- `layers = <0 1...>` will allow limiting a sequence to specific layers. This is an _optional_ parameter, when omitted it defaults to global scope.
- `bindings` is the behavior that is activated when all the key positions are pressed.
- (advanced) you can specify `immediate-trigger` if you want the sequence to be triggered as soon as all key positions are pressed. The default is to wait for the leader key's timeout to trigger the sequence if it overlaps another.
:::info
Key positions are numbered like the keys in your keymap, starting at 0. So, if the first key in your keymap is `Q`, this key is in position `0`. The next key (possibly `W`) will have position 1, etcetera.
:::
### Advanced usage
See [leader configuration](/docs/docs/config/leader.md) for advanced configuration options.

55
docs/docs/intro.md
View File

@ -1,55 +0,0 @@
---
title: Introduction to ZMK
sidebar_label: Introduction
slug: /
---
ZMK Firmware is an open source (MIT) keyboard
firmware built on the [Zephyr™ Project](https://zephyrproject.org/) Real Time Operating System (RTOS). ZMK's goal is to provide a modern, wireless, and powerful firmware free of licensing issues.
## Features
ZMK is currently missing some features found in other popular firmware. This table compares the features supported by ZMK, BlueMicro and QMK:
| Legend: | ✅ Supported | 🚧 Under Development | 💡 Planned |
| :------ | :----------- | :------------------- | :--------- |
| **Feature** | ZMK | BlueMicro | QMK |
| ---------------------------------------------------------------------------------------------------------------------------------- | :-: | :-------: | :-: |
| Low Latency BLE Support | ✅ | ✅ | |
| Multi-Device BLE Support | ✅ | | |
| [USB Connectivity](behaviors/outputs.md) | ✅ | ✅ | ✅ |
| User Configuration Repositories | ✅ | | |
| Split Keyboard Support | ✅ | ✅ | ✅ |
| [Keymaps and Layers](behaviors/layers.md) | ✅ | ✅ | ✅ |
| [Hold-Tap](behaviors/hold-tap.mdx) (which includes [Mod-Tap](behaviors/mod-tap.md) and [Layer-Tap](behaviors/layers.md#layer-tap)) | ✅ | ✅ | ✅ |
| [Tap-Dance](behaviors/tap-dance.mdx) | ✅ | ✅[^2] | ✅ |
| [Keyboard Codes](codes/index.mdx#keyboard) | ✅ | ✅ | ✅ |
| [Media](codes/index.mdx#media-controls) & [Consumer](codes/index.mdx#consumer-controls) Codes | ✅ | ✅ | ✅ |
| [Encoders](features/encoders.md) | ✅ | ✅ | ✅ |
| [Display Support](features/displays.md)[^1] | 🚧 | 🚧 | ✅ |
| [RGB Underglow](features/underglow.md) | ✅ | ✅ | ✅ |
| [Backlight](features/backlight.mdx) | ✅ | ✅ | ✅ |
| One Shot Keys | ✅ | ✅ | ✅ |
| [Combo Keys](features/combos.md) | ✅ | | ✅ |
| [Macros](behaviors/macros.md) | ✅ | ✅ | ✅ |
| [Leader Key](behaviors/leader-key.md) | ✅ | | ✅ |
| Mouse Keys | 🚧 | ✅ | ✅ |
| Low Active Power Usage | ✅ | | |
| Low Power Sleep States | ✅ | ✅ | |
| [Low Power Mode (VCC Shutoff)](behaviors/power.md) | ✅ | ✅ | |
| Battery Reporting | ✅ | ✅ | |
| Shell over BLE | 💡 | | |
| Realtime Keymap Updating | 💡 | | ✅ |
| AVR/8 Bit | | | ✅ |
| [Wide Range of ARM Chips Supported](https://docs.zephyrproject.org/3.5.0/boards/index.html) | ✅ | | |
[^2]: Tap-Dances are limited to single and double-tap on BlueMicro
[^1]: OLEDs are currently proof of concept in ZMK.
## Code of Conduct
Please note that this project is released with a
[Contributor Code of Conduct](https://www.contributor-covenant.org/version/2/0/code_of_conduct/).
By participating in this project you agree to abide by its terms.

1
docs/docs/intro.mdx
View File

@ -63,6 +63,7 @@ Below table lists major features/capabilities currently supported in ZMK, as wel
| [Sticky (One Shot) Keys](keymaps/behaviors/sticky-key.md) | ✅ |
| [Combos](keymaps/combos.md) | ✅ |
| [Macros](keymaps/behaviors/macros.md) | ✅ |
| [Leader Key](keymaps/behaviors/leader-key.md) | ✅ |
| [Mouse Keys](keymaps/behaviors/mouse-emulation.md) | ✅ |
| [Realtime Keymap Updating](features/studio.md) | 🚧 |

52
docs/docs/keymaps/behaviors/leader-key.md
View File

@ -5,7 +5,7 @@ sidebar_label: Leader Key
## Summary
The leader key behavior when triggered will capture all following key presses and trigger a [Leader Sequence](../features/leader.md) if pressed.
The leader key behavior when triggered will capture all following key presses and trigger a leader sequence's behavior if pressed.
### Behavior Binding
@ -36,3 +36,53 @@ To change the timeout term, you can update the existing behavior:
};
};
```
### Leader Sequences
#### Summary
Leader sequences are a way to have a sequence of key presses to output a different key. For example, you can hit the leader key followed by Q, then W to output escape.
#### Configuration
Leader sequences are configured as child nodes of your leader key behavior(s). They are specified like this:
```
leader: leader {
compatible = "zmk,behavior-leader-key";
#binding-cells = <0>;
seq_esc {
key-positions = <0 1>;
bindings = <&kp ESC>;
};
};
```
Each sequence can have the following properties:
- `key-positions` is an array of key positions. See the info section below about how to figure out the positions on your board.
- `bindings` is the behavior that is activated when all the key positions are pressed.
- (advanced) you can specify `immediate-trigger` if you want the sequence to be triggered as soon as all key positions are pressed. The default is to wait for the leader key's timeout to trigger the sequence if it overlaps another.
The `key-positions` array must not be longer than the `CONFIG_ZMK_LEADER_MAX_KEYS_PER_SEQUENCE` setting, which defaults to 4. If you want a leader sequence that triggers when pressing 5 keys, then you must change the setting to 5.
:::info
Key positions are numbered like the keys in your keymap, starting at 0. So, if the first key in your keymap is `Q`, this key is in position `0`. The next key (possibly `W`) will have position 1, etcetera.
:::
#### Locality
Sequence behaviors inherit their locality from the position of the leader key. For example, on split keyboards, a sequence using the `&bootloader` behavior will invoke the bootloader on the side on which the leader key is bound.
::::tip
Add the same leader key to both sides to be able to reset either side.
::::
### Advanced usage
See [leader configuration](../../config/leader.md) for advanced configuration options.

37
docs/sidebars.js
View File

@ -69,6 +69,7 @@ module.exports = {
"keymaps/behaviors/hold-tap",
"keymaps/behaviors/mod-morph",
"keymaps/behaviors/macros",
"keymaps/behaviors/leader-key",
"keymaps/behaviors/key-toggle",
"keymaps/behaviors/sticky-key",
"keymaps/behaviors/sticky-layer",
@ -107,41 +108,6 @@ module.exports = {
"keymaps/input-processors/temp-layer",
],
},
"behaviors/key-press",
"behaviors/layers",
"behaviors/misc",
"behaviors/hold-tap",
"behaviors/mod-tap",
"behaviors/mod-morph",
"behaviors/macros",
"behaviors/leader-key",
"behaviors/key-toggle",
"behaviors/sticky-key",
"behaviors/sticky-layer",
"behaviors/tap-dance",
"behaviors/caps-word",
"behaviors/key-repeat",
"behaviors/sensor-rotate",
"behaviors/mouse-emulation",
"behaviors/reset",
"behaviors/bluetooth",
"behaviors/outputs",
"behaviors/underglow",
"behaviors/backlight",
"behaviors/power",
"behaviors/soft-off",
],
},
{
Codes: [
"codes/index",
"codes/keyboard-keypad",
"codes/modifiers",
"codes/editing",
"codes/media",
"codes/applications",
"codes/input-assist",
"codes/power",
],
},
{
@ -161,6 +127,7 @@ module.exports = {
"config/encoders",
"config/lighting",
"config/pointing",
"config/leader",
"config/keymap",
"config/layout",
"config/kscan",