Fix YMDK NP21 keyboard to use proper keyboard level functions (#3042)

* Use proper function levels

* Add matrix init functions

* Convert KEYMAP to LAYOUT

Or @mechmerlin is going to hunt me down and harm me... probably :)

* Fix conflict issues

.gitignore

@@ -43,6 +43,7 @@ doxygen/
 .project
 .settings/
 .idea
+*.iml
 .browse.VC.db*
 *.stackdump
 util/Win_Check_Output.txt

.vscode/settings.json

@@ -11,6 +11,7 @@
         "*.h": "c",
         "*.c": "c",
         "*.cpp": "cpp",
-        "*.hpp": "cpp"
+        "*.hpp": "cpp",
+        "xstddef": "c"
     }
-}
+}

CODE_OF_CONDUCT.md

@@ -1,10 +1,10 @@
 # Code Of Conduct
 
-QMK strives to be an inclusive and tolerant community. We welcome participation from anyone regardless of age, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, political belief, race, religion, or sexual identity and orientation. 
+QMK strives to be an inclusive, tolerant, and welcoming community. We encourage participation from anyone regardless of age, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, political belief, race, religion, or sexual identity and orientation.
 
-> “A gentle word turns away wrath, but a harsh word stirs up anger.”
+> “A gentle word turns away wrath, but a harsh word stirs up anger."
 
-Our users, contributors, and collaborators are expected to treat each other with respect, to assume good intentions, and to gently correct, where possible, rather than react with escalation. Some examples of behavior we will not tolerate include, but is not limited to:
+Our users, contributors, and collaborators are expected to treat each other with kindness and respect, to assume good intentions, and to gently correct, where possible, rather than react with escalation. While our goal is to be as accurate as possible, kindness and understanding are more valuable than correctness. Some examples of behavior we will not tolerate include, but is not limited to:
 
 * The use of sexualized language or imagery
 * Unwelcome advances, sexual or otherwise

Makefile

@@ -67,7 +67,7 @@ $(eval $(call NEXT_PATH_ELEMENT))
 # It's really a very simple if else chain, if you squint enough,
 # but the makefile syntax makes it very verbose.
 # If we are in a subfolder of keyboards
-# 
+#
 # *** No longer needed **
 #
 # ifeq ($(CURRENT_PATH_ELEMENT),keyboards)
@@ -307,11 +307,6 @@ define PARSE_KEYBOARD
     KEYBOARD_FOLDER_PATH_3 := $$(patsubst %/,%,$$(dir $$(KEYBOARD_FOLDER_PATH_2)))
     KEYBOARD_FOLDER_PATH_4 := $$(patsubst %/,%,$$(dir $$(KEYBOARD_FOLDER_PATH_3)))
     KEYBOARD_FOLDER_PATH_5 := $$(patsubst %/,%,$$(dir $$(KEYBOARD_FOLDER_PATH_4)))
-    KEYBOARD_FOLDER_1 := $$(notdir $$(KEYBOARD_FOLDER_PATH_1))
-    KEYBOARD_FOLDER_2 := $$(notdir $$(KEYBOARD_FOLDER_PATH_2))
-    KEYBOARD_FOLDER_3 := $$(notdir $$(KEYBOARD_FOLDER_PATH_3))
-    KEYBOARD_FOLDER_4 := $$(notdir $$(KEYBOARD_FOLDER_PATH_4))
-    KEYBOARD_FOLDER_5 := $$(notdir $$(KEYBOARD_FOLDER_PATH_5))
 
     KEYMAPS :=
     # get a list of all keymaps
@@ -325,35 +320,35 @@ define PARSE_KEYBOARD
         $$(KEYBOARD_FOLDER_3) $$(KEYBOARD_FOLDER_4) $$(KEYBOARD_FOLDER_5), $$(KEYMAPS)))
 
     KEYBOARD_LAYOUTS :=
-    ifneq ("$$(wildcard $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_5)/rules.mk)","")
+    ifneq ("$$(wildcard $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_5)/rules.mk)","")
       LAYOUTS :=
-      $$(eval include $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_5)/rules.mk)
+      $$(eval include $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_5)/rules.mk)
       KEYBOARD_LAYOUTS := $$(sort $$(LAYOUTS) $$(KEYBOARD_LAYOUTS))
     endif
-    ifneq ("$$(wildcard $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_4)/rules.mk)","")
+    ifneq ("$$(wildcard $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_4)/rules.mk)","")
       LAYOUTS :=
-      $$(eval include $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_4)/rules.mk)
+      $$(eval include $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_4)/rules.mk)
       KEYBOARD_LAYOUTS := $$(sort $$(LAYOUTS) $$(KEYBOARD_LAYOUTS))
     endif
-    ifneq ("$$(wildcard $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_3)/rules.mk)","")
+    ifneq ("$$(wildcard $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_3)/rules.mk)","")
       LAYOUTS :=
-      $$(eval include $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_3)/rules.mk)
+      $$(eval include $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_3)/rules.mk)
       KEYBOARD_LAYOUTS := $$(sort $$(LAYOUTS) $$(KEYBOARD_LAYOUTS))
     endif
-    ifneq ("$$(wildcard $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_2)/rules.mk)","")
+    ifneq ("$$(wildcard $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_2)/rules.mk)","")
       LAYOUTS :=
-      $$(eval include $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_2)/rules.mk)
+      $$(eval include $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_2)/rules.mk)
       KEYBOARD_LAYOUTS := $$(sort $$(LAYOUTS) $$(KEYBOARD_LAYOUTS))
     endif
-    ifneq ("$$(wildcard $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_1)/rules.mk)","")
+    ifneq ("$$(wildcard $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_1)/rules.mk)","")
       LAYOUTS :=
-      $$(eval include $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_1)/rules.mk)
+      $$(eval include $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_1)/rules.mk)
       KEYBOARD_LAYOUTS := $$(sort $$(LAYOUTS) $$(KEYBOARD_LAYOUTS))
     endif
 
     LAYOUT_KEYMAPS :=
     $$(foreach LAYOUT,$$(KEYBOARD_LAYOUTS),$$(eval LAYOUT_KEYMAPS += $$(notdir $$(patsubst %/.,%,$$(wildcard $(ROOT_DIR)/layouts/*/$$(LAYOUT)/*/.)))))
-    
+
     KEYMAPS := $$(sort $$(KEYMAPS) $$(LAYOUT_KEYMAPS))
 
     # if the rule after removing the start of it is empty (we haven't specified a kemap or target)
@@ -583,7 +578,7 @@ lib/%:
 
 git-submodule:
 	git submodule sync --recursive
-	git submodule update --init --recursive
+	git submodule update --init --recursive --progress
 
 ifdef SKIP_VERSION
 SKIP_GIT := yes

Vagrantfile

@@ -2,27 +2,8 @@
 # vi: set ft=ruby :
 
 Vagrant.configure(2) do |config|
-  # You can only have one config.vm.box uncommented at a time
-
-  # Comment this and uncomment another if you don't want to use the minimal Arch box
-  #config.vm.box = "dragon788/arch-ala-elasticdog"
-
   # VMware/Virtualbox 64 bit
   config.vm.box = "phusion/ubuntu-14.04-amd64"
-  #
-  # VMware/Virtualbox 64 bit
-  #config.vm.box = "puphpet/centos65-x64"
-  #
-  # The opensuse boxes don't have dfu-util in their default repositories
-  #
-  # The virtualbox version has tools issues
-  # VMware/Virtualbox 64 bit
-  #config.vm.box = "bento/opensuse-13.2-x86_64"
-  #
-  # Virtualbox only
-  #config.vm.box = "bento/opensuse-13.2-i386"
-  # config.vm.box = ""
-  # config.vm.box = ""
 
   # This section allows you to customize the Virtualbox VM
   # settings, ie showing the GUI or upping the memory
@@ -81,18 +62,16 @@ Vagrant.configure(2) do |config|
   config.vm.provision "shell", run: "always", path: "./util/install_dependencies.sh", args: "-update"
 
   config.vm.post_up_message = <<-EOT
-  Log into the VM using 'vagrant ssh' on OSX or from Git Bash (Win)
-  or 'vagrant ssh-config' and Putty or Bitvise SSH or another SSH tool
 
-  Change directory (cd) to the keyboard you wish to program
-  (Optionally) modify your layout,
-  then run 'make clean'
-  and then 'make' to compile the .eep and .hex files.
-
-  Or you can copy and paste the example line below.
-
-  cd /vagrant; cd keyboards; cd ergodox; make clean; make
+  Log into the VM using 'vagrant ssh'. QMK directory synchronized with host is
+  located at /vagrant
+  To compile the .hex files use make command inside this directory.
 
+  QMK's make format recently changed to use folder locations and colons:
+     make project_folder:keymap[:target]
+  Examples:
+     make planck/rev4:default:dfu
+     make planck:default
 
   EOT
 end

bootloader.mk

@@ -32,21 +32,41 @@
 ifeq ($(strip $(BOOTLOADER)), atmel-dfu)
     OPT_DEFS += -DBOOTLOADER_ATMEL_DFU
     OPT_DEFS += -DBOOTLOADER_DFU
-    BOOTLOADER_SIZE = 4096
+    ifeq ($(strip $(MCU)), atmega32u4)
+      BOOTLOADER_SIZE = 4096
+    endif
+    ifeq ($(strip $(MCU)), at90usb1286)
+      BOOTLOADER_SIZE = 8192
+    endif
 endif
 ifeq ($(strip $(BOOTLOADER)), lufa-dfu)
     OPT_DEFS += -DBOOTLOADER_LUFA_DFU
     OPT_DEFS += -DBOOTLOADER_DFU
-    BOOTLOADER_SIZE = 4096
+    ifeq ($(strip $(MCU)), atmega32u4)
+      BOOTLOADER_SIZE = 4096
+    endif
+    ifeq ($(strip $(MCU)), at90usb1286)
+      BOOTLOADER_SIZE = 8192
+    endif
 endif
 ifeq ($(strip $(BOOTLOADER)), qmk-dfu)
     OPT_DEFS += -DBOOTLOADER_QMK_DFU
     OPT_DEFS += -DBOOTLOADER_DFU
-    BOOTLOADER_SIZE = 4096
+    ifeq ($(strip $(MCU)), atmega32u4)
+      BOOTLOADER_SIZE = 4096
+    endif
+    ifeq ($(strip $(MCU)), at90usb1286)
+      BOOTLOADER_SIZE = 8192
+    endif
 endif
 ifeq ($(strip $(BOOTLOADER)), halfkay)
     OPT_DEFS += -DBOOTLOADER_HALFKAY
-    BOOTLOADER_SIZE = 512
+    ifeq ($(strip $(MCU)), atmega32u4)
+      BOOTLOADER_SIZE = 512
+    endif
+    ifeq ($(strip $(MCU)), at90usb1286)
+      BOOTLOADER_SIZE = 1024
+    endif
 endif
 ifeq ($(strip $(BOOTLOADER)), caterina)
     OPT_DEFS += -DBOOTLOADER_CATERINA
@@ -59,4 +79,4 @@ endif
 
 ifdef BOOTLOADER_SIZE
     OPT_DEFS += -DBOOTLOADER_SIZE=$(strip $(BOOTLOADER_SIZE))
-endif
+endif

build_keyboard.mk

@@ -1,3 +1,9 @@
+# Determine what keyboard we are building and setup the build environment.
+#
+# We support folders up to 5 levels deep below `keyboards/`. This file is
+# responsible for determining which folder is being used and doing the
+# corresponding environment setup.
+
 ifndef VERBOSE
 .SILENT:
 endif
@@ -6,26 +12,15 @@ endif
 
 include common.mk
 
-# 5/4/3/2/1
-KEYBOARD_FOLDER_PATH_1 := $(KEYBOARD)
-KEYBOARD_FOLDER_PATH_2 := $(patsubst %/,%,$(dir $(KEYBOARD_FOLDER_PATH_1)))
-KEYBOARD_FOLDER_PATH_3 := $(patsubst %/,%,$(dir $(KEYBOARD_FOLDER_PATH_2)))
-KEYBOARD_FOLDER_PATH_4 := $(patsubst %/,%,$(dir $(KEYBOARD_FOLDER_PATH_3)))
-KEYBOARD_FOLDER_PATH_5 := $(patsubst %/,%,$(dir $(KEYBOARD_FOLDER_PATH_4)))
-KEYBOARD_FOLDER_1 := $(notdir $(KEYBOARD_FOLDER_PATH_1))
-KEYBOARD_FOLDER_2 := $(notdir $(KEYBOARD_FOLDER_PATH_2))
-KEYBOARD_FOLDER_3 := $(notdir $(KEYBOARD_FOLDER_PATH_3))
-KEYBOARD_FOLDER_4 := $(notdir $(KEYBOARD_FOLDER_PATH_4))
-KEYBOARD_FOLDER_5 := $(notdir $(KEYBOARD_FOLDER_PATH_5))
-
+# Set the filename for the final firmware binary
 KEYBOARD_FILESAFE := $(subst /,_,$(KEYBOARD))
-
 TARGET ?= $(KEYBOARD_FILESAFE)_$(KEYMAP)
 KEYBOARD_OUTPUT := $(BUILD_DIR)/obj_$(KEYBOARD_FILESAFE)
 
 # Force expansion
 TARGET := $(TARGET)
 
+# For split boards we need to set a master half.
 MASTER ?= left
 ifdef master
     MASTER = $(master)
@@ -39,35 +34,58 @@ $(error MASTER does not have a valid value(left/right))
     endif
 endif
 
+# Determine which subfolders exist.
+KEYBOARD_FOLDER_PATH_1 := $(KEYBOARD)
+KEYBOARD_FOLDER_PATH_2 := $(patsubst %/,%,$(dir $(KEYBOARD_FOLDER_PATH_1)))
+KEYBOARD_FOLDER_PATH_3 := $(patsubst %/,%,$(dir $(KEYBOARD_FOLDER_PATH_2)))
+KEYBOARD_FOLDER_PATH_4 := $(patsubst %/,%,$(dir $(KEYBOARD_FOLDER_PATH_3)))
+KEYBOARD_FOLDER_PATH_5 := $(patsubst %/,%,$(dir $(KEYBOARD_FOLDER_PATH_4)))
+KEYBOARD_FOLDER_1 := $(notdir $(KEYBOARD_FOLDER_PATH_1))
+KEYBOARD_FOLDER_2 := $(notdir $(KEYBOARD_FOLDER_PATH_2))
+KEYBOARD_FOLDER_3 := $(notdir $(KEYBOARD_FOLDER_PATH_3))
+KEYBOARD_FOLDER_4 := $(notdir $(KEYBOARD_FOLDER_PATH_4))
+KEYBOARD_FOLDER_5 := $(notdir $(KEYBOARD_FOLDER_PATH_5))
 KEYBOARD_PATHS :=
-
 KEYBOARD_PATH_1 := keyboards/$(KEYBOARD_FOLDER_PATH_1)
 KEYBOARD_PATH_2 := keyboards/$(KEYBOARD_FOLDER_PATH_2)
 KEYBOARD_PATH_3 := keyboards/$(KEYBOARD_FOLDER_PATH_3)
 KEYBOARD_PATH_4 := keyboards/$(KEYBOARD_FOLDER_PATH_4)
 KEYBOARD_PATH_5 := keyboards/$(KEYBOARD_FOLDER_PATH_5)
 
-ifneq ("$(wildcard $(KEYBOARD_PATH_5)/rules.mk)","")
+ifneq ("$(wildcard $(KEYBOARD_PATH_5)/)","")
     KEYBOARD_PATHS += $(KEYBOARD_PATH_5)
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_4)/)","")
+    KEYBOARD_PATHS += $(KEYBOARD_PATH_4)
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_3)/)","")
+    KEYBOARD_PATHS += $(KEYBOARD_PATH_3)
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_2)/)","")
+    KEYBOARD_PATHS += $(KEYBOARD_PATH_2)
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_1)/)","")
+    KEYBOARD_PATHS += $(KEYBOARD_PATH_1)
+endif
+
+# Pull in rules.mk files from all our subfolders
+ifneq ("$(wildcard $(KEYBOARD_PATH_5)/rules.mk)","")
     include $(KEYBOARD_PATH_5)/rules.mk
 endif
 ifneq ("$(wildcard $(KEYBOARD_PATH_4)/rules.mk)","")
-    KEYBOARD_PATHS += $(KEYBOARD_PATH_4)
     include $(KEYBOARD_PATH_4)/rules.mk
 endif
 ifneq ("$(wildcard $(KEYBOARD_PATH_3)/rules.mk)","")
-    KEYBOARD_PATHS += $(KEYBOARD_PATH_3)
     include $(KEYBOARD_PATH_3)/rules.mk
 endif
 ifneq ("$(wildcard $(KEYBOARD_PATH_2)/rules.mk)","")
-    KEYBOARD_PATHS += $(KEYBOARD_PATH_2)
     include $(KEYBOARD_PATH_2)/rules.mk
 endif
 ifneq ("$(wildcard $(KEYBOARD_PATH_1)/rules.mk)","")
-    KEYBOARD_PATHS += $(KEYBOARD_PATH_1)
     include $(KEYBOARD_PATH_1)/rules.mk
 endif
 
+# Find all the C source files to be compiled in subfolders.
 KEYBOARD_SRC :=
 
 KEYBOARD_C_1 := $(KEYBOARD_PATH_1)/$(KEYBOARD_FOLDER_1).c
@@ -95,6 +113,15 @@ endif
 OPT_DEFS += -DKEYBOARD_$(KEYBOARD_FILESAFE)
 
 
+# Setup the define for QMK_KEYBOARD_H. This is used inside of keymaps so
+# that the same keymap may be used on multiple keyboards.
+#
+# We grab the most top-level include file that we can. That file should
+# use #ifdef statements to include all the neccesary subfolder includes,
+# as described here:
+#
+#    https://docs.qmk.fm/#/feature_layouts?id=tips-for-making-layouts-keyboard-agnostic
+#
 ifneq ("$(wildcard $(KEYBOARD_PATH_1)/$(KEYBOARD_FOLDER_1).h)","")
     QMK_KEYBOARD_H = $(KEYBOARD_FOLDER_1).h
 endif
@@ -111,13 +138,18 @@ ifneq ("$(wildcard $(KEYBOARD_PATH_5)/$(KEYBOARD_FOLDER_5).h)","")
     QMK_KEYBOARD_H = $(KEYBOARD_FOLDER_5).h
 endif
 
-# We can assume a ChibiOS target When MCU_FAMILY is defined , since it's not used for LUFA
+# Determine and set parameters based on the keyboard's processor family.
+# We can assume a ChibiOS target When MCU_FAMILY is defined since it's
+# not used for LUFA
 ifdef MCU_FAMILY
-    FIRMWARE_FORMAT=bin
+    FIRMWARE_FORMAT?=bin
     PLATFORM=CHIBIOS
+else ifdef ARM_ATSAM
+    PLATFORM=ARM_ATSAM
+    FIRMWARE_FORMAT=bin
 else
     PLATFORM=AVR
-    FIRMWARE_FORMAT=hex
+    FIRMWARE_FORMAT?=hex
 endif
 
 ifeq ($(PLATFORM),CHIBIOS)
@@ -148,6 +180,7 @@ ifeq ($(PLATFORM),CHIBIOS)
     endif
 endif
 
+# Find all of the config.h files and add them to our CONFIG_H define.
 CONFIG_H :=
 ifneq ("$(wildcard $(KEYBOARD_PATH_5)/config.h)","")
     CONFIG_H += $(KEYBOARD_PATH_5)/config.h
@@ -203,11 +236,15 @@ else
     # this state should never be reached
 endif
 
-# User space stuff
-USER_PATH := users/$(KEYMAP)
+# Userspace setup and definitions
+ifeq ("$(USER_NAME)","")
+    USER_NAME := $(KEYMAP)
+endif
+USER_PATH := users/$(USER_NAME)
+
 -include $(USER_PATH)/rules.mk
-ifneq ("$(wildcard users/$(KEYMAP)/config.h)","")
-    CONFIG_H += users/$(KEYMAP)/config.h
+ifneq ("$(wildcard $(USER_PATH)/config.h)","")
+    CONFIG_H += $(USER_PATH)/config.h
 endif
 
 
@@ -252,6 +289,11 @@ endif
     include $(TMK_PATH)/avr.mk
 endif
 
+ifeq ($(PLATFORM),ARM_ATSAM)
+    include $(TMK_PATH)/arm_atsam.mk
+    include $(TMK_PATH)/protocol/arm_atsam.mk
+endif
+
 ifeq ($(PLATFORM),CHIBIOS)
     include $(TMK_PATH)/protocol/chibios.mk
 endif
@@ -279,11 +321,6 @@ $(KEYBOARD_OUTPUT)_CONFIG := $(PROJECT_CONFIG)
 
 # Default target.
 all: build check-size
-
-# Change the build target to build a HEX file or a library.
 build: elf cpfirmware
-#build: elf hex eep lss sym
-#build: lib
-
 
 include $(TMK_PATH)/rules.mk

common.mk

@@ -3,16 +3,16 @@ include message.mk
 # Directory common source files exist
 TOP_DIR = .
 TMK_DIR = tmk_core
-TMK_PATH = $(TOP_DIR)/$(TMK_DIR)
-LIB_PATH = $(TOP_DIR)/lib
+TMK_PATH = $(TMK_DIR)
+LIB_PATH = lib
 
 QUANTUM_DIR = quantum
-QUANTUM_PATH = $(TOP_DIR)/$(QUANTUM_DIR)
+QUANTUM_PATH = $(QUANTUM_DIR)
 
 DRIVER_DIR = drivers
-DRIVER_PATH = $(TOP_DIR)/$(DRIVER_DIR)
+DRIVER_PATH = $(DRIVER_DIR)
 
-BUILD_DIR := $(TOP_DIR)/.build
+BUILD_DIR := .build
 
 COMMON_VPATH := $(TOP_DIR)
 COMMON_VPATH += $(TMK_PATH)
@@ -21,4 +21,5 @@ COMMON_VPATH += $(QUANTUM_PATH)/keymap_extras
 COMMON_VPATH += $(QUANTUM_PATH)/audio
 COMMON_VPATH += $(QUANTUM_PATH)/process_keycode
 COMMON_VPATH += $(QUANTUM_PATH)/api
-COMMON_VPATH += $(DRIVER_PATH)
+COMMON_VPATH += $(QUANTUM_PATH)/split_common
+COMMON_VPATH += $(DRIVER_PATH)

common_features.mk

@@ -34,6 +34,7 @@ ifeq ($(strip $(AUDIO_ENABLE)), yes)
     OPT_DEFS += -DAUDIO_ENABLE
     MUSIC_ENABLE := 1
     SRC += $(QUANTUM_DIR)/process_keycode/process_audio.c
+    SRC += $(QUANTUM_DIR)/process_keycode/process_clicky.c
     ifeq ($(PLATFORM),AVR)
         SRC += $(QUANTUM_DIR)/audio/audio.c
     else
@@ -60,8 +61,8 @@ endif
 
 ifeq ($(strip $(STENO_ENABLE)), yes)
     OPT_DEFS += -DSTENO_ENABLE
-	VIRTSER_ENABLE := yes
-	SRC += $(QUANTUM_DIR)/process_keycode/process_steno.c
+    VIRTSER_ENABLE := yes
+    SRC += $(QUANTUM_DIR)/process_keycode/process_steno.c
 endif
 
 ifeq ($(strip $(VIRTSER_ENABLE)), yes)
@@ -74,9 +75,9 @@ ifeq ($(strip $(FAUXCLICKY_ENABLE)), yes)
 endif
 
 ifeq ($(strip $(POINTING_DEVICE_ENABLE)), yes)
-	OPT_DEFS += -DPOINTING_DEVICE_ENABLE
-	OPT_DEFS += -DMOUSE_ENABLE
-	SRC += $(QUANTUM_DIR)/pointing_device.c
+    OPT_DEFS += -DPOINTING_DEVICE_ENABLE
+    OPT_DEFS += -DMOUSE_ENABLE
+    SRC += $(QUANTUM_DIR)/pointing_device.c
 endif
 
 ifeq ($(strip $(UCIS_ENABLE)), yes)
@@ -109,10 +110,41 @@ ifeq ($(strip $(RGBLIGHT_ENABLE)), yes)
     ifeq ($(strip $(RGBLIGHT_CUSTOM_DRIVER)), yes)
         OPT_DEFS += -DRGBLIGHT_CUSTOM_DRIVER
     else
-	    SRC += ws2812.c
+        SRC += ws2812.c
     endif
 endif
 
+RGB_MATRIX_ENABLE ?= no
+VALID_MATRIX_TYPES := yes IS31FL3731 IS31FL3733 custom
+ifneq ($(strip $(RGB_MATRIX_ENABLE)), no)
+ifeq ($(filter $(RGB_MATRIX_ENABLE),$(VALID_MATRIX_TYPES)),)
+    $(error RGB_MATRIX_ENABLE="$(RGB_MATRIX_ENABLE)" is not a valid matrix type)
+endif
+    OPT_DEFS += -DRGB_MATRIX_ENABLE
+    SRC += $(QUANTUM_DIR)/color.c
+    SRC += $(QUANTUM_DIR)/rgb_matrix.c
+    SRC += $(QUANTUM_DIR)/rgb_matrix_drivers.c
+    CIE1931_CURVE = yes
+endif
+
+ifeq ($(strip $(RGB_MATRIX_ENABLE)), yes)
+	RGB_MATRIX_ENABLE = IS31FL3731
+endif
+
+ifeq ($(strip $(RGB_MATRIX_ENABLE)), IS31FL3731)
+    OPT_DEFS += -DIS31FL3731
+    COMMON_VPATH += $(DRIVER_PATH)/issi
+    SRC += is31fl3731.c
+    SRC += i2c_master.c
+endif
+
+ifeq ($(strip $(RGB_MATRIX_ENABLE)), IS31FL3733)
+    OPT_DEFS += -DIS31FL3733
+    COMMON_VPATH += $(DRIVER_PATH)/issi
+    SRC += is31fl3733.c
+    SRC += i2c_master.c
+endif
+
 ifeq ($(strip $(TAP_DANCE_ENABLE)), yes)
     OPT_DEFS += -DTAP_DANCE_ENABLE
     SRC += $(QUANTUM_DIR)/process_keycode/process_tap_dance.c
@@ -159,7 +191,7 @@ ifeq ($(strip $(BACKLIGHT_ENABLE)), yes)
     ifeq ($(strip $(VISUALIZER_ENABLE)), yes)
         CIE1931_CURVE = yes
     endif
-		ifeq ($(strip $(BACKLIGHT_CUSTOM_DRIVER)), yes)
+        ifeq ($(strip $(BACKLIGHT_CUSTOM_DRIVER)), yes)
         OPT_DEFS += -DBACKLIGHT_CUSTOM_DRIVER
     endif
 endif
@@ -187,12 +219,38 @@ ifeq ($(strip $(USB_HID_ENABLE)), yes)
     include $(TMK_DIR)/protocol/usb_hid.mk
 endif
 
+ifeq ($(strip $(HD44780_ENABLE)), yes)
+    SRC += drivers/avr/hd44780.c
+    OPT_DEFS += -DHD44780_ENABLE
+endif
+
+ifeq ($(strip $(DYNAMIC_KEYMAP_ENABLE)), yes)
+    OPT_DEFS += -DDYNAMIC_KEYMAP_ENABLE
+    SRC += $(QUANTUM_DIR)/dynamic_keymap.c
+endif
+
+ifeq ($(strip $(LEADER_ENABLE)), yes)
+  SRC += $(QUANTUM_DIR)/process_keycode/process_leader.c
+  OPT_DEFS += -DLEADER_ENABLE
+endif
+
 QUANTUM_SRC:= \
     $(QUANTUM_DIR)/quantum.c \
     $(QUANTUM_DIR)/keymap_common.c \
-    $(QUANTUM_DIR)/keycode_config.c \
-    $(QUANTUM_DIR)/process_keycode/process_leader.c
+    $(QUANTUM_DIR)/keycode_config.c
 
 ifndef CUSTOM_MATRIX
-    QUANTUM_SRC += $(QUANTUM_DIR)/matrix.c
+    ifeq ($(strip $(SPLIT_KEYBOARD)), yes)
+        QUANTUM_SRC += $(QUANTUM_DIR)/split_common/matrix.c
+    else
+        QUANTUM_SRC += $(QUANTUM_DIR)/matrix.c
+    endif
+endif
+
+ifeq ($(strip $(SPLIT_KEYBOARD)), yes)
+    OPT_DEFS += -DSPLIT_KEYBOARD
+    QUANTUM_SRC += $(QUANTUM_DIR)/split_common/split_flags.c \
+                $(QUANTUM_DIR)/split_common/split_util.c \
+                $(QUANTUM_DIR)/split_common/i2c.c \
+                $(QUANTUM_DIR)/split_common/serial.c
 endif

docs/CNAME

@@ -0,0 +1 @@
+docs.qmk.fm

docs/README.md

@@ -1,16 +1,23 @@
 # Quantum Mechanical Keyboard Firmware
 
-## What is QMK Firmware? {#what-is-qmk-firmware}
+[![Current Version](https://img.shields.io/github/tag/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/tags)
+[![Build Status](https://travis-ci.org/qmk/qmk_firmware.svg?branch=master)](https://travis-ci.org/qmk/qmk_firmware)
+[![Discord](https://img.shields.io/discord/440868230475677696.svg)](https://discord.gg/Uq7gcHh)
+[![Docs Status](https://img.shields.io/badge/docs-ready-orange.svg)](https://docs.qmk.fm)
+[![GitHub contributors](https://img.shields.io/github/contributors/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/pulse/monthly)
+[![GitHub forks](https://img.shields.io/github/forks/qmk/qmk_firmware.svg?style=social&label=Fork)](https://github.com/qmk/qmk_firmware/)
 
-QMK (*Quantum Mechanical Keyboard*) is an open source community that maintains QMK Firmware, QMK Flasher, qmk.fm, and these docs. QMK Firmware is a keyboard firmware based on the [tmk\_keyboard](http://github.com/tmk/tmk_keyboard) with some useful features for Atmel AVR controllers, and more specifically, the [OLKB product line](http://olkb.com), the [ErgoDox EZ](http://www.ergodox-ez.com) keyboard, and the [Clueboard product line](http://clueboard.co/). It has also been ported to ARM chips using ChibiOS. You can use it to power your own hand-wired or custom keyboard PCB.
+## What is QMK Firmware?
 
-## How to Get It {#how-to-get-it}
+QMK (*Quantum Mechanical Keyboard*) is an open source community that maintains QMK Firmware, QMK Toolbox, qmk.fm, and these docs. QMK Firmware is a keyboard firmware based on the [tmk\_keyboard](http://github.com/tmk/tmk_keyboard) with some useful features for Atmel AVR controllers, and more specifically, the [OLKB product line](http://olkb.com), the [ErgoDox EZ](http://www.ergodox-ez.com) keyboard, and the [Clueboard product line](http://clueboard.co/). It has also been ported to ARM chips using ChibiOS. You can use it to power your own hand-wired or custom keyboard PCB.
+
+## How to Get It
 
 If you plan on contributing a keymap, keyboard, or features to QMK, the easiest thing to do is [fork the repo through Github](https://github.com/qmk/qmk_firmware#fork-destination-box), and clone your repo locally to make your changes, push them, then open a [Pull Request](https://github.com/qmk/qmk_firmware/pulls) from your fork.
 
 Otherwise, you can either download it directly ([zip](https://github.com/qmk/qmk_firmware/zipball/master), [tar](https://github.com/qmk/qmk_firmware/tarball/master)), or clone it via git (`git@github.com:qmk/qmk_firmware.git`), or https (`https://github.com/qmk/qmk_firmware.git`).
 
-## How to Compile {#how-to-compile}
+## How to Compile
 
 Before you are able to compile, you'll need to [install an environment](getting_started_build_tools.md) for AVR or/and ARM development. Once that is complete, you'll use the `make` command to build a keyboard and keymap with the following notation:
 
@@ -20,6 +27,6 @@ This would build the `rev4` revision of the `planck` with the `default` keymap.
 
     make preonic:default
 
-## How to Customize {#how-to-customize}
+## How to Customize
 
 QMK has lots of [features](features.md) to explore, and a good deal of [reference documentation](http://docs.qmk.fm) to dig through. Most features are taken advantage of by modifying your [keymap](keymap.md), and changing the [keycodes](keycodes.md).

docs/_sidebar.md

@@ -0,0 +1,92 @@
+* [Complete Newbs Guide](newbs.md)
+  * [Getting Started](newbs_getting_started.md)
+  * [Building Your First Firmware](newbs_building_firmware.md)
+  * [Flashing Firmware](newbs_flashing.md)
+  * [Testing and Debugging](newbs_testing_debugging.md)
+
+* [QMK Basics](README.md)
+  * [QMK Introduction](getting_started_introduction.md)
+  * [Contributing to QMK](contributing.md)
+  * [How to Use Github](getting_started_github.md)
+  * [Getting Help](getting_started_getting_help.md)
+
+* [FAQ](faq.md)
+  * [General FAQ](faq_general.md)
+  * [Build/Compile QMK](faq_build.md)
+  * [Debugging/Troubleshooting QMK](faq_debug.md)
+  * [Keymap](faq_keymap.md)
+
+* Detailed Guides
+  * [Install Build Tools](getting_started_build_tools.md)
+  * [Vagrant Guide](getting_started_vagrant.md)
+  * [Build/Compile Instructions](getting_started_make_guide.md)
+  * [Flashing Firmware](flashing.md)
+  * [Customizing Functionality](custom_quantum_functions.md)
+  * [Keymap Overview](keymap.md)
+
+* [Hardware](hardware.md)
+  * [AVR Processors](hardware_avr.md)
+  * [Drivers](hardware_drivers.md)
+
+* Reference
+  * [Keyboard Guidelines](hardware_keyboard_guidelines.md)
+  * [Config Options](config_options.md)
+  * [Keycodes](keycodes.md)
+  * [Documentation Best Practices](documentation_best_practices.md)
+  * [Documentation Templates](documentation_templates.md)
+  * [Glossary](reference_glossary.md)
+  * [Unit Testing](unit_testing.md)
+  * [Useful Functions](ref_functions.md)
+
+* [Features](features.md)
+  * [Basic Keycodes](keycodes_basic.md)
+  * [Quantum Keycodes](quantum_keycodes.md)
+  * [Advanced Keycodes](feature_advanced_keycodes.md)
+  * [Audio](feature_audio.md)
+  * [Auto Shift](feature_auto_shift.md)
+  * [Backlight](feature_backlight.md)
+  * [Bluetooth](feature_bluetooth.md)
+  * [Bootmagic](feature_bootmagic.md)
+  * [Command](feature_command.md)
+  * [Dynamic Macros](feature_dynamic_macros.md)
+  * [Grave Escape](feature_grave_esc.md)
+  * [Key Lock](feature_key_lock.md)
+  * [Layouts](feature_layouts.md)
+  * [Leader Key](feature_leader_key.md)
+  * [Macros](feature_macros.md)
+  * [Mouse Keys](feature_mouse_keys.md)
+  * [One Shot Keys](feature_advanced_keycodes.md#one-shot-keys)
+  * [Pointing Device](feature_pointing_device.md)
+  * [PS/2 Mouse](feature_ps2_mouse.md)
+  * [RGB Lighting](feature_rgblight.md)
+  * [RGB Matrix](feature_rgb_matrix.md)
+  * [Space Cadet Shift](feature_space_cadet_shift.md)
+  * [Space Cadet Shift Enter](feature_space_cadet_shift_enter.md)
+  * [Stenography](feature_stenography.md)
+  * [Swap Hands](feature_swap_hands.md)
+  * [Tap Dance](feature_tap_dance.md)
+  * [Terminal](feature_terminal.md)
+  * [Thermal Printer](feature_thermal_printer.md)
+  * [Unicode](feature_unicode.md)
+  * [Userspace](feature_userspace.md)
+  * [US ANSI Shifted Keys](keycodes_us_ansi_shifted.md)
+
+* For Makers and Modders
+  * [Hand Wiring Guide](hand_wire.md)
+  * [ISP Flashing Guide](isp_flashing_guide.md)
+
+* For a Deeper Understanding
+  * [How Keyboards Work](how_keyboards_work.md)
+  * [Understanding QMK](understanding_qmk.md)
+
+* Other Topics
+  * [Using Eclipse with QMK](eclipse.md)
+
+* QMK Internals (In Progress)
+  * [Defines](internals_defines.md)
+  * [Input Callback Reg](internals_input_callback_reg.md)
+  * [Midi Device](internals_midi_device.md)
+  * [Midi Device Setup Process](internals_midi_device_setup_process.md)
+  * [Midi Util](internals_midi_util.md)
+  * [Send Functions](internals_send_functions.md)
+  * [Sysex Tools](internals_sysex_tools.md)

docs/_summary.md

@@ -1,36 +1,51 @@
-* [Getting Started](README.md)
-  * [QMK Introduction](getting_started_introduction.md)
-  * [Install Build Tools](getting_started_build_tools.md)
-    * Alternative: [Vagrant Guide](getting_started_vagrant.md)
-  * [Build/Compile Instructions](getting_started_make_guide.md)
-  * [Flashing Firmware](flashing.md)
-  * [Contributing to QMK](contributing.md)
-  * [How to Use Github](getting_started_github.md)
-  * [Getting Help](getting_started_getting_help.md)
-
 * [Complete Newbs Guide](newbs.md)
   * [Getting Started](newbs_getting_started.md)
   * [Building Your First Firmware](newbs_building_firmware.md)
   * [Flashing Firmware](newbs_flashing.md)
   * [Testing and Debugging](newbs_testing_debugging.md)
 
+* [QMK Basics](README.md)
+  * [QMK Introduction](getting_started_introduction.md)
+  * [Contributing to QMK](contributing.md)
+  * [How to Use Github](getting_started_github.md)
+  * [Getting Help](getting_started_getting_help.md)
+
 * [FAQ](faq.md)
   * [General FAQ](faq_general.md)
   * [Build/Compile QMK](faq_build.md)
   * [Debugging/Troubleshooting QMK](faq_debug.md)
   * [Keymap](faq_keymap.md)
 
+* Detailed Guides
+  * [Install Build Tools](getting_started_build_tools.md)
+  * [Vagrant Guide](getting_started_vagrant.md)
+  * [Build/Compile Instructions](getting_started_make_guide.md)
+  * [Flashing Firmware](flashing.md)
+  * [Customizing Functionality](custom_quantum_functions.md)
+  * [Keymap Overview](keymap.md)
+
 * [Hardware](hardware.md)
-  * [Keyboard Guidelines](hardware_keyboard_guidelines.md)
   * [AVR Processors](hardware_avr.md)
-  * ARM Processors (TBD)
   * [Drivers](hardware_drivers.md)
 
+* Reference
+  * [Keyboard Guidelines](hardware_keyboard_guidelines.md)
+  * [Config Options](config_options.md)
+  * [Keycodes](keycodes.md)
+  * [Documentation Best Practices](documentation_best_practices.md)
+  * [Documentation Templates](documentation_templates.md)
+  * [Glossary](reference_glossary.md)
+  * [Unit Testing](unit_testing.md)
+  * [Useful Functions](ref_functions.md)
+
 * [Features](features.md)
+  * [Basic Keycodes](keycodes_basic.md)
+  * [Quantum Keycodes](quantum_keycodes.md)
   * [Advanced Keycodes](feature_advanced_keycodes.md)
   * [Audio](feature_audio.md)
   * [Auto Shift](feature_auto_shift.md)
   * [Backlight](feature_backlight.md)
+  * [Bluetooth](feature_bluetooth.md)
   * [Bootmagic](feature_bootmagic.md)
   * [Command](feature_command.md)
   * [Dynamic Macros](feature_dynamic_macros.md)
@@ -40,10 +55,13 @@
   * [Leader Key](feature_leader_key.md)
   * [Macros](feature_macros.md)
   * [Mouse Keys](feature_mouse_keys.md)
+  * [One Shot Keys](feature_advanced_keycodes.md#one-shot-keys)
   * [Pointing Device](feature_pointing_device.md)
   * [PS/2 Mouse](feature_ps2_mouse.md)
   * [RGB Lighting](feature_rgblight.md)
-  * [Space Cadet](feature_space_cadet.md)
+  * [RGB Matrix](feature_rgb_matrix.md)
+  * [Space Cadet Shift](feature_space_cadet_shift.md)
+  * [Space Cadet Shift Enter](feature_space_cadet_shift_enter.md)
   * [Stenography](feature_stenography.md)
   * [Swap Hands](feature_swap_hands.md)
   * [Tap Dance](feature_tap_dance.md)
@@ -51,32 +69,8 @@
   * [Thermal Printer](feature_thermal_printer.md)
   * [Unicode](feature_unicode.md)
   * [Userspace](feature_userspace.md)
-
-* [Keycodes](keycodes.md)
-  * [Backlight](feature_backlight.md#backlight-keycodes)
-  * [Basic](keycodes_basic.md)
-  * [Bluetooth](feature_bluetooth.md#bluetooth-keycodes)
-  * [Bootmagic](feature_bootmagic.md#bootmagic-keycodes)
-  * [Layer Switching](feature_advanced_keycodes.md#switching-and-toggling-layers)
-  * [Mod+Key](feature_advanced_keycodes.md#modifier-keys)
-  * [Mod Tap](feature_advanced_keycodes.md#mod-tap)
-  * [One Shot Keys](feature_advanced_keycodes.md#one-shot-keys)
-  * [Quantum](quantum_keycodes.md)
-  * [RGB Light](feature_rgblight.md#rgblight-keycodes)
-  * [Shifted Keys](feature_advanced_keycodes.md#shifted-keycodes)
-  * [Stenography](feature_stenography.md#keycode-reference)
-  * [Thermal Printer](feature_thermal_printer.md#thermal-printer-keycodes)
   * [US ANSI Shifted Keys](keycodes_us_ansi_shifted.md)
 
-* Reference
-  * [Config Options](config_options.md)
-  * [Customizing Functionality](custom_quantum_functions.md)
-  * [Documentation Best Practices](documentation_best_practices.md)
-  * [Documentation Templates](documentation_templates.md)
-  * [Glossary](reference_glossary.md)
-  * [Keymap Overview](keymap.md)
-  * [Unit Testing](unit_testing.md)
-
 * For Makers and Modders
   * [Hand Wiring Guide](hand_wire.md)
   * [ISP Flashing Guide](isp_flashing_guide.md)

docs/becoming_a_qmk_collaborator.md

@@ -1,7 +1,9 @@
-A QMK collaborator is a keyboard maker/designer that is interested in helping QMK grow and fully support their keyboard(s), and encouraging their users/customers to submit features, ideas, and keymaps. We're always looking to add more keyboards and collaborators, but we ask that they fulfill these requirements:
+# Becoming a QMK Collaborator
 
-* **Have a PCB available for sale** - unfortunately there's just too much variation and complications with handwired keyboards.
-* **Maintain the your keyboard's directory** - this may just require an initial setup to get your keyboard working, but it could also include accommodating changes made to QMK's core.
-* **Approve and merge your keyboard's keymap pull requests** - we like to encourage users to contribute their keymaps for others to see and work from when creating their own.
+A QMK collaborator is a keyboard maker or designer that is interested in helping QMK grow and fully support their keyboard(s), and encouraging their users and customers to submit features, ideas, and keymaps. We're always looking to add more keyboards and collaborators, but we ask that they fulfill these requirements:
+
+* **Have a PCB available for sale.** Unfortunately there's just too much variation and complications with handwired keyboards.
+* **Maintain your keyboard in QMK.** This may just require an initial setup to get your keyboard working, but it could also include accommodating changes made to QMK's core that might break or render any custom code redundant.
+* **Approve and merge keymap pull requests for your keyboard.** We like to encourage users to contribute their keymaps for others to see and work from when creating their own.
 
 If you feel you meet these requirements, shoot us an email at hello@qmk.fm with an introduction and some links to your keyboard!

docs/config_options.md

@@ -61,10 +61,18 @@ This is a C header file that is one of the first things included, and will persi
   * COL2ROW or ROW2COL - how your matrix is configured. COL2ROW means the black mark on your diode is facing to the rows, and between the switch and the rows.
 * `#define AUDIO_VOICES`
   * turns on the alternate audio voices (to cycle through)
+* `#define C4_AUDIO`
+  * enables audio on pin C4
+* `#define C5_AUDIO`
+  * enables audio on pin C5
 * `#define C6_AUDIO`
   * enables audio on pin C6
 * `#define B5_AUDIO`
-  * enables audio on pin B5 (duophony is enable if both are enabled)
+  * enables audio on pin B5 (duophony is enables if one of B[5-7]_AUDIO is enabled along with one of C[4-6]_AUDIO)
+* `#define B6_AUDIO`
+  * enables audio on pin B6 (duophony is enables if one of B[5-7]_AUDIO is enabled along with one of C[4-6]_AUDIO)
+* `#define B7_AUDIO`
+  * enables audio on pin B7 (duophony is enables if one of B[5-7]_AUDIO is enabled along with one of C[4-6]_AUDIO)
 * `#define BACKLIGHT_PIN B7`
   * pin of the backlight - B5, B6, B7 use PWM, others use softPWM
 * `#define BACKLIGHT_LEVELS 3`
@@ -81,6 +89,10 @@ This is a C header file that is one of the first things included, and will persi
   * tries to keep switch state consistent with keyboard LED state
 * `#define IS_COMMAND() ( keyboard_report->mods == (MOD_BIT(KC_LSHIFT) | MOD_BIT(KC_RSHIFT)) )`
   * key combination that allows the use of magic commands (useful for debugging)
+* `#define USB_MAX_POWER_CONSUMPTION`
+  * sets the maximum power (in mA) over USB for the device (default: 500)
+* `#define SCL_CLOCK 100000L`
+  * sets the SCL_CLOCK speed for split keyboards. The default is `100000L` but some boards can be set to `400000L`.
 
 ## Features That Can Be Disabled
 
@@ -107,27 +119,33 @@ If you define these options you will enable the associated feature, which may in
 
 * `#define FORCE_NKRO`
   * NKRO by default requires to be turned on, this forces it on during keyboard startup regardless of EEPROM setting. NKRO can still be turned off but will be turned on again if the keyboard reboots.
-* `#define PREVENT_STUCK_MODIFIERS`
-  * when switching layers, this will release all mods
+* `#define STRICT_LAYER_RELEASE`
+  * force a key release to be evaluated using the current layer stack instead of remembering which layer it came from (used for advanced cases)
 
 ## Behaviors That Can Be Configured
 
 * `#define TAPPING_TERM 200`
-  * how long before a tap becomes a hold
+  * how long before a tap becomes a hold, if set above 500, a key tapped during the tapping term will turn it into a hold too
 * `#define RETRO_TAPPING`
   * tap anyway, even after TAPPING_TERM, if there was no other key interruption between press and release
+  * See [Retro Tapping](feature_advanced_keycodes.md#retro-tapping) for details
 * `#define TAPPING_TOGGLE 2`
   * how many taps before triggering the toggle
 * `#define PERMISSIVE_HOLD`
   * makes tap and hold keys work better for fast typers who don't want tapping term set above 500
+  * See [Permissive Hold](feature_advanced_keycodes.md#permissive-hold) for details
+* `#define IGNORE_MOD_TAP_INTERRUPT`
+  * makes it possible to do rolling combos (zx) with keys that convert to other keys on hold
+  * See [Mod tap interrupt](feature_advanced_keycodes.md#mod-tap-interrupt) for details
+* `#define TAPPING_FORCE_HOLD`
+  * makes it possible to use a dual role key as modifier shortly after having been tapped
+  * See [Hold after tap](feature_advanced_keycodes.md#hold-after-tap)
 * `#define LEADER_TIMEOUT 300`
   * how long before the leader key times out
 * `#define ONESHOT_TIMEOUT 300`
   * how long before oneshot times out
 * `#define ONESHOT_TAP_TOGGLE 2`
   * how many taps before oneshot toggle is triggered
-* `#define IGNORE_MOD_TAP_INTERRUPT`
-  * makes it possible to do rolling combos (zx) with keys that convert to other keys on hold
 * `#define QMK_KEYS_PER_SCAN 4`
   * Allows sending more than one key per scan. By default, only one key event gets
     sent via `process_record()` per scan. This has little impact on most typing, but
@@ -163,6 +181,16 @@ If you define these options you will enable the associated feature, which may in
 * `#define MOUSEKEY_MAX_SPEED 7`
 * `#define MOUSEKEY_WHEEL_DELAY 0`
 
+## Split Keyboard Options
+
+Split Keyboard specific options, make sure you have 'SPLIT_KEYBOARD = yes' in your rules.mk
+
+* `#define SPLIT_HAND_PIN B7`
+  * For using high/low pin to determine handedness, low = right hand, high = left hand. Replace 'B7' with the pin you are using. This is optional and you can still use the EEHANDS method or MASTER_LEFT / MASTER_RIGHT defines like the stock Let's Split uses.
+  
+* `#define USE_I2C`
+  * For using I2C instead of Serial (defaults to serial)
+
 # The `rules.mk` File
 
 This is a [make](https://www.gnu.org/software/make/manual/make.html) file that is included by the top-level `Makefile`. It is used to set some information about the MCU that we will be compiling for as well as enabling and disabling certain features.
@@ -171,6 +199,8 @@ This is a [make](https://www.gnu.org/software/make/manual/make.html) file that i
 
 * `DEFAULT_FOLDER`
   * Used to specify a default folder when a keyboard has more than one sub-folder.
+* `FIRMWARE_FORMAT`
+  * Defines which format (bin, hex) is copied to the root `qmk_firmware` folder after building.
 * `SRC`
   * Used to add files to the compilation/linking list.
 * `LAYOUTS`
@@ -216,3 +246,9 @@ Use these to enable or disable building certain features. The more you have enab
   * Unicode
 * `BLUETOOTH_ENABLE`
   * Enable Bluetooth with the Adafruit EZ-Key HID
+* `SPLIT_KEYBOARD`
+  * Enables split keyboard support (dual MCU like the let's split and bakingpy's boards) and includes all necessary files located at quantum/split_common
+* `WAIT_FOR_USB`
+  * Forces the keyboard to wait for a USB connection to be established before it starts up
+* `NO_USB_STARTUP_CHECK`
+  * Disables usb suspend check after keyboard startup. Usually the keyboard waits for the host to wake it up before any tasks are performed. This is useful for split keyboards as one half will not get a wakeup call but must send commands to the master.

docs/contributing.md

@@ -11,7 +11,7 @@ Third-party contributions help us grow and improve QMK. We want to make the pull
 
 ## I Don't Want to Read This Whole Thing! I Just Have a Question!
 
-If you'd like to ask questions about QMK you can do so on the [OLKB Subreddit](https://reddit.com/r/olkb) or on [Gitter](https://gitter.im/qmk/qmk_firmware).
+If you'd like to ask questions about QMK you can do so on the [OLKB Subreddit](https://reddit.com/r/olkb) or on [Discord](https://discord.gg/Uq7gcHh).
 
 Please keep these things in mind:
 
@@ -29,7 +29,7 @@ QMK is largely written in C, with specific features and parts written in C++. It
 
 # Where Can I Go for Help?
 
-If you need help you can [open an issue](https://github.com/qmk/qmk_firmware/issues) or [chat on gitter](http://gitter.im/QMK/qmk_firmware).
+If you need help you can [open an issue](https://github.com/qmk/qmk_firmware/issues) or [chat on Discord](https://discord.gg/Uq7gcHh).
 
 # How Do I Make a Contribution?
 
@@ -70,6 +70,7 @@ Most of our style is pretty easy to pick up on, but right now it's not entirely
   * Do not write obvious comments
   * If you not sure if a comment is obvious, go ahead and include it.
 * In general we don't wrap lines, they can be as long as needed. If you do choose to wrap lines please do not wrap any wider than 76 columns.
+* We use `#pragma once` at the start of header files rather than old-style include guards (`#ifndef THIS_FILE_H`, `#define THIS_FILE_H`, ..., `#endif`)
 
 # General Guidelines
 
@@ -101,7 +102,7 @@ You'll find all our documentation in the `qmk_firmware/docs` directory, or if yo
 
 Most first-time QMK contributors start with their personal keymaps. We try to keep keymap standards pretty casual (keymaps, after all, reflect the personality of their creators) but we do ask that you follow these guidelines to make it easier for others to discover and learn from your keymap.
 
-* Write a `readme.md` using [the template](https://docs.qmk.fm/documentation_templates.html#).
+* Write a `readme.md` using [the template](documentation_templates.md).
 * All Keymap PR's are squashed, so if you care about how your commits are squashed you should do it yourself
 * Do not lump features in with keymap PR's. Submit the feature first and then a second PR for the keymap.
 * Do not include `Makefile`s in your keymap folder (they're no longer used)
@@ -113,7 +114,7 @@ Keyboards are the raison d'être for QMK. Some keyboards are community maintaine
 
 We also ask that you follow these guidelines:
 
-* Write a `readme.md` using [the template](https://docs.qmk.fm/documentation_templates.html#).
+* Write a `readme.md` using [the template](documentation_templates.md).
 * Keep the number of commits reasonable or we will squash your PR
 * Do not lump core features in with new keyboards. Submit the feature first and then submit a separate PR for the keyboard.
 * Name `.c`/`.h` file after the immediate parent folder, eg `/keyboards/<kb1>/<kb2>/<kb2>.[ch]`
@@ -124,7 +125,7 @@ We also ask that you follow these guidelines:
 
 Before you put a lot of work into building your new feature you should make sure you are implementing it in the best way. You can get a basic understanding of QMK by reading [Understanding QMK](understanding_qmk.md), which will take you on a tour of the QMK program flow. From here you should talk to us to get a sense of the best way to implement your idea. There are two main ways to do this:
 
-* [Chat on Gitter](https://gitter.im/qmk/qmk_firmware)
+* [Chat on Discord](https://discord.gg/Uq7gcHh)
 * [Open an Issue](https://github.com/qmk/qmk_firmware/issues/new)
 
 Feature and Bug Fix PR's affect all keyboards. We are also in the process of restructuring QMK. For this reason it is especially important for significant changes to be discussed before implementation has happened. If you open a PR without talking to us first please be prepared to do some significant rework if your choices do not mesh well with our planned direction.
@@ -140,7 +141,7 @@ We also ask that you follow these guidelines:
 
 * Keep the number of commits reasonable or we will squash your PR
 * Do not lump keyboards or keymaps in with core changes. Submit your core changes first.
-* Write [Unit Tests](http://docs.qmk.fm/unit_testing.html) for your feature
+* Write [Unit Tests](unit_testing.md) for your feature
 * Follow the style of the file you are editing. If the style is unclear or there are mixed styles you should conform to the [coding conventions](#coding-conventions) above.
 
 ## Refactoring

docs/custom_quantum_functions.md

@@ -135,9 +135,11 @@ void led_set_user(uint8_t usb_led) {
 * Keyboard/Revision: `void led_set_kb(uint8_t usb_led)`
 * Keymap: `void led_set_user(uint8_t usb_led)`
 
+
 # Matrix Initialization Code
 
-Before a keyboard can be used the hardware must be initialized. QMK handles initialization of the keyboard matrix itself, but if you have other hardware like LED's or i²c controllers you will need to set up that hardware before it can be used.
+Before a keyboard can be used the hardware must be initialized. QMK handles initialization of the keyboard matrix itself, but if you have other hardware like LED's or i²c controllers you will need to set up that hardware before it can be used.  
+
 
 ### Example `matrix_init_user()` Implementation
 
@@ -165,7 +167,7 @@ Whenever possible you should customize your keyboard by using `process_record_*(
 
 ### Example `matrix_scan_*` Implementation
 
-This example has been deliberately omitted. You should understand enough about QMK internals to write this without an example before hooking into such a performance sensitive area. If you need help please [open an issue](https://github.com/qmk/qmk_firmware/issues/new) or [chat with us on gitter](https://gitter.im/qmk/qmk_firmware).
+This example has been deliberately omitted. You should understand enough about QMK internals to write this without an example before hooking into such a performance sensitive area. If you need help please [open an issue](https://github.com/qmk/qmk_firmware/issues/new) or [chat with us on Discord](https://discord.gg/Uq7gcHh).
 
 ### `matrix_scan_*` Function Documentation
 
@@ -177,9 +179,38 @@ This function gets called at every matrix scan, which is basically as often as t
 You should use this function if you need custom matrix scanning code. It can also be used for custom status output (such as LED's or a display) or other functionality that you want to trigger regularly even when the user isn't typing.
 
 
+# Keyboard Idling/Wake Code
+
+If the board supports it, it can be "idled", by stopping a number of functions.  A good example of this is RGB lights or backlights.   This can save on power consumption, or may be better behavior for your keyboard.  
+
+This is controlled by two functions: `suspend_power_down_*` and `suspend_wakeup_init_*`, which are called when the system is board is idled and when it wakes up, respectively. 
+
+
+### Example suspend_power_down_user() and suspend_wakeup_init_user() Implementation
+
+This example, at the keyboard level, sets up B1, B2, and B3 as LED pins.
+
+```
+void suspend_power_down_user(void)
+{
+    rgb_matrix_set_suspend_state(true);
+}
+
+void suspend_wakeup_init_user(void)
+{
+    rgb_matrix_set_suspend_state(false);
+}
+
+```
+
+### `keyboard_init_*` Function Documentation
+
+* Keyboard/Revision: `void suspend_power_down_kb(void)` and `void suspend_wakeup_init_user(void)`
+* Keymap: `void suspend_power_down_kb(void)` and `void suspend_wakeup_init_user(void)`
+
 # Layer Change Code
 
-Thir runs code every time that the layers get changed.  This can be useful for layer indication, or custom layer handling. 
+This runs code every time that the layers get changed.  This can be useful for layer indication, or custom layer handling. 
 
 ### Example `layer_state_set_*` Implementation
 

docs/documentation_best_practices.md

@@ -22,60 +22,27 @@ Your page should generally have multiple "H1" headings. Only H1 and H2 headings
 
 You can have styled hint blocks drawn around text to draw attention to it.
 
-```
-{% hint style='info' %}
-This uses `hint style='info'`
-{% endhint %}
-```
-
-### Examples:
-
-{% hint style='info' %}
-This uses `hint style='info'`
-{% endhint %}
-
-{% hint style='tip' %}
-This uses `hint style='tip'`
-{% endhint %}
-
-{% hint style='danger' %}
-This uses `hint style='danger'`
-{% endhint %}
-
-{% hint style='working' %}
-This uses `hint style='working'`
-{% endhint %}
-
-# Styled Terminal Blocks
-
-You can present styled terminal blocks by including special tokens inside your text block.
+### Important
 
 ```
-\`\`\`
-**[terminal]
-**[prompt foo@joe]**[path ~]**[delimiter  $ ]**[command ./myscript]
-Normal output line. Nothing special here...
-But...
-You can add some colors. What about a warning message?
-**[warning [WARNING] The color depends on the theme. Could look normal too]
-What about an error message?
-**[error [ERROR] This is not the error you are looking for]
-\`\`\`
+!> This is important
 ```
 
-### Example
+Renders as:
+
+!> This is important
+
+### General Tips
 
 ```
-**[terminal]
-**[prompt foo@joe]**[path ~]**[delimiter  $ ]**[command ./myscript]
-Normal output line. Nothing special here...
-But...
-You can add some colors. What about a warning message?
-**[warning [WARNING] The color depends on the theme. Could look normal too]
-What about an error message?
-**[error [ERROR] This is not the error you are looking for]
+?> This is a helpful tip.
 ```
 
+Renders as:
+
+?> This is a helpful tip.
+
+
 # Documenting Features
 
 If you create a new feature for QMK, create a documentation page for it. It doesn't have to be very long, a few sentences describing your feature and a table listing any relevant keycodes is enough. Here is a basic template:
@@ -94,4 +61,4 @@ This page describes my cool feature. You can use my cool feature to make coffee
 |KC_SUGAR||Order Sugar|
 ```
 
-Place your documentation into `docs/feature_<my_cool_feature>.md`, and add that file to the appropriate place in `docs/_summary.md`. If you have added any keycodes be sure to add them to `docs/keycodes.md` with a link back to your feature page.
+Place your documentation into `docs/feature_<my_cool_feature>.md`, and add that file to the appropriate place in `docs/_sidebar.md`. If you have added any keycodes be sure to add them to `docs/keycodes.md` with a link back to your feature page.

docs/documentation_templates.md

@@ -36,7 +36,7 @@ Make example for this keyboard (after setting up your build environment):
 
     make planck/rev4:default
 
-See [build environment setup](https://docs.qmk.fm/build_environment_setup.html) then the [make instructions](https://docs.qmk.fm/make_instructions.html) for more information.
+See the [build environment setup](https://docs.qmk.fm/#/getting_started_build_tools) and the [make instructions](https://docs.qmk.fm/#/getting_started_make_guide) for more information. Brand new to QMK? Start with our [Complete Newbs Guide](https://docs.qmk.fm/#/newbs).
 ```
 
 There needs to be two spaces at the end of the `Keyboard Maintainer` and `Hardware Supported` lines for it to render correctly with Markdown.

docs/faq_build.md

@@ -104,3 +104,17 @@ brew install dfu-programmer
 brew install gcc-arm-none-eabi
 brew install avrdude
 ```
+
+### avr-gcc 8.1 and LUFA
+
+If you updated your avr-gcc to above 7 you may see errors involving LUFA. For example:
+
+`lib/lufa/LUFA/Drivers/USB/Class/Device/AudioClassDevice.h:380:5: error: 'const' attribute on function returning 'void'`
+
+For now, you need to rollback avr-gcc to 7 in brew.
+
+```
+brew uninstall --force avr-gcc
+brew install avr-gcc@7
+brew link avr-gcc@7
+```

docs/faq_keymap.md

@@ -11,8 +11,8 @@ Keycodes are actually defined in [common/keycode.h](https://github.com/qmk/qmk_f
 
 There are 3 standard keyboard layouts in use around the world- ANSI, ISO, and JIS. North America primarily uses ANSI, Europe and Africa primarily use ISO, and Japan uses JIS. Regions not mentioned typically use either ANSI or ISO. The keycodes corresponding to these layouts are shown here:
 
-<!-- Source for this image: http://www.keyboard-layout-editor.com/#/gists/9ce023dc6caadc0cf11c88c782350a8c -->
-![Keyboard Layout Image](https://i.imgur.com/45m4mRf.png)
+<!-- Source for this image: http://www.keyboard-layout-editor.com/#/gists/070a530eedaed36a2d77f3f6fd455677 -->
+![Keyboard Layout Image](https://i.imgur.com/gvlNUpQ.png)
 
 ## Some Of My Keys Are Swapped Or Not Working
 
@@ -34,12 +34,11 @@ See [issue #168](https://github.com/tmk/tmk_keyboard/issues/168) and
 * http://en.wikipedia.org/wiki/Magic_SysRq_key
 * http://en.wikipedia.org/wiki/System_request
 
-## Power Key Doesn't Work
-Use `KC_PWR` instead of `KC_POWER` or vice versa.
-* `KC_PWR` works with Windows and Linux, not with OSX.
-* `KC_POWER` works with OSX and Linux, not with Windows.
+## Power Keys Aren't Working
 
-More info: http://geekhack.org/index.php?topic=14290.msg1327264#msg1327264
+Somewhat confusingly, there are two "Power" keycodes in QMK: `KC_POWER` in the Keyboard/Keypad HID usage page, and `KC_SYSTEM_POWER` (or `KC_PWR`) in the Consumer page.
+
+The former is only recognized on macOS, while the latter, `KC_SLEP` and `KC_WAKE` are supported by all three major operating systems, so it is recommended to use those instead. Under Windows, these keys take effect immediately, however on macOS they must be held down until a dialog appears.
 
 ## One Shot Modifier
 Solves my personal 'the' problem. I often got 'the' or 'THe' wrongly instead of 'The'.  One Shot Shift mitigates this for me.
@@ -87,14 +86,14 @@ On **Xorg** you can use `compose` key, instead.
 And see this for **Unicode** input.
 * http://en.wikipedia.org/wiki/Unicode_input
 
+## `Fn` Key on macOS
 
-## Apple/Mac Keyboard `Fn`
-Not supported.
+Unlike most Fn keys, the one on Apple keyboards actually has its own keycode... sort of. It takes the place of the sixth keycode in a basic 6KRO HID report -- so an Apple keyboard is in fact only 5KRO.
 
-Apple/Mac keyboard sends keycode for Fn unlike most of other keyboards.
-I think you can send Apple Fn key using Apple venter specific Page 0xff01 and usage 0x0003. But you have to change HID Report Descriptor for this, of course.
+It is technically possible to get QMK to send this key. However, doing so requires modification of the report format to add the state of the Fn key.
+Even worse, it is not recognized unless the keyboard's VID and PID match that of a real Apple keyboard. The legal issues that official QMK support for this feature may create mean it is unlikely to happen.
 
-https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/AppleHIDUsageTables.h
+See [this issue](https://github.com/qmk/qmk_firmware/issues/2179) for detailed information.
 
 
 ## Media Control Keys in Mac OSX

docs/feature_advanced_keycodes.md

@@ -1,6 +1,6 @@
 # Advanced Keycodes
 
-Your keymap can include keycodes that are more advanced than normal, for example shifted keys. This page documents the functions that are available to you.
+Your keymap can include keycodes that are more advanced than normal, for example keys that switch layers or send modifiers when held, but send regular keycodes when tapped. This page documents the functions that are available to you.
 
 ### Assigning Custom Names
 
@@ -13,20 +13,23 @@ People often define custom names using `#define`. For example:
 
 This will allow you to use `FN_CAPS` and `ALT_TAB` in your `KEYMAP()`, keeping it more readable.
 
-### Limits of These Aliases
+### Caveats
 
-Currently, the keycodes able to used with these functions are limited to the [Basic Keycodes](keycodes_basic.md), meaning you can't use keycodes like `KC_TILD`, or anything greater than 0xFF. For a full list of the keycodes able to be used see [Basic Keycodes](keycodes_basic.md).
+Currently, `LT()` and `MT()` are limited to the [Basic Keycode set](keycodes_basic.md), meaning you can't use keycodes like `LCTL()`, `KC_TILD`, or anything greater than `0xFF`. Modifiers specified as part of a Layer Tap or Mod Tap's keycode will be ignored.
+
+Additionally, if at least one right-handed modifier is specified in a Mod Tap or Layer Tap, it will cause all modifiers specified to become right-handed, so it is not possible to mix and match the two.
 
 # Switching and Toggling Layers
 
-These functions allow you to activate layers in various ways.
+These functions allow you to activate layers in various ways. Note that layers are not generally independent layouts -- multiple layers can be activated at once, and it's typical for layers to use `KC_TRNS` to allow keypresses to pass through to lower layers. For a detailed explanation of layers, see [Keymap Overview](keymap.md#keymap-and-layers)
 
-* `MO(layer)` - momentary switch to *layer*. As soon as you let go of the key, the layer is deactivated and you pop back out to the previous layer.
-* `LT(layer, kc)` - momentary switch to *layer* when held, and *kc* when tapped.
-* `TG(layer)` - toggles a layer on or off.
-* `TO(layer)` - Goes to a layer. This code is special, because it lets you go either up or down the stack -- just goes directly to the layer you want. So while other codes only let you go _up_ the stack (from layer 0 to layer 3, for example), `TO(2)` is going to get you to layer 2, no matter where you activate it from -- even if you're currently on layer 5. This gets activated on keydown (as soon as the key is pressed).
-* `TT(layer)` - Layer Tap-Toggle. If you hold the key down, the layer becomes active, and then deactivates when you let go. And if you repeatedly tap it, the layer simply becomes active (toggles on). It needs 5 taps by default, but you can set it by defining `TAPPING_TOGGLE`, for example, `#define TAPPING_TOGGLE 2` for just two taps.
-* `LM(layer, mod)` - Momentary switch to *layer* (like MO), but with modifier(s) *mod* active. Only supports layers 0-15 and the left modifiers.
+* `DF(layer)` - switches the default layer. The default layer is the always-active base layer that other layers stack on top of. See below for more about the default layer. This might be used to switch from QWERTY to Dvorak layout. (Note that this is a temporary switch that only persists until the keyboard loses power. To modify the default layer in a persistent way requires deeper customization, such as calling the `set_single_persistent_default_layer` function inside of [process_record_user](custom_quantum_functions.md#programming-the-behavior-of-any-keycode).)
+* `MO(layer)` - momentarily activates *layer*. As soon as you let go of the key, the layer is deactivated. 
+* `LM(layer, mod)` - Momentarily activates *layer* (like `MO`), but with modifier(s) *mod* active. Only supports layers 0-15 and the left modifiers.
+* `LT(layer, kc)` - momentarily activates *layer* when held, and sends *kc* when tapped.
+* `TG(layer)` - toggles *layer*, activating it if it's inactive and vice versa
+* `TO(layer)` - activates *layer* and de-activates all other layers (except your default layer). This function is special, because instead of just adding/removing one layer to your active layer stack, it will completely replace your current active layers, uniquely allowing you to replace higher layers with a lower one. This is activated on keydown (as soon as the key is pressed).
+* `TT(layer)` - Layer Tap-Toggle. If you hold the key down, *layer* is activated, and then is de-activated when you let go (like `MO`). If you repeatedly tap it, the layer will be toggled on or off (like `TG`). It needs 5 taps by default, but you can change this by defining `TAPPING_TOGGLE` -- for example, `#define TAPPING_TOGGLE 2` to toggle on just two taps.
 
 # Working with Layers
 
@@ -36,9 +39,9 @@ Care must be taken when switching layers, it's possible to lock yourself into a
 
 If you are just getting started with QMK you will want to keep everything simple. Follow these guidelines when setting up your layers:
 
-* Setup layer 0 as your "base" layer. This is your normal typing layer, and could be whatever layout you want (qwerty, dvorak, colemak, etc.)
+* Setup layer 0 as your default, "base" layer. This is your normal typing layer, and could be whatever layout you want (qwerty, dvorak, colemak, etc.). It's important to set this as the lowest layer since it will typically have most or all of the keyboard's keys defined, so would block other layers from having any effect if it were above them (i.e., had a higher layer number). 
 * Arrange your layers in a "tree" layout, with layer 0 as the root. Do not try to enter the same layer from more than one other layer.
-* Never try to stack a higher numbered layer on top of a lower numbered layer. Doing so is tricky and error prone.
+* In a layer's keymap, only reference higher-numbered layers. Because layers are processed from the highest-numbered (topmost) active layer down, modifying the state of lower layers can be tricky and error-prone.
 
 ### Intermediate Users
 
@@ -54,87 +57,73 @@ Sometimes, you might want to switch between layers in a macro or as part of a ta
 
 # Modifier Keys
 
-These functions allow you to combine a mod with a keycode. When pressed the keydown for the mod will be sent first, and then *kc* will be sent. When released the keyup for *kc* will be sent and then the mod will be sent.
+These allow you to combine a modifier with a keycode. When pressed, the keydown event for the modifier, then `kc` will be sent. On release, the keyup event for `kc`, then the modifier will be sent.
 
-* `LSFT(kc)` or `S(kc)` - applies left Shift to *kc* (keycode)
-* `RSFT(kc)` - applies right Shift to *kc*
-* `LCTL(kc)` - applies left Control to *kc*
-* `RCTL(kc)` - applies right Control to *kc*
-* `LALT(kc)` - applies left Alt to *kc*
-* `RALT(kc)` - applies right Alt to *kc*
-* `LGUI(kc)` - applies left GUI (command/win) to *kc*
-* `RGUI(kc)` - applies right GUI (command/win) to *kc*
-* `HYPR(kc)` - applies Hyper (all modifiers) to *kc*
-* `MEH(kc)`  - applies Meh (all modifiers except Win/Cmd) to *kc*
-* `LCAG(kc)` - applies CtrlAltGui to *kc*
+|Key       |Aliases               |Description                                         |
+|----------|----------------------|----------------------------------------------------|
+|`LCTL(kc)`|                      |Hold Left Control and press `kc`                    |
+|`LSFT(kc)`|`S(kc)`               |Hold Left Shift and press `kc`                      |
+|`LALT(kc)`|                      |Hold Left Alt and press `kc`                        |
+|`LGUI(kc)`|`LCMD(kc)`, `LWIN(kc)`|Hold Left GUI and press `kc`                        |
+|`RCTL(kc)`|                      |Hold Right Control and press `kc`                   |
+|`RSFT(kc)`|                      |Hold Right Shift and press `kc`                     |
+|`RALT(kc)`|                      |Hold Right Alt and press `kc`                       |
+|`RGUI(kc)`|`RCMD(kc)`, `LWIN(kc)`|Hold Right GUI and press `kc`                       |
+|`HYPR(kc)`|                      |Hold Left Control, Shift, Alt and GUI and press `kc`|
+|`MEH(kc)` |                      |Hold Left Control, Shift and Alt and press `kc`     |
+|`LCAG(kc)`|                      |Hold Left Control, Alt and GUI and press `kc`       |
+|`ALTG(kc)`|                      |Hold Right Control and Alt and press `kc`           |
+|`SGUI(kc)`|`SCMD(kc)`, `SWIN(kc)`|Hold Left Shift and GUI and press `kc`              |
+|`LCA(kc)` |                      |Hold Left Control and Alt and press `kc`            |
 
-You can also chain these, like this:
+You can also chain them, for example `LCTL(LALT(KC_DEL))` makes a key that sends Control+Alt+Delete with a single keypress.
 
-    LALT(LCTL(KC_DEL)) -- this makes a key that sends Alt, Control, and Delete in a single keypress.
+# Mod-Tap
 
-# Shifted Keycodes
+The Mod-Tap key `MT(mod, kc)` acts like a modifier when held, and a regular keycode when tapped. In other words, you can have a key that sends Escape when you tap it, but functions as a Control or Shift key when you hold it down.
 
-The following shortcuts automatically add `LSFT()` to keycodes to get commonly used symbols.
+The modifiers this keycode and `OSM()` accept are prefixed with `MOD_`, not `KC_`:
 
-|Key                     |Aliases           |Description        |
-|------------------------|------------------|-------------------|
-|`KC_TILDE`              |`KC_TILD`         |`~`                |
-|`KC_EXCLAIM`            |`KC_EXLM`         |`!`                |
-|`KC_AT`                 |                  |`@`                |
-|`KC_HASH`               |                  |`#`                |
-|`KC_DOLLAR`             |`KC_DLR`          |`$`                |
-|`KC_PERCENT`            |`KC_PERC`         |`%`                |
-|`KC_CIRCUMFLEX`         |`KC_CIRC`         |`^`                |
-|`KC_AMPERSAND`          |`KC_AMPR`         |`&`                |
-|`KC_ASTERISK`           |`KC_ASTR`         |`*`                |
-|`KC_LEFT_PAREN`         |`KC_LPRN`         |`(`                |
-|`KC_RIGHT_PAREN`        |`KC_RPRN`         |`)`                |
-|`KC_UNDERSCORE`         |`KC_UNDS`         |`_`                |
-|`KC_PLUS`               |                  |`+`                |
-|`KC_LEFT_CURLY_BRACE`   |`KC_LCBR`         |`{`                |
-|`KC_RIGHT_CURLY_BRACE`  |`KC_RCBR`         |`}`                |
-|`KC_PIPE`               |                  |<code>&#124;</code>|
-|`KC_COLON`              |`KC_COLN`         |`:`                |
-|`KC_DOUBLE_QUOTE`       |`KC_DQT`/`KC_DQUO`|`"`                |
-|`KC_LEFT_ANGLE_BRACKET` |`KC_LT`/`KC_LABK` |`<`                |
-|`KC_RIGHT_ANGLE_BRACKET`|`KC_GT`/`KC_RABK` |`>`                |
-|`KC_QUESTION`           |`KC_QUES`         |`?`                |
+|Modifier  |Description                             |
+|----------|----------------------------------------|
+|`MOD_LCTL`|Left Control                            |
+|`MOD_LSFT`|Left Shift                              |
+|`MOD_LALT`|Left Alt                                |
+|`MOD_LGUI`|Left GUI (Windows/Command/Meta key)     |
+|`MOD_RCTL`|Right Control                           |
+|`MOD_RSFT`|Right Shift                             |
+|`MOD_RALT`|Right Alt                               |
+|`MOD_RGUI`|Right GUI (Windows/Command/Meta key)    |
+|`MOD_HYPR`|Hyper (Left Control, Shift, Alt and GUI)|
+|`MOD_MEH` |Meh (Left Control, Shift, and Alt)      |
 
-# Mod Tap
+You can combine these by ORing them together like so:
 
-`MT(mod, kc)` - is *mod* (modifier key - MOD_LCTL, MOD_LSFT) when held, and *kc* when tapped. In other words, you can have a key that sends Esc (or the letter O or whatever) when you tap it, but works as a Control key or a Shift key when you hold it down.
+```c
+MT(MOD_LCTL | MOD_LSFT, KC_ESC)
+```
 
-These are the values you can use for the `mod` in `MT()` and `OSM()`:
+This key would activate Left Control and Left Shift when held, and send Escape when tapped.
 
-  * MOD_LCTL
-  * MOD_LSFT
-  * MOD_LALT
-  * MOD_LGUI
-  * MOD_RCTL
-  * MOD_RSFT
-  * MOD_RALT
-  * MOD_RGUI
-  * MOD_HYPR
-  * MOD_MEH
+For convenience, QMK includes some Mod-Tap shortcuts to make common combinations more compact in your keymap:
 
-These can also be combined like `MOD_LCTL | MOD_LSFT` e.g. `MT(MOD_LCTL | MOD_LSFT, KC_ESC)` which would activate Control and Shift when held, and send Escape when tapped.
-
-We've added shortcuts to make common modifier/tap (mod-tap) mappings more compact:
-
-  * `CTL_T(kc)` - is LCTL when held and *kc* when tapped
-  * `SFT_T(kc)` - is LSFT when held and *kc* when tapped
-  * `ALT_T(kc)` - is LALT when held and *kc* when tapped
-  * `ALGR_T(kc)` - is AltGr when held and *kc* when tapped
-  * `GUI_T(kc)` - is LGUI when held and *kc* when tapped
-  * `ALL_T(kc)` - is Hyper (all mods) when held and *kc* when tapped. To read more about what you can do with a Hyper key, see [this blog post by Brett Terpstra](http://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/)
-  * `LCAG_T(kc)` - is CtrlAltGui when held and *kc* when tapped
-  * `MEH_T(kc)` - is like Hyper, but not as cool -- does not include the Cmd/Win key, so just sends Alt+Ctrl+Shift.
-
-{% hint style='info' %}
-Due to the way that keycodes are structured, any modifiers specified as part of `kc`, such as `LCTL()` or `KC_LPRN`, will only activate when held instead of tapped.
-
-Additionally, if there is at least one right modifier, any other modifiers will turn into their right equivalents, so it is not possible to "mix and match" the two.
-{% endhint %}
+|Key         |Aliases                                |Description                                            |
+|------------|---------------------------------------|-------------------------------------------------------|
+|`LCTL_T(kc)`|`CTL_T(kc)`                            |Left Control when held, `kc` when tapped               |
+|`RCTL_T(kc)`|                                       |Right Control when held, `kc` when tapped              |
+|`LSFT_T(kc)`|`SFT_T(kc)`                            |Left Shift when held, `kc` when tapped                 |
+|`RSFT_T(kc)`|                                       |Right Shift when held, `kc` when tapped                |
+|`LALT_T(kc)`|`ALT_T(kc)`                            |Left Alt when held, `kc` when tapped                   |
+|`RALT_T(kc)`|`ALGR_T(kc)`                           |Right Alt when held, `kc` when tapped                  |
+|`LGUI_T(kc)`|`LCMD_T(kc)`, `RWIN_T(kc)`, `GUI_T(kc)`|Left GUI when held, `kc` when tapped                   |
+|`RGUI_T(kc)`|`RCMD_T(kc)`, `RWIN_T(kc)`             |Right GUI when held, `kc` when tapped                  |
+|`C_S_T(kc)` |                                       |Left Control and Shift when held, `kc` when tapped     |
+|`MEH_T(kc)` |                                       |Left Control, Shift and Alt when held, `kc` when tapped|
+|`LCAG_T(kc)`|                                       |Left Control, Alt and GUI when held, `kc` when tapped  |
+|`RCAG_T(kc)`|                                       |Right Control, Alt and GUI when held, `kc` when tapped |
+|`ALL_T(kc)` |                                       |Left Control, Shift, Alt and GUI when held, `kc` when tapped - more info [here](http://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/)|
+|`SGUI_T(kc)`|`SCMD_T(kc)`, `SWIN_T(kc)`             |Left Shift and GUI when held, `kc` when tapped         |
+|`LCA_T(kc)` |                                       |Left Control and Alt when held, `kc` when tapped       |
 
 # One Shot Keys
 
@@ -176,3 +165,37 @@ Example: (Tapping Term = 200ms)
 - SHFT_T(KC_A) Up
 
 With defaults, if above is typed within tapping term, this will emit `ax`. With permissive hold, if above is typed within tapping term, this will emit `X` (so, Shift+X).
+
+# Mod tap interrupt
+
+When a dual role key used for a modifier is quickly followed by another keys, it is interpreted as held even before the tapping term elapsed.  This is a problem if a key is used for example inside a rolling combo because the second key will be pressed before the first key is released.
+
+For example, when trying to type the rolling combo "zx" and z being configured to send Ctrl when hold, z rapidly followed by x actually sends Ctrl-x. That's bad.
+
+You can disable this behavior by defining `IGNORE_MOD_TAP_INTERRUPT` in `config.h`.
+
+Note that this only concerns modifiers and not layer switching keys.
+
+# Hold after tap
+
+When the user holds a key after tap, this repeats the tapped key rather to hold a modifier key.  This allows to use auto repeat for the tapped key.  If you prefer to hold a modifier instead, define `TAPPING_FORCE_HOLD` in `config.h`.
+
+Example:
+
+- SHFT_T(KC_A) Down
+- SHFT_T(KC_A) Up
+- SHFT_T(KC_A) Down
+- wait more than tapping term...
+- SHFT_T(KC_A) Up
+
+With default settings, `a` will be sent on the first release, then `a` will be sent on the second press allowing the computer to trigger its auto repeat function.
+
+With `TAPPING_FORCE_HOLD`, the second press will be interpreted as a Shift, allowing to use it as a modifier shortly after having used it as a tap.
+
+!> `TAPPING_FORCE_HOLD` will break anything that uses tapping toggles (Such as the `TT` layer keycode, and the One Shot Tapping Toggle).
+
+# Retro Tapping
+
+When you hold a dual function key, and haven't pressed anything when you release the key, normally nothing happens.  However, if you enable this, if you release the key without pressing another key, it will send the original key, even if it is outside of the tapping term. 
+
+For instance, if you're using `LT(2, KC_SPACE)`, if you hold the key, don't hit anything else and then release it, normally, nothing happens. But with `RETRO_TAPPING` defined in your `config.h`, it will send `KC_SPACE`. 

docs/feature_audio.md

@@ -1,6 +1,18 @@
 # Audio
 
-Your keyboard can make sounds! If you've got a Planck, Preonic, or basically any AVR keyboard that allows access to the C6 or B5 port (`#define C6_AUDIO` and/or `#define B5_AUDIO`), you can hook up a simple speaker and make it beep. You can use those beeps to indicate layer transitions, modifiers, special keys, or just to play some funky 8bit tunes.
+Your keyboard can make sounds! If you've got a Planck, Preonic, or basically any AVR keyboard that allows access to certain PWM-capable pins, you can hook up a simple speaker and make it beep. You can use those beeps to indicate layer transitions, modifiers, special keys, or just to play some funky 8bit tunes.
+
+Up to two simultaneous audio voices are supported, one driven by timer 1 and another driven by timer 3.  The following pins can be defined as audio outputs in config.h:
+
+Timer 1:
+`#define B5_AUDIO`
+`#define B6_AUDIO`
+`#define B7_AUDIO`
+
+Timer 3:
+`#define C4_AUDIO`
+`#define C5_AUDIO`
+`#define C6_AUDIO`
 
 If you add `AUDIO_ENABLE = yes` to your `rules.mk`, there's a couple different sounds that will automatically be enabled without any other configuration:
 
@@ -47,6 +59,13 @@ PLAY_LOOP(my_song);
 
 It's advised that you wrap all audio features in `#ifdef AUDIO_ENABLE` / `#endif` to avoid causing problems when audio isn't built into the keyboard.
 
+The available keycodes for audio are: 
+
+* `AU_ON` - Turn audio mode on
+* `AU_OFF` - Turn audio mode off
+* `AU_TOG` - Toggle audio mode
+
+
 ## Music Mode
 
 The music mode maps your columns to a chromatic scale, and your rows to octaves. This works best with ortholinear keyboards, but can be made to work with others. All keycodes less than `0xFF` get blocked, so you won't type while playing notes - if you have special keys/mods, those will still work. A work-around for this is to jump to a different layer with KC_NOs before (or after) enabling music mode.
@@ -78,6 +97,20 @@ By default, `MUSIC_MASK` is set to `keycode < 0xFF` which means keycodes less th
 
 Which will capture all keycodes - be careful, this will get you stuck in music mode until you restart your keyboard!
 
+For a more advanced way to control which keycodes should still be processed, you can use `music_mask_kb(keycode)` in `<keyboard>.c` and `music_mask_user(keycode)` in your `keymap.c`:
+
+    bool music_mask_user(uint16_t keycode) {
+      switch (keycode) {
+        case RAISE:
+        case LOWER:
+          return false;
+        default:
+          return true;
+      }
+    }
+
+Things that return false are not part of the mask, and are always processed.
+
 The pitch standard (`PITCH_STANDARD_A`) is 440.0f by default - to change this, add something like this to your `config.h`:
 
     #define PITCH_STANDARD_A 432.0f
@@ -86,10 +119,57 @@ You can completely disable Music Mode as well. This is useful, if you're pressed
 
     #define NO_MUSIC_MODE
 
+## Audio Click
+
+This adds a click sound each time you hit a button, to simulate click sounds from the keyboard. And the sounds are slightly different for each keypress, so it doesn't sound like a single long note, if you type rapidly. 
+
+* `CK_TOGG` - Toggles the status (will play sound if enabled)
+* `CK_ON` - Turns on Audio Click (plays sound)
+* `CK_OFF` - Turns off Audio Click (doesn't play sound)
+* `CK_RST` - Resets the frequency to the default state (plays sound at default frequency)
+* `CK_UP` - Increases the frequency of the clicks (plays sound at new frequency)
+* `CK_DOWN` - Decreases the frequency of the clicks (plays sound at new frequency)
+
+
+The feature is disabled by default, to save space.  To enable it, add this to your `config.h`:
+
+    #define AUDIO_CLICKY
+
+
+You can configure the default, min and max frequencies, the stepping and built in randomness by defining these values: 
+
+| Option | Default Value | Description |
+|--------|---------------|-------------|
+| `AUDIO_CLICKY_FREQ_DEFAULT` | 440.0f | Sets the default/starting audio frequency for the clicky sounds. |
+| `AUDIO_CLICKY_FREQ_MIN` | 65.0f | Sets the lowest frequency (under 60f are a bit buggy). |
+| `AUDIO_CLICKY_FREQ_MAX` | 1500.0f | Sets the the highest frequency. Too high may result in coworkers attacking you. |
+| `AUDIO_CLICKY_FREQ_FACTOR` | 1.18921f| Sets the stepping of UP/DOWN key codes. |
+| `AUDIO_CLICKY_FREQ_RANDOMNESS`     |  0.05f |  Sets a factor of randomness for the clicks, Setting this to `0f` will make each click identical, and `1.0f` will make this sound much like the 90's computer screen scrolling/typing effect. | 
+
+
+
+
 ## MIDI Functionality
 
 This is still a WIP, but check out `quantum/keymap_midi.c` to see what's happening. Enable from the Makefile.
 
+
+## Audio Keycodes
+
+|Key             |Aliases  |Description                       |
+|----------------|---------|----------------------------------|
+|`AU_ON`         |         |Audio mode on                     |
+|`AU_OFF`        |         |Audio mode off                    |
+|`AU_TOG`        |         |Toggles Audio mode                |
+|`CLICKY_TOGGLE` |`CK_TOGG`|Toggles Audio clicky mode         |
+|`CLICKY_UP`     |`CK_UP`  |Increases frequency of the clicks |
+|`CLICKY_DOWN`   |`CK_DOWN`|Decreases frequency of the clicks |
+|`CLICKY_RESET`  |`CK_RST` |Resets frequency to default       |
+|`MU_ON`         |         |Turns on Music Mode               |
+|`MU_OFF`        |         |Turns off Music Mode              |
+|`MU_TOG`        |         |Toggles Music Mode                |
+|`MU_MOD`        |         |Cycles through the music modes    |
+
 <!-- FIXME: this formatting needs work
 
 ## Audio

docs/feature_auto_shift.md

@@ -88,10 +88,7 @@ occasion. This is simply due to habit and holding some keys a little longer
 than others. Once you find this value, work on tapping your problem keys a little
 quicker than normal and you will be set.
 
-{% hint style='info' %}
-Auto Shift has three special keys that can help you get this value right very
-quick. See "Auto Shift Setup" for more details!
-{% endhint %}
+?> Auto Shift has three special keys that can help you get this value right very quick. See "Auto Shift Setup" for more details!
 
 ### NO_AUTO_SHIFT_SPECIAL (simple define)
 

docs/feature_backlight.md

@@ -1,10 +1,20 @@
 # Backlighting
 
-<!-- FIXME: Describe how backlighting works in QMK -->
+Many keyboards support backlit keys by way of individual LEDs placed through or underneath the keyswitches. QMK is able to control the brightness of these LEDs by switching them on and off rapidly in a certain ratio, a technique known as *Pulse Width Modulation*, or PWM. By altering the duty cycle of the PWM signal, it creates the illusion of dimming.
 
-## Backlight Keycodes
+The MCU can only supply so much current to its GPIO pins. Instead of powering the backlight directly from the MCU, the backlight pin is connected to a transistor or MOSFET that switches the power to the LEDs.
 
-These keycodes control the backlight. Most keyboards use this for single color in-switch lighting.
+## Usage
+
+Most keyboards have backlighting enabled by default if they support it, but if it is not working for you, check that your `rules.mk` includes the following:
+
+```make
+BACKLIGHT_ENABLE = yes
+```
+
+You should then be able to use the keycodes below to change the backlight level.
+
+## Keycodes
 
 |Key      |Description                               |
 |---------|------------------------------------------|
@@ -16,24 +26,47 @@ These keycodes control the backlight. Most keyboards use this for single color i
 |`BL_DEC` |Decrease the backlight level              |
 |`BL_BRTG`|Toggle backlight breathing                |
 
-Note that for backlight breathing, you need to have `#define BACKLIGHT_BREATHING` in your config.h.
+## Caveats
 
-## Configuration Options in `config.h`
+This feature is distinct from both the [RGB underglow](feature_rgblight.md) and [RGB matrix](feature_rgb_matrix.md) features as it usually allows for only a single colour per switch, though you can obviously use multiple different coloured LEDs on a keyboard.
 
-* `BACKLIGHT_PIN B7` defines the pin that controlls the LEDs. Unless you design your own keyboard, you don't need to set this.
-* `BACKLIGHT_LEVELS 3` defines the number of brightness levels (maximum 15 excluding off).
-* `BACKLIGHT_BREATHING` if defined, enables backlight breathing. Note that this is only available if `BACKLIGHT_PIN` is B5, B6 or B7.
-* `BREATHING_PERIOD 6` defines the length of one backlight "breath" in seconds.
+Hardware PWM is only supported on certain pins of the MCU, so if the backlighting is not connected to one of them, a software implementation will be used, and backlight breathing will not be available. Currently the supported pins are `B5`, `B6`, `B7`, and `C6`.
 
-## Notes on Implementation
+## Configuration
 
-To change the brightness when using pins B5, B6 or B7, the PWM (Pulse Width Modulation) functionality of the on-chip timer is used.
-The timer is a counter that counts up to a certain TOP value (`0xFFFF` set in ICR1) before resetting to 0.
-We also set an OCR1x register.
-When the counter reaches the value stored in that register, the PWM pin drops to low.
-The PWM pin is pulled high again when the counter resets to 0.
-Therefore, OCR1x basically sets the duty cycle of the LEDs and as such the brightness where `0` is the darkest and `0xFFFF` the brightest setting.
+To change the behaviour of the backlighting, `#define` these in your `config.h`:
 
-To enable the breathing effect, we register an interrupt handler to be called whenever the counter resets (with `ISR(TIMER1_OVF_vect)`).
-In this handler, which gets called roughly 244 times per second, we compute the desired brightness using a precomputed brightness curve.
-To disable breathing, we can just disable the respective interrupt vector and reset the brightness to the desired level.
+|Define               |Default      |Description                                                                                                  |
+|---------------------|-------------|-------------------------------------------------------------------------------------------------------------|
+|`BACKLIGHT_PIN`      |`B7`         |The pin that controls the LEDs. Unless you are designing your own keyboard, you shouldn't need to change this|
+|`BACKLIGHT_LEVELS`   |`3`          |The number of brightness levels (maximum 15 excluding off)                                                   |
+|`BACKLIGHT_BREATHING`|*Not defined*|Enable backlight breathing, if hardware PWM is used                                                          |
+|`BREATHING_PERIOD`   |`6`          |The length of one backlight "breath" in seconds                                                              |
+
+## Hardware PWM Implementation
+
+When using the supported pins for backlighting, QMK will use a hardware timer configured to output a PWM signal. This timer will count up to `ICRx` (by default `0xFFFF`) before resetting to 0.
+The desired brightness is calculated and stored in the `OCRxx` register. When the counter reaches this value, the backlight pin will go low, and is pulled high again when the counter resets.
+In this way `OCRxx` essentially controls the duty cycle of the LEDs, and thus the brightness, where `0x0000` is completely off and `0xFFFF` is completely on.
+
+The breathing effect is achieved by registering an interrupt handler for `TIMER1_OVF_vect` that is called whenever the counter resets, roughly 244 times per second.
+In this handler, the value of an incrementing counter is mapped onto a precomputed brightness curve. To turn off breathing, the interrupt handler is simply disabled, and the brightness reset to the level stored in EEPROM.
+
+## Backlight Functions
+
+|Function  |Description                                               |
+|----------|----------------------------------------------------------|
+|`backlight_toggle()`   |Turn the backlight on or off                 |
+|`backlight_step()`     |Cycle through backlight levels               |
+|`backlight_increase()` |Increase the backlight level                 |
+|`backlight_decrease()` |Decrease the backlight level                 |
+|`backlight_level(x)`   |Sets the backlight level to specified level  |
+|`get_backlight_level()`|Toggle backlight breathing                   |
+
+### Backlight Breathing Functions
+
+|Function  |Description                                               |
+|----------|----------------------------------------------------------|
+|`breathing_toggle()`  |Turn the backlight breathing on or off        |
+|`breathing_enable()`  |Turns on backlight breathing                  |
+|`breathing_disable()` |Turns off backlight breathing                 |

docs/feature_bootmagic.md

@@ -1,89 +1,101 @@
-# Bootmagic and Magic Keycodes
+# Bootmagic
 
-There are 3 separate but related features that allow you to change the behavior of your keyboard without reflashing. While each of them have similar functionality you access that functionality in different ways depending on how your keyboard is configured.
+There are three separate but related features that allow you to change the behavior of your keyboard without reflashing. While each of them have similar functionality, it is accessed in different ways depending on how your keyboard is configured.
 
-Bootmagic is a system for configuring your keyboard while it initializes. To trigger a Bootmagic command you hold down the bootmagic key (`KC_SPACE` on most keyboards) and one or more command keys.
+**Bootmagic** is a system for configuring your keyboard while it initializes. To trigger a Bootmagic command, hold down the Bootmagic key and one or more command keys.
 
-Bootmagic Keycodes allow you to access the Bootmagic functionality after your keyboard has initialized. To use Bootmagic Keycodes you assign keycodes starting with `MAGIC_`, much in the same way you define any other key.
+**Bootmagic Keycodes** are prefixed with `MAGIC_`, and allow you to access the Bootmagic functionality *after* your keyboard has initialized. To use the keycodes, assign them to your keymap as you would any other keycode.
 
-Command is a feature that allows you to control different aspects of your keyboard. Command used to be called Magic. Command is typically accessed by holding Left and Right Shift at the same time, although that can be customized. While it shares some functionality with Bootmagic it also allows you to access functionality that Bootmagic does not. For more information see the (Command)[feature_command.md) documentation page.
+**Command**, formerly known as **Magic**, is another feature that allows you to control different aspects of your keyboard. While it shares some functionality with Bootmagic, it also allows you to do things that Bootmagic does not, such as printing version information to the console. For more information, see [Command](feature_command.md).
 
-## Enabling Bootmagic
+On some keyboards Bootmagic is disabled by default. If this is the case, it must be explicitly enabled in your `rules.mk` with:
 
-Bootmagic is disabled by default. To use Bootmagic you need to enable it in your `rules.mk` file:
+```make
+BOOTMAGIC_ENABLE = yes
+```
 
-    BOOTMAGIC_ENABLE = yes
+## Hotkeys
 
-## Bootmagic Hotkeys and Keycodes
+Hold down the Bootmagic key (Space by default) and the desired hotkey while plugging in your keyboard. For example, holding Space+`B` should cause it to enter the bootloader.
 
-This table describes the default Hotkeys for Bootmagic and the Keycodes for Magic. These may be overriden at the Keyboard or Keymap level. Some functionality is not available in both methods.
+|Hotkey            |Description                                  |
+|------------------|---------------------------------------------|
+|Escape            |Ignore Bootmagic configuration in EEPROM     |
+|`B`               |Enter the bootloader                         |
+|`D`               |Toggle debugging over serial                 |
+|`X`               |Toggle key matrix debugging                  |
+|`K`               |Toggle keyboard debugging                    |
+|`M`               |Toggle mouse debugging                       |
+|Backspace         |Clear the EEPROM                             |
+|Caps Lock         |Toggle treating Caps Lock as Left Control    |
+|Left Control      |Toggle swapping Caps Lock and Left Control   |
+|Left Alt          |Toggle swapping Left Alt and Left GUI        |
+|Right Alt         |Toggle swapping Right Alt and Right GUI      |
+|Left GUI          |Toggle the GUI keys (useful when gaming)     |
+|<code>&#96;</code>|Toggle swapping <code>&#96;</code> and Escape|
+|`\`               |Toggle swapping `\` and Backspace            |
+|`N`               |Toggle N-Key Rollover (NKRO)                 |
+|`0`               |Make layer 0 the default layer               |
+|`1`               |Make layer 1 the default layer               |
+|`2`               |Make layer 2 the default layer               |
+|`3`               |Make layer 3 the default layer               |
+|`4`               |Make layer 4 the default layer               |
+|`5`               |Make layer 5 the default layer               |
+|`6`               |Make layer 6 the default layer               |
+|`7`               |Make layer 7 the default layer               |
 
-To use the Hotkey hold down `BOOTMAGIC_KEY_SALT` (`KC_SPACE` by default) and the Hotkey while plugging in your keyboard. To use the Keycode assign that keycode to a layer. For example, if you hold down Space+B while plugging in most keyboards, you will enter bootloader mode.
+## Keycodes
 
-|Hotkey     |Keycode                           |Description                                             |
-|-----------|----------------------------------|--------------------------------------------------------|
-|`ESC`      |                                  |Skip bootmagic and saved eeprom configuration           |
-|`B`        |`RESET`                           |Enter bootloader instead of firmware                    |
-|`D`        |`DEBUG`                           |Enable debugging (writes messages to serial)            |
-|`X`        |                                  |Enable matrix debugging                                 |
-|`K`        |                                  |Enable keyboard debugging                               |
-|`M`        |                                  |Enable mouse debugging                                  |
-|`BACKSPACE`|                                  |Clear the saved settings from flash                     |
-|`CAPSLOCK` |`MAGIC_CAPSLOCK_TO_CONTROL`       |Treat `Capslock` as `Control`                           |
-|           |`MAGIC_UNCAPSLOCK_TO_CONTROL`     |Stop treating CapsLock as Control                       |
-|`LCTRL`    |`MAGIC_SWAP_CONTROL_CAPSLOCK`     |Swap `Control` and `Capslock`                           |
-|           |`MAGIC_UNSWAP_CONTROL_CAPSLOCK`   |Unswap Left Control and Caps Lock                       |
-|           |`MAGIC_SWAP_ALT_GUI`              |Swap Alt and GUI on both sides                          |
-|           |`MAGIC_UNSWAP_ALT_GUI`            |Unswap Left Alt and GUI                                 |
-|`LALT`     |`MAGIC_SWAP_LALT_LGUI`            |Swap Left `Alt` and `GUI`, e.g. for OSX Opt and Cmd     |
-|           |`MAGIC_UNSWAP_LALT_LGUI`          |Unswap Left Alt and GUI                                 |
-|`RALT`     |`MAGIC_SWAP_RALT_RGUI`            |Swap Right `Alt` and `GUI`                              |
-|           |`MAGIC_UNSWAP_RALT_RGUI`          |Unswap Right Alt and GUI                                |
-|`LGUI`     |`MAGIC_NO_GUI`                    |Disable GUI key - e.g. disable Windows key during gaming|
-|           |`MAGIC_UNNO_GUI`                  |Enable the GUI key                                      |
-|`GRAVE`    |`MAGIC_SWAP_GRAVE_ESC`            |Swap `\`~` and `ESC`                                    |
-|           |`MAGIC_UNSWAP_GRAVE_ESC`          |Unswap `\`~` and Escape                                 |
-|`BACKSLASH`|`MAGIC_SWAP_BACKSLASH_BACKSPACE`  |Swap Blackslash and Backspace                           |
-|           |`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`|Unswap Backslash and Backspace                          |
-|`N`        |`MAGIC_HOST_NKRO`                 |Force N-Key Rollover (NKRO) on                          |
-|           |`MAGIC_UNHOST_NKRO`               |Force NKRO off                                          |
-|           |`MAGIC_TOGGLE_NKRO`               |Toggle NKRO on or off                                   |
-|`0`        |`DF(0)`                           |Make Layer 0 the default layer at bootup                |
-|`1`        |`DF(1)`                           |Make Layer 1 the default layer at bootup                |
-|`2`        |`DF(2)`                           |Make Layer 2 the default layer at bootup                |
-|`3`        |`DF(3)`                           |Make Layer 3 the default layer at bootup                |
-|`4`        |`DF(4)`                           |Make Layer 4 the default layer at bootup                |
-|`5`        |`DF(5)`                           |Make Layer 5 the default layer at bootup                |
-|`6`        |`DF(6)`                           |Make Layer 6 the default layer at bootup                |
-|`7`        |`DF(7)`                           |Make Layer 7 the default layer at bootup                |
+|Keycode                           |Aliases  |Description                               |
+|----------------------------------|---------|------------------------------------------|
+|`MAGIC_CAPSLOCK_TO_CONTROL`       |         |Treat Caps Lock as Left Control           |
+|`MAGIC_UNCAPSLOCK_TO_CONTROL`     |         |Stop treating Caps Lock as Left Control   |
+|`MAGIC_HOST_NKRO`                 |         |Force N-Key Rollover (NKRO) on            |
+|`MAGIC_UNHOST_NKRO`               |         |Force NKRO off                            |
+|`MAGIC_TOGGLE_NKRO`               |         |Turn NKRO on or off                       |
+|`MAGIC_NO_GUI`                    |         |Disable the GUI keys (useful when gaming) |
+|`MAGIC_UNNO_GUI`                  |         |Enable the GUI keys                       |
+|`MAGIC_SWAP_ALT_GUI`              |`AG_SWAP`|Swap Alt and GUI on both sides (for macOS)|
+|`MAGIC_UNSWAP_ALT_GUI`            |`AG_NORM`|Unswap Left Alt and Left GUI              |
+|`MAGIC_TOGGLE_ALT_GUI`            |`AG_TOGG`|Toggle Left Alt and GUI swap              |
+|`MAGIC_SWAP_BACKSLASH_BACKSPACE`  |         |Swap `\` and Backspace                    |
+|`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`|         |Unswap `\` and Backspace                  |
+|`MAGIC_SWAP_CONTROL_CAPSLOCK`     |         |Swap Left Control and Caps Lock           |
+|`MAGIC_UNSWAP_CONTROL_CAPSLOCK`   |         |Unswap Left Control and Caps Lock         |
+|`MAGIC_SWAP_GRAVE_ESC`            |         |Swap <code>&#96;</code> and Escape        |
+|`MAGIC_UNSWAP_GRAVE_ESC`          |         |Unswap <code>&#96;</code> and Escape      |
+|`MAGIC_SWAP_LALT_LGUI`            |         |Swap Left Alt and Left GUI                |
+|`MAGIC_UNSWAP_LALT_LGUI`          |         |Unswap Left Alt and Left GUI              |
+|`MAGIC_SWAP_RALT_RGUI`            |         |Swap Right Alt and Right GUI              |
+|`MAGIC_UNSWAP_RALT_RGUI`          |         |Unswap Right Alt and Right GUI            |
 
-## Bootmagic Configuration
+## Configuration
 
-When setting up your keyboard and/or keymap there are a number of `#define`s that control the behavior of Bootmagic. To use these put them in your `config.h`, either at the keyboard or keymap level.
+If you would like to change the hotkey assignments for Bootmagic, `#define` these in your `config.h` at either the keyboard or keymap level.
 
-|Define |Default|Description |
-|-------|-------|------------|
-|`BOOTMAGIC_KEY_SALT`|`KC_SPACE`|The key to hold down to trigger Bootmagic during initialization.|
-|`BOOTMAGIC_KEY_SKIP`|`KC_ESC`|The Hotkey to ignore saved eeprom configuration.|
-|`BOOTMAGIC_KEY_EEPROM_CLEAR`|`KC_BSPACE`|The hotkey to clear the saved eeprom configuration.|
-|`BOOTMAGIC_KEY_BOOTLOADER`|`KC_B`|The hotkey to enter the bootloader.|
-|`BOOTMAGIC_KEY_DEBUG_ENABLE`|`KC_D`|The hotkey to enable debug mode.|
-|`BOOTMAGIC_KEY_DEBUG_MATRIX`|`KC_X`|The hotkey to enable matrix debugging mode.|
-|`BOOTMAGIC_KEY_DEBUG_KEYBOARD`|`KC_K`|The hotkey to enable keyboard debugging mode.|
-|`BOOTMAGIC_KEY_DEBUG_MOUSE`|`KC_M`|The hotkey to enable mouse debugging mode.|
-|`BOOTMAGIC_KEY_SWAP_CONTROL_CAPSLOCK`|`KC_LCTRL`||
-|`BOOTMAGIC_KEY_CAPSLOCK_TO_CONTROL`|`KC_CAPSLOCK`||
-|`BOOTMAGIC_KEY_SWAP_LALT_LGUI`|`KC_LALT`||
-|`BOOTMAGIC_KEY_SWAP_RALT_RGUI`|`KC_RALT`||
-|`BOOTMAGIC_KEY_NO_GUI`|`KC_LGUI`||
-|`BOOTMAGIC_KEY_SWAP_GRAVE_ESC`|`KC_GRAVE`||
-|`BOOTMAGIC_KEY_SWAP_BACKSLASH_BACKSPACE`|`KC_BSLASH`||
-|`BOOTMAGIC_HOST_NKRO`|`KC_N`||
-|`BOOTMAGIC_KEY_DEFAULT_LAYER_0`|`KC_0`|Hotkey to set Layer 0 as the default layer|
-|`BOOTMAGIC_KEY_DEFAULT_LAYER_1`|`KC_1`|Hotkey to set Layer 1 as the default layer|
-|`BOOTMAGIC_KEY_DEFAULT_LAYER_2`|`KC_2`|Hotkey to set Layer 2 as the default layer|
-|`BOOTMAGIC_KEY_DEFAULT_LAYER_3`|`KC_3`|Hotkey to set Layer 3 as the default layer|
-|`BOOTMAGIC_KEY_DEFAULT_LAYER_4`|`KC_4`|Hotkey to set Layer 4 as the default layer|
-|`BOOTMAGIC_KEY_DEFAULT_LAYER_5`|`KC_5`|Hotkey to set Layer 5 as the default layer|
-|`BOOTMAGIC_KEY_DEFAULT_LAYER_6`|`KC_6`|Hotkey to set Layer 6 as the default layer|
-|`BOOTMAGIC_KEY_DEFAULT_LAYER_7`|`KC_7`|Hotkey to set Layer 7 as the default layer|
+|Define                                  |Default      |Description                                        |
+|----------------------------------------|-------------|---------------------------------------------------|
+|`BOOTMAGIC_KEY_SALT`                    |`KC_SPACE`   |The Bootmagic key                                  |
+|`BOOTMAGIC_KEY_SKIP`                    |`KC_ESC`     |Ignore Bootmagic configuration in EEPROM           |
+|`BOOTMAGIC_KEY_EEPROM_CLEAR`            |`KC_BSPACE`  |Clear the EEPROM configuration                     |
+|`BOOTMAGIC_KEY_BOOTLOADER`              |`KC_B`       |Enter the bootloader                               |
+|`BOOTMAGIC_KEY_DEBUG_ENABLE`            |`KC_D`       |Toggle debugging over serial                       |
+|`BOOTMAGIC_KEY_DEBUG_MATRIX`            |`KC_X`       |Toggle matrix debugging                            |
+|`BOOTMAGIC_KEY_DEBUG_KEYBOARD`          |`KC_K`       |Toggle keyboard debugging                          |
+|`BOOTMAGIC_KEY_DEBUG_MOUSE`             |`KC_M`       |Toggle mouse debugging                             |
+|`BOOTMAGIC_KEY_SWAP_CONTROL_CAPSLOCK`   |`KC_LCTRL`   |Swap Left Control and Caps Lock                    |
+|`BOOTMAGIC_KEY_CAPSLOCK_TO_CONTROL`     |`KC_CAPSLOCK`|Toggle treating Caps Lock as Left Control          |
+|`BOOTMAGIC_KEY_SWAP_LALT_LGUI`          |`KC_LALT`    |Toggle swapping Left Alt and Left GUI (for macOS)  |
+|`BOOTMAGIC_KEY_SWAP_RALT_RGUI`          |`KC_RALT`    |Toggle swapping Right Alt and Right GUI (for macOS)|
+|`BOOTMAGIC_KEY_NO_GUI`                  |`KC_LGUI`    |Toggle the GUI keys (useful when gaming)           |
+|`BOOTMAGIC_KEY_SWAP_GRAVE_ESC`          |`KC_GRAVE`   |Toggle swapping <code>&#96;</code> and Escape      |
+|`BOOTMAGIC_KEY_SWAP_BACKSLASH_BACKSPACE`|`KC_BSLASH`  |Toggle swapping `\` and Backspace                  |
+|`BOOTMAGIC_HOST_NKRO`                   |`KC_N`       |Toggle N-Key Rollover (NKRO)                       |
+|`BOOTMAGIC_KEY_DEFAULT_LAYER_0`         |`KC_0`       |Make layer 0 the default layer                     |
+|`BOOTMAGIC_KEY_DEFAULT_LAYER_1`         |`KC_1`       |Make layer 1 the default layer                     |
+|`BOOTMAGIC_KEY_DEFAULT_LAYER_2`         |`KC_2`       |Make layer 2 the default layer                     |
+|`BOOTMAGIC_KEY_DEFAULT_LAYER_3`         |`KC_3`       |Make layer 3 the default layer                     |
+|`BOOTMAGIC_KEY_DEFAULT_LAYER_4`         |`KC_4`       |Make layer 4 the default layer                     |
+|`BOOTMAGIC_KEY_DEFAULT_LAYER_5`         |`KC_5`       |Make layer 5 the default layer                     |
+|`BOOTMAGIC_KEY_DEFAULT_LAYER_6`         |`KC_6`       |Make layer 6 the default layer                     |
+|`BOOTMAGIC_KEY_DEFAULT_LAYER_7`         |`KC_7`       |Make layer 7 the default layer                     |

docs/feature_command.md

@@ -1,52 +1,50 @@
-# Command (Formerly known as Magic)
+# Command
 
-Command is a way to change your keyboard's behavior without having to flash or unplug it to use [Bootmagic](feature_bootmagic.md). There is a lot of overlap between this functionality and the [Bootmagic Keycodes](feature_bootmagic.md). Whenever possible we encourage you to use that functionality instead of Command.
+Command, formerly known as Magic, is a way to change your keyboard's behavior without having to flash or unplug it to use [Bootmagic](feature_bootmagic.md). There is a lot of overlap between this functionality and the [Bootmagic Keycodes](feature_bootmagic.md#keycodes). Wherever possible we encourage you to use that feature instead of Command.
 
-## Enabling Command
+On some keyboards Command is disabled by default. If this is the case, it must be explicitly enabled in your `rules.mk`:
 
-By default Command is disabled. You can enable it in your `rules.mk` file:
-
-    COMMAND_ENABLE = yes
+```make
+COMMAND_ENABLE = yes
+```
 
 ## Usage
 
-To use Command you hold down the key combination defined by `IS_COMMAND`. By default that combination is both shift keys. While holding the key combination press the key corresponding to the command you want.
-
-For example, to write the current QMK version to the QMK Toolbox console, you can press `Left Shift`+`Right Shift`+`V`.
+To use Command, hold down the key combination defined by the `IS_COMMAND()` macro. By default this is Left Shift+Right Shift. Then, press the key corresponding to the command you want. For example, to output the current QMK version to the QMK Toolbox console, press Left Shift+Right Shift+`V`.
 
 ## Configuration
 
-The following values can be defined in `config.h` to control the behavior of Command.
+If you would like to change the key assignments for Command, `#define` these in your `config.h` at either the keyboard or keymap level. All keycode assignments here must omit the `KC_` prefix.
 
-|Define |Default | Description |
-|-------|--------|-------------|
-|`IS_COMMAND()`                      |`(keyboard_report->mods == (MOD_BIT(KC_LSHIFT) | MOD_BIT(KC_RSHIFT)))`|Key combination to activate Command|
-|`MAGIC_KEY_SWITCH_LAYER_WITH_FKEYS` |`true`                                                                |Do layer switching with Function row|
-|`MAGIC_KEY_SWITCH_LAYER_WITH_NKEYS` |`true`                                                                |Do layer switching with number keys.|
-|`MAGIC_KEY_SWITCH_LAYER_WITH_CUSTOM`|`false`                                                               |Do layer switching with custom keys (`MAGIC_KEY_LAYER0..9` below.)|
-|`MAGIC_KEY_HELP1`                   |`H`                                                                   |Show help.|
-|`MAGIC_KEY_HELP2`                   |`SLASH`                                                               |Show help.|
-|`MAGIC_KEY_DEBUG`                   |`D`                                                                   |Turn on debug mode.|
-|`MAGIC_KEY_DEBUG_MATRIX`            |`X`                                                                   |Turn on matrix debugging.|
-|`MAGIC_KEY_DEBUG_KBD`               |`K`                                                                   |Turn on keyboard debugging.|
-|`MAGIC_KEY_DEBUG_MOUSE`             |`M`                                                                   |Turn on mouse debugging.|
-|`MAGIC_KEY_VERSION`                 |`V`                                                                   |Write the QMK version to the console|
-|`MAGIC_KEY_STATUS`                  |`S`                                                                   |Show the current keyboard status|
-|`MAGIC_KEY_CONSOLE`                 |`C`                                                                   |Enable the Command Console|
-|`MAGIC_KEY_LAYER0_ALT1`             |`ESC`                                                                 |Alternate access to layer 0|
-|`MAGIC_KEY_LAYER0_ALT2`             |`GRAVE`                                                               |Alternate access to layer 0|
-|`MAGIC_KEY_LAYER0`                  |`0`                                                                   |Change default layer to 0|
-|`MAGIC_KEY_LAYER1`                  |`1`                                                                   |Change default layer to 1|
-|`MAGIC_KEY_LAYER2`                  |`2`                                                                   |Change default layer to 2|
-|`MAGIC_KEY_LAYER3`                  |`3`                                                                   |Change default layer to 3|
-|`MAGIC_KEY_LAYER4`                  |`4`                                                                   |Change default layer to 4|
-|`MAGIC_KEY_LAYER5`                  |`5`                                                                   |Change default layer to 5|
-|`MAGIC_KEY_LAYER6`                  |`6`                                                                   |Change default layer to 6|
-|`MAGIC_KEY_LAYER7`                  |`7`                                                                   |Change default layer to 7|
-|`MAGIC_KEY_LAYER8`                  |`8`                                                                   |Change default layer to 8|
-|`MAGIC_KEY_LAYER9`                  |`9`                                                                   |Change default layer to 9|
-|`MAGIC_KEY_BOOTLOADER`              |`PAUSE`                                                               |Exit keyboard and enter bootloader|
-|`MAGIC_KEY_LOCK`                    |`CAPS`                                                                |Lock the keyboard so nothing can be typed|
-|`MAGIC_KEY_EEPROM`                  |`E`                                                                   |Erase EEPROM settings|
-|`MAGIC_KEY_NKRO`                    |`N`                                                                   |Toggle NKRO on/off|
-|`MAGIC_KEY_SLEEP_LED`               |`Z`                                                                   |Toggle LED when computer is sleeping on/off|
+|Define                              |Default                                                                               |Description                                     |
+|------------------------------------|--------------------------------------------------------------------------------------|------------------------------------------------|
+|`IS_COMMAND()`                      |<code>(keyboard_report->mods == (MOD_BIT(KC_LSHIFT) &#124; MOD_BIT(KC_RSHIFT)))</code>|The key combination to activate Command         |
+|`MAGIC_KEY_SWITCH_LAYER_WITH_FKEYS` |`true`                                                                                |Set default layer with the Function row         |
+|`MAGIC_KEY_SWITCH_LAYER_WITH_NKEYS` |`true`                                                                                |Set default layer with the number keys          |
+|`MAGIC_KEY_SWITCH_LAYER_WITH_CUSTOM`|`false`                                                                               |Set default layer with `MAGIC_KEY_LAYER0..9`    |
+|`MAGIC_KEY_DEBUG`                   |`D`                                                                                   |Toggle debugging over serial                    |
+|`MAGIC_KEY_DEBUG_MATRIX`            |`X`                                                                                   |Toggle key matrix debugging                     |
+|`MAGIC_KEY_DEBUG_KBD`               |`K`                                                                                   |Toggle keyboard debugging                       |
+|`MAGIC_KEY_DEBUG_MOUSE`             |`M`                                                                                   |Toggle mouse debugging                          |
+|`MAGIC_KEY_CONSOLE`                 |`C`                                                                                   |Enable the Command console                      |
+|`MAGIC_KEY_VERSION`                 |`V`                                                                                   |Print the running QMK version to the console    |
+|`MAGIC_KEY_STATUS`                  |`S`                                                                                   |Print the current keyboard status to the console|
+|`MAGIC_KEY_HELP1`                   |`H`                                                                                   |Print Command help to the console               |
+|`MAGIC_KEY_HELP2`                   |`SLASH`                                                                               |Print Command help to the console (alternate)   |
+|`MAGIC_KEY_LAYER0`                  |`0`                                                                                   |Make layer 0 the default layer                  |
+|`MAGIC_KEY_LAYER1`                  |`1`                                                                                   |Make layer 1 the default layer                  |
+|`MAGIC_KEY_LAYER2`                  |`2`                                                                                   |Make layer 2 the default layer                  |
+|`MAGIC_KEY_LAYER3`                  |`3`                                                                                   |Make layer 3 the default layer                  |
+|`MAGIC_KEY_LAYER4`                  |`4`                                                                                   |Make layer 4 the default layer                  |
+|`MAGIC_KEY_LAYER5`                  |`5`                                                                                   |Make layer 5 the default layer                  |
+|`MAGIC_KEY_LAYER6`                  |`6`                                                                                   |Make layer 6 the default layer                  |
+|`MAGIC_KEY_LAYER7`                  |`7`                                                                                   |Make layer 7 the default layer                  |
+|`MAGIC_KEY_LAYER8`                  |`8`                                                                                   |Make layer 8 the default layer                  |
+|`MAGIC_KEY_LAYER9`                  |`9`                                                                                   |Make layer 9 the default layer                  |
+|`MAGIC_KEY_LAYER0_ALT1`             |`ESC`                                                                                 |Make layer 0 the default layer (alternate)      |
+|`MAGIC_KEY_LAYER0_ALT2`             |`GRAVE`                                                                               |Make layer 0 the default layer (alternate)      |
+|`MAGIC_KEY_BOOTLOADER`              |`PAUSE`                                                                               |Enter the bootloader                            |
+|`MAGIC_KEY_LOCK`                    |`CAPS`                                                                                |Lock the keyboard so nothing can be typed       |
+|`MAGIC_KEY_EEPROM`                  |`E`                                                                                   |Clear the EEPROM                                |
+|`MAGIC_KEY_NKRO`                    |`N`                                                                                   |Toggle N-Key Rollover (NKRO)                    |
+|`MAGIC_KEY_SLEEP_LED`               |`Z`                                                                                   |Toggle LED when computer is sleeping            |

docs/feature_dynamic_macros.md

@@ -4,10 +4,10 @@ QMK supports temporary macros created on the fly. We call these Dynamic Macros.
 
 You can store one or two macros and they may have a combined total of 128 keypresses. You can increase this size at the cost of RAM.
 
-To enable them, first add a new element to the `planck_keycodes` enum — `DYNAMIC_MACRO_RANGE`:
+To enable them, first add a new element to the end of your `keycodes` enum — `DYNAMIC_MACRO_RANGE`:
 
 ```c
-enum planck_keycodes {
+enum keycodes {
 	QWERTY = SAFE_RANGE,
 	COLEMAK,
 	DVORAK,
@@ -20,7 +20,7 @@ enum planck_keycodes {
 };
 ```
 
-It must be the last element because `dynamic_macros.h` will add some more keycodes after it.
+Your `keycodes` enum may have a slightly different name. You must add `DYNAMIC_MACRO_RANGE` as the last element because `dynamic_macros.h` will add some more keycodes after it.
 
 Below it, include the `dynamic_macro.h` header:
 

docs/feature_grave_esc.md

@@ -1,17 +1,24 @@
 # Grave Escape
 
-Grave Escape is a feature that allows you to share the grave key (<code>&#96;</code> and `~`) on the same key as Escape. When `KC_GESC` is used it will act as `KC_ESC`, unless Shift or GUI is pressed, in which case it will act as `KC_GRAVE`.
+If you're using a 60% keyboard, or any other layout with no F-row, you will have noticed that there is no dedicated Escape key. Grave Escape is a feature that allows you to share the grave key (<code>&#96;</code> and `~`) with Escape.
 
+## Usage
+
+Replace the `KC_GRAVE` key in your keymap (usually to the left of the `1` key) with `KC_GESC`. When pressed it will behave like `KC_ESC`, but with Shift or GUI held it will send `KC_GRAVE`.
+
+## Keycodes
 
 |Key      |Aliases    |Description                                                       |
 |---------|-----------|------------------------------------------------------------------|
 |`KC_GESC`|`GRAVE_ESC`|Escape when pressed, <code>&#96;</code> when Shift or GUI are held|
 
-There are several possible key combinations this will break, among them Ctrl+Shift+Esc on Windows and Cmd+Opt+Esc on macOS. You can use these options in your `config.h` to work around this:
+## Configuration
 
-| Option | Description |
-|--------|-------------|
-| `GRAVE_ESC_ALT_OVERRIDE` | Always send Escape if Alt is pressed. |
-| `GRAVE_ESC_CTRL_OVERRIDE` | Always send Escape if Ctrl is pressed. |
-| `GRAVE_ESC_GUI_OVERRIDE` | Always send Escape if GUI is pressed. |
-| `GRAVE_ESC_SHIFT_OVERRIDE` | Always send Escape if SHIFT is pressed. |
+There are several possible key combinations this will break, among them Control+Shift+Escape on Windows and Command+Option+Escape on macOS. To work around this, you can `#define` these options in your `config.h`:
+
+|Define                    |Description                              |
+|--------------------------|-----------------------------------------|
+|`GRAVE_ESC_ALT_OVERRIDE`  |Always send Escape if Alt is pressed     |
+|`GRAVE_ESC_CTRL_OVERRIDE` |Always send Escape if Control is pressed |
+|`GRAVE_ESC_GUI_OVERRIDE`  |Always send Escape if GUI is pressed     |
+|`GRAVE_ESC_SHIFT_OVERRIDE`|Always send Escape if Shift is pressed   |