17 files changed, 201 insertions, 26 deletions
diff --git a/docs/docs/assets/pro-micro/pro-micro-pins-labelled.jpg b/docs/docs/assets/pro-micro/pro-micro-pins-labelled.jpg
new file mode 100644
index 0000000..f72d407
--- /dev/null
+++ b/docs/docs/assets/pro-micro/pro-micro-pins-labelled.jpg
diff --git a/docs/docs/assets/troubleshooting/filetransfer/linux.png b/docs/docs/assets/troubleshooting/filetransfer/linux.png
new file mode 100644
index 0000000..c192dfa
--- /dev/null
+++ b/docs/docs/assets/troubleshooting/filetransfer/linux.png
diff --git a/docs/docs/assets/troubleshooting/filetransfer/windows.png b/docs/docs/assets/troubleshooting/filetransfer/windows.png
new file mode 100644
index 0000000..91cb8a6
--- /dev/null
+++ b/docs/docs/assets/troubleshooting/filetransfer/windows.png
diff --git a/docs/docs/assets/troubleshooting/keymaps/errorscreen.png b/docs/docs/assets/troubleshooting/keymaps/errorscreen.png
new file mode 100644
index 0000000..73b5b58
--- /dev/null
+++ b/docs/docs/assets/troubleshooting/keymaps/errorscreen.png
diff --git a/docs/docs/assets/troubleshooting/keymaps/healthyEDIT.png b/docs/docs/assets/troubleshooting/keymaps/healthyEDIT.png
new file mode 100644
index 0000000..50d2c73
--- /dev/null
+++ b/docs/docs/assets/troubleshooting/keymaps/healthyEDIT.png
diff --git a/docs/docs/assets/troubleshooting/keymaps/unhealthyEDIT.png b/docs/docs/assets/troubleshooting/keymaps/unhealthyEDIT.png
new file mode 100644
index 0000000..3fd8dc7
--- /dev/null
+++ b/docs/docs/assets/troubleshooting/keymaps/unhealthyEDIT.png
diff --git a/docs/docs/behavior/bluetooth.md b/docs/docs/behavior/bluetooth.md
new file mode 100644
index 0000000..f802a9a
--- /dev/null
+++ b/docs/docs/behavior/bluetooth.md
@@ -0,0 +1,76 @@
+---
+title: Bluetooth Behavior
+sidebar_label: Bluetooth
+---
+
+## Summary
+
+The bluetooth behavior allows management of various settings and states related to the bluetooth connection(s)
+between the keyboard and the host. By default, ZMK supports five "profiles" for selecting which bonded host
+computer/laptop/keyboard should receive the keyboard input; many of the commands here operation on those profiles.
+
+## Bluetooth Command Defines
+
+Bluetooth command defines are provided through the [`dt-bindings/zmk/bt.h`](https://github.com/zmkfirmware/zmk/blob/main/app/include/dt-bindings/zmk/bt.h) header,
+which is added at the top of the keymap file:
+
+```
+#include <dt-bindings/zmk/bt.h>
+```
+
+This will allow you to reference the actions defined in this header such as `BT_CLR_CMD`.
+
+Here is a table describing the command for each define:
+
+| Define       | Action                                                                                         |
+| ------------ | ---------------------------------------------------------------------------------------------- |
+| `BT_CLR_CMD` | Clear bond information between the keyboard and host for the selected profile [^1]             |
+| `BT_NXT_CMD` | Switch to the next profile, cycling through to the first one when the end is reached.          |
+| `BT_PRV_CMD` | Switch to the previous profile, cycling through to the last one when the beginning is reached. |
+| `BT_SEL_CMD` | Select the 0-indexed profile by number.                                                        |
+
+Because at least one bluetooth commands takes an additional parameter, it is recommended to use
+the following aliases in your keymap to avoid having to specify an ignored second parameter:
+
+| Define   | Action                                                                           |
+| -------- | -------------------------------------------------------------------------------- |
+| `BT_CLR` | Alias for `BT_CLR_CMD 0` to clear the current profile's bond to the current host |
+| `BT_NXT` | Alias for `BT_NXT_CMD 0` to select the next profile                              |
+| `BT_PRV` | Alias for `BT_PRV_CMD 0` to select the previous profile                          |
+| `BT_SEL` | Alias for `BT_SEL_CMD` to select the given profile, e.g. `&bt BT_SEL 1`          |
+
+## Bluetooth Behavior
+
+The bluetooth behavior completes an bluetooth action given on press.
+
+### Behavior Binding
+
+- Reference: `&bt`
+- Parameter #1: The bluetooth command define, e.g. `BT_CLR_CMD`
+- Parameter #2: (Reserved for future bluetooth command types)
+
+### Examples
+
+1. Behavior binding to clear the paired host for the selected profile:
+
+   ```
+   &bt BT_CLR
+   ```
+
+1. Behavior binding to select the next profile:
+
+   ```
+   &bt BT_NXT
+   ```
+
+1. Behavior binding to select the previous profile:
+
+   ```
+   &bt BT_NXT
+   ```
+
+1. Behavior binding to select the 2nd profile (passed parameters are [zero based](https://en.wikipedia.org/wiki/Zero-based_numbering)):
+
+   ```
+   &bt BT_SEL 1
+   ```
diff --git a/docs/docs/behavior/hold-tap.md b/docs/docs/behavior/hold-tap.md
index fa68538..9f8f5fa 100644
--- a/docs/docs/behavior/hold-tap.md
+++ b/docs/docs/behavior/hold-tap.md
@@ -22,7 +22,11 @@ We call this the 'hold-preferred' flavor of hold-taps. While this flavor may wor
 
 ![Hold-tap comparison](../assets/hold-tap/comparison.png)
 
-### Configuration
+### Basic usage
+For basic usage, please see [mod-tap](./mod-tap.md) and [layer-tap](./layers.md) pages.
+
+
+### Advanced Configuration
 A code example which configures a mod-tap setting that works with homerow mods:
 
 ```
@@ -58,5 +62,5 @@ If this config does not work for you, try the flavor "tap-preferred" and a short
 
 If you want to use a tap-hold with a keycode from a different code page, you have to define another behavior with another "bindings" parameter.For example, if you want to use SHIFT and volume up, define the bindings like `bindings = <&kp>, <&cp>;`. Only single-argument behaviors are supported at the moment.
 
-#### Note
-Astute readers may notice similarities between the possible behaviors in ZMK and other firmware, such as QMK. The hold-preferred flavor works similar to the `HOLD_ON_OTHER_KEY_PRESS` setting. The 'balanced' flavor is similar to the `PERMISSIVE_HOLD` setting, and the `tap-preferred` flavor is similar to `IGNORE_MOD_TAP_INTERRUPT`.
-\ No newline at end of file
+#### Comparison to QMK
+The hold-preferred flavor works similar to the `HOLD_ON_OTHER_KEY_PRESS` setting in QMK. The 'balanced' flavor is similar to the `PERMISSIVE_HOLD` setting, and the `tap-preferred` flavor is similar to `IGNORE_MOD_TAP_INTERRUPT`. 
+\ No newline at end of file
diff --git a/docs/docs/behavior/key-press.md b/docs/docs/behavior/key-press.md
index f58225d..d427f9d 100644
--- a/docs/docs/behavior/key-press.md
+++ b/docs/docs/behavior/key-press.md
@@ -27,6 +27,11 @@ There is an [open issue](https://github.com/zmkfirmware/zmk/issues/21) to provid
 complete set of defines for the full keypad and consumer usage pages in the future for ZMK.
 :::
 
+### Improperly defined keymap - `dtlib.DTError: <board>.dts.pre.tmp:<line number>`
+
+When compiling firmware from a keymap, it may be common to encounter an error in the form of a`dtlib.DTError: <board>.dts.pre.tmp:<line number>`.
+For instructions to resolve such an error, click [here](../troubleshooting###Improperly-defined-keymap)
+
 ## Keypad Key Press
 
 The "keypad key press" behavior sends standard keypad keycodes on press/release.
@@ -59,4 +64,4 @@ Example:
 
 ```
 &cp M_PREV
-```
+```
+\ No newline at end of file
diff --git a/docs/docs/behavior/layers.md b/docs/docs/behavior/layers.md
index da7f07f..c769388 100644
--- a/docs/docs/behavior/layers.md
+++ b/docs/docs/behavior/layers.md
@@ -26,7 +26,7 @@ This allows you to use those defines, e.g. `LOWER` later in your keymap.
 
 ## Momentary Layer
 
-The "momentary layer" behavior allows you to enable a layer while a certain key is pressed. Immediately upon
+The "momentary layer" behavior enables a layer while a certain key is pressed. Immediately upon
 activation of the key, the layer is enabled, and immediately open release of the key, the layer is disabled
 again.
 
@@ -41,9 +41,25 @@ Example:
 &mo LOWER
 ```
 
+## Layer-tap
+
+The "layer-tap" behavior enables a layer when a key is held, and output another key when the key is only tapped for a short time. For more information on the inner workings of layer-tap, see [hold-tap](./hold-tap.md).
+
+### Behavior Binding
+- Reference: `&lt`
+- Parameter: The layer number to enable when held, e.g. `1`
+- Parameter: The keycode to send when tapped, e.g. `A`
+
+Example:
+
+```
+&lt LOWER SPC
+```
+
+
 ## Toggle Layer
 
-The "toggle layer" behavior allows you to enable a layer until the layer is manually disabled.
+The "toggle layer" behavior enables a layer until the layer is manually disabled.
 
 ### Behavior Binding
 
diff --git a/docs/docs/behavior/mod-tap.md b/docs/docs/behavior/mod-tap.md
index dcac492..068928a 100644
--- a/docs/docs/behavior/mod-tap.md
+++ b/docs/docs/behavior/mod-tap.md
@@ -31,8 +31,8 @@ You can configure a different tapping term in your keymap:
 
 ```
 &mt {
-    tapping_term_ms: <400>;
-} 
+    tapping_term_ms = <400>;
+};
 
 / {
     keymap {
diff --git a/docs/docs/dev-boards-shields-keymaps.md b/docs/docs/dev-boards-shields-keymaps.md
index cfe5252..9ed5a32 100644
--- a/docs/docs/dev-boards-shields-keymaps.md
+++ b/docs/docs/dev-boards-shields-keymaps.md
@@ -35,6 +35,8 @@ in the `app/boards/${arch}/${board_name}` directory, e.g. `app/boards/arm/planck
 
 ## Pro Micro Compatible Keyboard
 
+![Labelled Pro Micro pins](assets/pro-micro/pro-micro-pins-labelled.jpg)
+
 For keyboards that require a (usually Pro Micro compatible) add-on board to operate, the ZMK integration pieces are places
 in the _shield_ definition for that keyboard, allowing users to
 swap in different Pro Micro compatible boards (e.g. Proton-C, or nice!nano) and build a firmware the matches their actual
diff --git a/docs/docs/dev-guide-new-shield.md b/docs/docs/dev-guide-new-shield.md
index bc5175b..6140b07 100644
--- a/docs/docs/dev-guide-new-shield.md
+++ b/docs/docs/dev-guide-new-shield.md
@@ -64,6 +64,10 @@ endif
 
 ## Shield Overlay
 
+![Labelled Pro Micro pins](assets/pro-micro/pro-micro-pins-labelled.jpg)
+
+ZMK uses the green color coded pin names to generate devicetree node references. For example, to refer to the node `D0` in the devicetree files, use `&pro_micro_d 0` or to refer to `A1`, use `&pro_micro_a 1`.
+
 The `<shield_name>.overlay` is the devicetree description of the keyboard shield that is merged with the primary board devicetree description before the build. For ZMK, this file at a minimum should include the [chosen]() node named `zmk,kscan` that references a KSCAN driver instance. For a simple 3x3 macropad matrix,
 this might look something like:
 
diff --git a/docs/docs/faq.md b/docs/docs/faq.md
index 2ab158d..d8bbd71 100644
--- a/docs/docs/faq.md
+++ b/docs/docs/faq.md
@@ -76,7 +76,7 @@ Please note, many keyboards only have a single PCB which includes the “brains�
 
 ### What bootloader does ZMK use?
 
-ZMK isn’t designed for any particular bootloader, and supports flashing different boards with different flash utilities (e.g. OpenOCD, nrfjprog, etc.).  So if you have any difficulties, please let us know on  [Discord](https://discord.gg/VJnx9kr)!
+ZMK isn’t designed for any particular bootloader, and supports flashing different boards with different flash utilities (e.g. OpenOCD, nrfjprog, etc.).  So if you have any difficulties, please let us know on  [Discord](https://zmkfirmware.dev/community/discord/invite)!
 
 ### Can I contribute?
 
@@ -84,11 +84,11 @@ Of course!  Please use the developer [documentation](/docs) to get started!
 
 ### I have an idea!  What should I do?
 
-Please join us on [Discord](https://discord.gg/VJnx9kr) and discuss it with us!
+Please join us on [Discord](https://zmkfirmware.dev/community/discord/invite) and discuss it with us!
 
 ### I want to add a new keyboard!  What should I do?
 
-The exact process for the management of all the possible hardware is still being finalized, but any developer looking to contribute new keyboard definitions should chat with us on [Discord](https://discord.gg/VJnx9kr) to get started.
+The exact process for the management of all the possible hardware is still being finalized, but any developer looking to contribute new keyboard definitions should chat with us on [Discord](https://zmkfirmware.dev/community/discord/invite) to get started.
 
 ### Does ZMK have a Code of Conduct?
 
diff --git a/docs/docs/intro.md b/docs/docs/intro.md
index 29045f7..8c1c043 100644
--- a/docs/docs/intro.md
+++ b/docs/docs/intro.md
@@ -5,33 +5,38 @@ sidebar_label: Introduction
 ---
 
 ZMK Firmware is an open source (MIT) keyboard
-firmware built on the [Zephyr™ Project](https://zephyrproject.com/) Real Time Operating System (RTOS).
+firmware built on the [Zephyr™ Project](https://zephyrproject.org/) Real Time Operating System (RTOS).
 
-The goal is to provider a powerful, featureful keyboard firmware that is free
+The goal is to provide a powerful, featureful keyboard firmware that is free
 of licensing issues that prevent upstream BLE support as a first-class
 feature.
 
 ## Features
 
-At this point, ZMK is _missing_ more features than it has. Currently, the mostly working bits
+At this point, ZMK is still missing many features. Currently, the working bits
 include:
 
-- HID Over GATT (HOG) - This is the official term for BLE HID devices
-- Keymaps and layers with basic keycodes
-- Some initial work on one "behavior", Mod-Tap
-- Basic HID over USB
-- Basic consumer (media) keycodes.
-- Basic OLED display logic
-- Basic Split support
-- Encoders
+- Wireless connectivity via BLE HID Over GATT (HOG)
+- USB connectivity
+- Low active power usage
+- Split keyboard support
+- [Keymaps and layers](behavior/layers)
+- [Hold-tap](behavior/hold-tap) (which includes [mod-tap](behavior/mod-tap), [layer-tap](behavior/layers))
+- [Basic HID over USB](behavior/key-press)
+- [Basic consumer (media) keycodes](behavior/key-press#consumer-key-press)
+- [Encoders](feature/encoders)
+- Basic [OLED display support](feature/displays)
+- [RGB Underglow](feature/underglow)
 
 ## Missing Features
 
-- One Shot
-- Layer Tap
-- Complete split support
+- One Shot Keys
+- Combo keys
+- Macros
+- Complete split support (encoders and RGB are not supported on the 'peripheral' side)
 - Battery reporting
-- Low power mode
+- Low power sleep states
+- Low power mode (to toggle LEDs and screen off)
 - Shell over BLE
 
 ## Code Of Conduct
diff --git a/docs/docs/troubleshooting.md b/docs/docs/troubleshooting.md
new file mode 100644
index 0000000..deb89b6
--- /dev/null
+++ b/docs/docs/troubleshooting.md
@@ -0,0 +1,61 @@
+---
+id: troubleshooting
+title: Troubleshooting
+sidebar_title: Troubleshooting
+---
+### Summary
+
+The following page provides suggestions for common errors that may occur during firmware compilation. If the information provided is insufficient to resolve the issue, feel free to seek out help from the [ZMK Discord](https://zmkfirmware.dev/community/discord/invite).
+
+### File Transfer Error
+
+Variations of the warnings shown below occur when flashing the `<firmware>.uf2` onto the microcontroller. This is because the microcontroller resets itself before the OS receives confirmation that the file transfer is complete. Errors like this are normal and can generally be ignored. Verification of a functional board can be done by attempting to pair your newly flashed keyboard to your computer via Bluetooth or plugging in a USB cable if `ZMK_USB` is enabled in your Kconfig.defconfig.
+
+|       ![Example Error Screen](../docs/assets/troubleshooting/filetransfer/windows.png)      |
+| :-------------------------------------------------------------------------------:           |
+|            An example of the file transfer error on Windows 10                              |
+
+|       ![Example Error Screen](../docs/assets/troubleshooting/filetransfer/linux.png)        |
+| :-------------------------------------------------------------------------------:           |
+|           An example of the file transfer error on Linux                                    |
+
+
+### CMake Error
+
+```
+CMake Warning at C:/zmk/zephyr/subsys/usb/CMakeLists.txt:28 (message):
+  CONFIG_USB_DEVICE_VID has default value 0x2FE3.
+ 
+  This value is only for testing and MUST be configured for USB products.
+ 
+ 
+CMake Warning at C:/zmk/zephyr/subsys/usb/CMakeLists.txt:34 (message):
+  CONFIG_USB_DEVICE_PID has default value 0x100.
+ 
+  This value is only for testing and MUST be configured for USB products.
+```
+
+CMake Warnings shown above during `west build` are normal occurrences. They should not negatively affect the firmware's ability to function as normal.
+
+On the other hand, an error along the lines of `CMake Error at (zmk directory)/zephyr/cmake/generic_toolchain.cmake:64 (include): include could not find load file:` during firmware compilation indicates that the Zephyr Environment Variables are not properly defined.
+For more information, click [here](../docs/dev-setup#environment-variables).
+
+
+### dtlib.DTError
+
+An error along the lines of `dtlib.DTError: <board>.dts.pre.tmp:<line number>` during firmware compilation indicates an issue within the `<shield>.keymap` file.
+This can be verified by checking the file in question, found in `mkdir/app/build`.
+
+|       ![Example Error Screen](../docs/assets/troubleshooting/keymaps/errorscreen.png)                                             |
+| :-------------------------------------------------------------------------------:                                                 |
+|            An example of the dtlib.DTError when compiling an iris with the nice!nano while the keymap is not properly defined     |
+
+After opening the `<board>.dts.pre.tmp:<line number>` and scrolling down to the referenced line, one can locate errors within their shield's keymap by checking if the referenced keycodes were properly converted into the correct [USB HID Usage ID](https://www.usb.org/document-library/hid-usage-tables-12).
+
+|       ![Unhealthy Keymap Temp](../docs/assets/troubleshooting/keymaps/unhealthyEDIT.png)  |
+| :-------------------------------------------------------------------------------:         |
+|   An incorrectly defined keymap unable to compile. As shown in red, `&kp SPAC` is not a valid reference to the [USB HID Usage ID](https://www.usb.org/document-library/hid-usage-tables-12) used for "Keyboard Spacebar"         |
+
+|  ![Healthy Keymap Temp](../docs/assets/troubleshooting/keymaps/healthyEDIT.png)  |
+| :-------------------------------------------------------------------------------: |
+|  A properly defined keymap with successful compilation. As shown in red, the corrected keycode (`&kp SPC`) references the proper Usage ID defined in the [USB HID Usage Tables](https://www.usb.org/document-library/hid-usage-tables-12)|
diff --git a/docs/sidebars.js b/docs/sidebars.js
index 7df5e12..ace7fa1 100644
--- a/docs/sidebars.js
+++ b/docs/sidebars.js
@@ -7,6 +7,7 @@ module.exports = {
       "user-setup",
       "customization",
       "bond-reset",
+      "troubleshooting"
     ],
     Features: [
       "feature/keymaps",
@@ -21,6 +22,7 @@ module.exports = {
       "behavior/hold-tap",
       "behavior/mod-tap",
       "behavior/reset",
+      "behavior/bluetooth",
       "behavior/lighting",
     ],
     Development: [