From 89567d3150207836b96030cc85f7267e0c203690 Mon Sep 17 00:00:00 2001
From: Okke Formsma <okke@formsma.nl>
Date: Sun, 13 Dec 2020 14:33:28 +0100
Subject: [PATCH] docs(sticky keys): document sticky keys and sticky layers

---
 docs/docs/behaviors/sticky-key.md   | 51 +++++++++++++++++++++++++++++
 docs/docs/behaviors/sticky-layer.md | 45 +++++++++++++++++++++++++
 docs/sidebars.js                    |  2 ++
 3 files changed, 98 insertions(+)
 create mode 100644 docs/docs/behaviors/sticky-key.md
 create mode 100644 docs/docs/behaviors/sticky-layer.md

diff --git a/docs/docs/behaviors/sticky-key.md b/docs/docs/behaviors/sticky-key.md
new file mode 100644
index 00000000..d5627dcb
--- /dev/null
+++ b/docs/docs/behaviors/sticky-key.md
@@ -0,0 +1,51 @@
+---
+title: Sticky Key Behavior
+sidebar_label: Sticky Key
+---
+
+## Summary
+
+A sticky key stays pressed until another key is pressed. It is often used for 'sticky shift'. By using a sticky shift, you don't have to hold the shift key to write a capital.
+
+By default, sticky keys stay pressed for a second if you don't press any other key. You can configure this with the `release-after-ms` setting (see below).
+
+### Behavior Binding
+
+- Reference: `&sk`
+- Parameter #1: The keycode , e.g. `LSHFT`
+
+Example:
+
+```
+&sk LSHFT
+```
+
+You can use any keycode that works for `&kp` as parameter to `&sk`:
+
+```
+&sk LG(LS(LA(LCTRL)))
+```
+
+### Configuration
+
+You can configure a different `release-after-ms` in your keymap:
+
+```
+&sk {
+    release-after-ms = <2000>;
+};
+
+/ {
+    keymap {
+        ...
+    }
+}
+```
+
+### Advanced usage
+
+Sticky keys can be combined; if you tap `&sk LCTRL` and then `&sk LSHFT` and then `&kp A`, the output will be ctrl+shift+a.
+
+### Comparison to QMK
+
+In QMK, sticky keys are known as 'one shot mods'.
diff --git a/docs/docs/behaviors/sticky-layer.md b/docs/docs/behaviors/sticky-layer.md
new file mode 100644
index 00000000..597ed9f0
--- /dev/null
+++ b/docs/docs/behaviors/sticky-layer.md
@@ -0,0 +1,45 @@
+---
+title: Sticky Layer Behavior
+sidebar_label: Sticky Layer
+---
+
+## Summary
+
+A sticky layer stays pressed until another key is pressed. By using a sticky layer, you don't have to hold the layer key to access a layer. Instead, tap the sticky layer key to activate the layer until the next keypress.
+
+By default, sticky layers stay pressed for a second if you don't press any other key. You can configure this with the `release-after-ms` setting (see below).
+
+### Behavior Binding
+
+- Reference: `&sl`
+- Parameter #1: The layer to activate , e.g. `1`
+
+Example:
+
+```
+&sl 1
+```
+
+### Configuration
+
+You can configure a different `release-after-ms` in your keymap:
+
+```
+&sl {
+    release-after-ms = <2000>;
+};
+
+/ {
+    keymap {
+        ...
+    }
+}
+```
+
+### Advanced usage
+
+Sticky layers behave slightly different from sticky keys. They are configured to `quick-release`. This means that the layer is released immediately when another key is pressed. "Normal" sticky keys are not `quick-release`; they are released when the next key is released. This makes it possible to combine sticky layers and sticky keys as such: tap `&sl 1`, tap `&sk LSHFT` on layer 1, tap `&kp A` on base layer to output shift+A.
+
+### Comparison to QMK
+
+In QMK, sticky layers are known as 'one shot layers'.
diff --git a/docs/sidebars.js b/docs/sidebars.js
index 56de3eb8..f0465d4d 100644
--- a/docs/sidebars.js
+++ b/docs/sidebars.js
@@ -21,6 +21,8 @@ module.exports = {
       "behaviors/misc",
       "behaviors/hold-tap",
       "behaviors/mod-tap",
+      "behaviors/sticky-key",
+      "behaviors/sticky-layer",
       "behaviors/reset",
       "behaviors/bluetooth",
       "behaviors/outputs",