Fix i2c EEPROM compile issue when Console is enabled (#9186)

* Fix i2c EEPROM compile issue when Console is enabled

* Only use if both console and debugging is enabled

.clang_complete

@@ -1,24 +0,0 @@
-
--I.
--I./drivers
--I./drivers/avr
--I./keyboards/ergodox_ez
--I./keyboards/ergodox_ez/keymaps/vim
--I./lib
--I./lib/lufa
--I./quantum
--I./quantum/api
--I./quantum/audio
--I./quantum/keymap_extras
--I./quantum/process_keycode
--I./quantum/serial_link
--I./quantum/template
--I./quantum/tools
--I./quantum/visualizer
--I./tmk_core
--I./tmk_core/common
--I./tmk_core/common/debug.h
--I./tmk_core/protocol
--I./tmk_core/protocol/lufa
--I./util
--DQMK_KEYBOARD=\"$(KEYBOARD)\" -DQMK_KEYMAP=\"$(KEYMAP)\"

.github/workflows/cli.yml

@@ -0,0 +1,28 @@
+name: CLI CI
+
+on:
+  push:
+    branches:
+    - master
+    - future
+  pull_request:
+    paths:
+    - 'lib/python/**'
+    - 'bin/qmk'
+    - 'requirements.txt'
+    - '.github/workflows/cli.yml'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    container: qmkfm/base_container
+
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        submodules: recursive
+    - name: Install dependencies
+      run: pip3 install -r requirements.txt
+    - name: Run tests
+      run: bin/qmk pytest

.gitignore

@@ -24,6 +24,7 @@ quantum/version.h
 .idea/
 CMakeLists.txt
 cmake-build-debug
+.clang_complete
 doxygen/
 .DS_Store
 /util/wsl_downloaded
@@ -47,7 +48,6 @@ doxygen/
 *.iml
 .browse.VC.db*
 *.stackdump
-util/Win_Check_Output.txt
 # Let these ones be user specific, since we have so many different configurations
 .vscode/c_cpp_properties.json
 .vscode/launch.json
@@ -63,9 +63,6 @@ util/Win_Check_Output.txt
 *.gif
 *.jpg
 
-# Do not ignore MiniDox left/right hand eeprom files
-!keyboards/minidox/*.eep
-
 # things travis sees
 secrets.tar
 id_rsa_*
@@ -73,3 +70,6 @@ id_rsa_*
 
 # python things
 __pycache__
+
+# prerequisites for updating ChibiOS
+/util/fmpp*

.gitmodules

@@ -1,13 +1,15 @@
 [submodule "lib/chibios"]
 	path = lib/chibios
 	url = https://github.com/qmk/ChibiOS
+	branch = master
 [submodule "lib/chibios-contrib"]
 	path = lib/chibios-contrib
 	url = https://github.com/qmk/ChibiOS-Contrib
-	branch = k-type-fix
+	branch = master
 [submodule "lib/ugfx"]
 	path = lib/ugfx
 	url = https://github.com/qmk/uGFX
+	branch = master
 [submodule "lib/googletest"]
 	path = lib/googletest
 	url = https://github.com/google/googletest

.vscode/settings.json

@@ -5,15 +5,21 @@
     // Configure glob patterns for excluding files and folders.
     "files.exclude": {
         "**/.build": true,
-        "**/*.hex": true
+        "**/*.hex": true,
+        "**/*.bin": true
     },
     "files.associations": {
-      "*.h": "c",
-      "*.c": "c",
-      "*.cpp": "cpp",
-      "*.hpp": "cpp",
-      "xstddef": "c",
-      "type_traits": "c",
-      "utility": "c"
+        "*.h": "c",
+        "*.c": "c",
+        "*.inc": "c",
+        "*.cpp": "cpp",
+        "*.hpp": "cpp",
+        "xstddef": "c",
+        "type_traits": "c",
+        "utility": "c"
+    },
+    "[markdown]": {
+        "editor.trimAutoWhitespace": false,
+        "files.trimTrailingWhitespace": false
     }
 }

Makefile

@@ -29,6 +29,9 @@ $(info QMK Firmware $(QMK_VERSION))
 endif
 endif
 
+# avoid 'Entering|Leaving directory' messages
+MAKEFLAGS += --no-print-directory
+
 ON_ERROR := error_occurred=1
 
 BREAK_ON_ERRORS = no
@@ -291,8 +294,8 @@ define PARSE_RULE
         $$(info |  QMK's make format recently changed to use folder locations and colons:)
         $$(info |     make project_folder:keymap[:target])
         $$(info |  Examples:)
-        $$(info |     make planck/rev4:default:dfu)
-        $$(info |     make planck:default)
+        $$(info |     make dz60:default)
+        $$(info |     make planck/rev6:default:flash)
         $$(info |)
     endif
 endef
@@ -623,13 +626,19 @@ endif
 # Generate the version.h file
 ifndef SKIP_GIT
     GIT_VERSION := $(shell git describe --abbrev=6 --dirty --always --tags 2>/dev/null || date +"%Y-%m-%d-%H:%M:%S")
+    CHIBIOS_VERSION := $(shell cd lib/chibios && git describe --abbrev=6 --dirty --always --tags 2>/dev/null || date +"%Y-%m-%d-%H:%M:%S")
+    CHIBIOS_CONTRIB_VERSION := $(shell cd lib/chibios-contrib && git describe --abbrev=6 --dirty --always --tags 2>/dev/null || date +"%Y-%m-%d-%H:%M:%S")
 else
     GIT_VERSION := NA
+    CHIBIOS_VERSION := NA
+    CHIBIOS_CONTRIB_VERSION := NA
 endif
 ifndef SKIP_VERSION
 BUILD_DATE := $(shell date +"%Y-%m-%d-%H:%M:%S")
 $(shell echo '#define QMK_VERSION "$(GIT_VERSION)"' > $(ROOT_DIR)/quantum/version.h)
 $(shell echo '#define QMK_BUILDDATE "$(BUILD_DATE)"' >> $(ROOT_DIR)/quantum/version.h)
+$(shell echo '#define CHIBIOS_VERSION "$(CHIBIOS_VERSION)"' >> $(ROOT_DIR)/quantum/version.h)
+$(shell echo '#define CHIBIOS_CONTRIB_VERSION "$(CHIBIOS_CONTRIB_VERSION)"' >> $(ROOT_DIR)/quantum/version.h)
 else
 BUILD_DATE := NA
 endif

Vagrantfile

@@ -89,7 +89,7 @@ Vagrant.configure(2) do |config|
 
   Examples:
      make planck/rev4:default:dfu
-     make planck:default
+     make planck/rev4:default
 
   EOT
 end

bin/qmk

@@ -2,52 +2,61 @@
 """CLI wrapper for running QMK commands.
 """
 import os
-import subprocess
 import sys
 from importlib.util import find_spec
-from time import strftime
+from pathlib import Path
 
 # Add the QMK python libs to our path
-script_dir = os.path.dirname(os.path.realpath(__file__))
-qmk_dir = os.path.abspath(os.path.join(script_dir, '..'))
-python_lib_dir = os.path.abspath(os.path.join(qmk_dir, 'lib', 'python'))
-sys.path.append(python_lib_dir)
+script_dir = Path(os.path.realpath(__file__)).parent
+qmk_dir = script_dir.parent
+python_lib_dir = Path(qmk_dir / 'lib' / 'python').resolve()
+sys.path.append(str(python_lib_dir))
 
-# Make sure our modules have been setup
-with open(os.path.join(qmk_dir, 'requirements.txt'), 'r') as fd:
-    for line in fd.readlines():
-        line = line.strip().replace('<', '=').replace('>', '=')
 
-        if line[0] == '#':
-            continue
+def _check_modules(requirements):
+    """ Check if the modules in the given requirements.txt are available.
+    """
+    with Path(qmk_dir / requirements).open() as fd:
+        for line in fd.readlines():
+            line = line.strip().replace('<', '=').replace('>', '=')
 
-        if '#' in line:
-            line = line.split('#')[0]
+            if len(line) == 0 or line[0] == '#' or line.startswith('-r'):
+                continue
 
-        module = line.split('=')[0] if '=' in line else line
+            if '#' in line:
+                line = line.split('#')[0]
+
+            module = dict()
+            module['name'] = module['import'] = line.split('=')[0] if '=' in line else line
 
-        if module in ['pep8-naming']:
             # Not every module is importable by its own name.
-            continue
+            if module['name'] == "pep8-naming":
+                module['import'] = "pep8ext_naming"
 
-        if not find_spec(module):
-            print('Could not find module %s!' % module)
-            print('Please run `pip3 install -r requirements.txt` to install the python dependencies.')
-            exit(255)
+            if not find_spec(module['import']):
+                print('Could not find module %s!' % module['name'])
+                print('Please run `python3 -m pip install -r %s` to install required python dependencies.' % (qmk_dir / requirements,))
+                if developer:
+                    print('You can also turn off developer mode: qmk config user.developer=None')
+                print()
+                exit(255)
 
-# Figure out our version
-# TODO(skullydazed/anyone): Find a method that doesn't involve git. This is slow in docker and on windows.
-command = ['git', 'describe', '--abbrev=6', '--dirty', '--always', '--tags']
-result = subprocess.run(command, universal_newlines=True, stdout=subprocess.PIPE, stderr=subprocess.STDOUT)
 
-if result.returncode == 0:
-    os.environ['QMK_VERSION'] = result.stdout.strip()
-else:
-    os.environ['QMK_VERSION'] = 'nogit-' + strftime('%Y-%m-%d-%H:%M:%S') + '-dirty'
+developer = False
+# Make sure our modules have been setup
+_check_modules('requirements.txt')
 
 # Setup the CLI
 import milc  # noqa
 
+# For developers additional modules are needed
+if milc.cli.config.user.developer:
+    # Do not run the check for 'config',
+    # so users can turn off developer mode
+    if len(sys.argv) == 1 or (len(sys.argv) > 1 and 'config' != sys.argv[1]):
+        developer = True
+        _check_modules('requirements-dev.txt')
+
 milc.EMOJI_LOGLEVELS['INFO'] = '{fg_blue}Ψ{style_reset_all}'
 
 

build_json.mk

@@ -21,6 +21,11 @@ else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_1)/keymap.json)","")
     KEYMAP_PATH := $(MAIN_KEYMAP_PATH_1)
 endif
 
+# Load the keymap-level rules.mk if exists
+ifneq ("$(wildcard $(KEYMAP_PATH))", "")
+    -include $(KEYMAP_PATH)/rules.mk
+endif
+
 # Generate the keymap.c
 $(KEYBOARD_OUTPUT)/src/keymap.c: $(KEYMAP_JSON)
-	bin/qmk json-keymap --quiet --output $(KEYMAP_C) $(KEYMAP_JSON)
+	bin/qmk json2c --quiet --output $(KEYMAP_C) $(KEYMAP_JSON)

build_keyboard.mk

@@ -231,44 +231,19 @@ endif
 # We can assume a ChibiOS target When MCU_FAMILY is defined since it's
 # not used for LUFA
 ifdef MCU_FAMILY
-    FIRMWARE_FORMAT?=bin
     PLATFORM=CHIBIOS
+    PLATFORM_KEY=chibios
+    FIRMWARE_FORMAT?=bin
 else ifdef ARM_ATSAM
     PLATFORM=ARM_ATSAM
+    PLATFORM_KEY=arm_atsam
     FIRMWARE_FORMAT=bin
 else
     PLATFORM=AVR
+    PLATFORM_KEY=avr
     FIRMWARE_FORMAT?=hex
 endif
 
-ifeq ($(PLATFORM),CHIBIOS)
-    include $(TMK_PATH)/chibios.mk
-    OPT_OS = chibios
-    ifneq ("$(wildcard $(KEYBOARD_PATH_5)/bootloader_defs.h)","")
-        OPT_DEFS += -include $(KEYBOARD_PATH_5)/bootloader_defs.h
-     else ifneq ("$(wildcard $(KEYBOARD_PATH_5)/boards/$(BOARD)/bootloader_defs.h)","")
-        OPT_DEFS += -include $(KEYBOARD_PATH_5)/boards/$(BOARD)/bootloader_defs.h
-    else ifneq ("$(wildcard $(KEYBOARD_PATH_4)/bootloader_defs.h)","")
-        OPT_DEFS += -include $(KEYBOARD_PATH_4)/bootloader_defs.h
-     else ifneq ("$(wildcard $(KEYBOARD_PATH_4)/boards/$(BOARD)/bootloader_defs.h)","")
-        OPT_DEFS += -include $(KEYBOARD_PATH_4)/boards/$(BOARD)/bootloader_defs.h
-    else ifneq ("$(wildcard $(KEYBOARD_PATH_3)/bootloader_defs.h)","")
-        OPT_DEFS += -include $(KEYBOARD_PATH_3)/bootloader_defs.h
-     else ifneq ("$(wildcard $(KEYBOARD_PATH_3)/boards/$(BOARD)/bootloader_defs.h)","")
-        OPT_DEFS += -include $(KEYBOARD_PATH_3)/boards/$(BOARD)/bootloader_defs.h
-    else ifneq ("$(wildcard $(KEYBOARD_PATH_2)/bootloader_defs.h)","")
-        OPT_DEFS += -include $(KEYBOARD_PATH_2)/bootloader_defs.h
-     else ifneq ("$(wildcard $(KEYBOARD_PATH_2)/boards/$(BOARD)/bootloader_defs.h)","")
-        OPT_DEFS += -include $(KEYBOARD_PATH_2)/boards/$(BOARD)/bootloader_defs.h
-    else ifneq ("$(wildcard $(KEYBOARD_PATH_1)/bootloader_defs.h)","")
-        OPT_DEFS += -include $(KEYBOARD_PATH_1)/bootloader_defs.h
-     else ifneq ("$(wildcard $(KEYBOARD_PATH_1)/boards/$(BOARD)/bootloader_defs.h)","")
-        OPT_DEFS += -include $(KEYBOARD_PATH_1)/boards/$(BOARD)/bootloader_defs.h
-    else ifneq ("$(wildcard $(TOP_DIR)/drivers/boards/$(BOARD)/bootloader_defs.h)","")
-        OPT_DEFS += -include $(TOP_DIR)/drivers/boards/$(BOARD)/bootloader_defs.h
-    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)","")
@@ -304,11 +279,6 @@ ifneq ("$(wildcard $(KEYBOARD_PATH_5)/post_config.h)","")
     POST_CONFIG_H += $(KEYBOARD_PATH_5)/post_config.h
 endif
 
-# Save the defines and includes here, so we don't include any keymap specific ones
-PROJECT_DEFS := $(OPT_DEFS)
-PROJECT_INC := $(VPATH) $(EXTRAINCDIRS) $(KEYBOARD_PATHS)
-PROJECT_CONFIG := $(CONFIG_H)
-
 # Userspace setup and definitions
 ifeq ("$(USER_NAME)","")
     USER_NAME := $(KEYMAP)
@@ -354,23 +324,17 @@ SRC += $(TMK_COMMON_SRC)
 OPT_DEFS += $(TMK_COMMON_DEFS)
 EXTRALDFLAGS += $(TMK_COMMON_LDFLAGS)
 
-ifeq ($(PLATFORM),AVR)
-ifeq ($(strip $(PROTOCOL)), VUSB)
-    include $(TMK_PATH)/protocol/vusb.mk
+include $(TMK_PATH)/$(PLATFORM_KEY).mk
+ifneq ($(strip $(PROTOCOL)),)
+    include $(TMK_PATH)/protocol/$(strip $(shell echo $(PROTOCOL) | tr '[:upper:]' '[:lower:]')).mk
 else
-    include $(TMK_PATH)/protocol/lufa.mk
-endif
-    include $(TMK_PATH)/avr.mk
+    include $(TMK_PATH)/protocol/$(PLATFORM_KEY).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
+# TODO: remove this bodge?
+PROJECT_DEFS := $(OPT_DEFS)
+PROJECT_INC := $(VPATH) $(EXTRAINCDIRS) $(KEYBOARD_PATHS)
+PROJECT_CONFIG := $(CONFIG_H)
 
 ifeq ($(strip $(VISUALIZER_ENABLE)), yes)
     VISUALIZER_DIR = $(QUANTUM_DIR)/visualizer

build_test.mk

@@ -41,6 +41,7 @@ all: elf
 
 VPATH += $(COMMON_VPATH)
 PLATFORM:=TEST
+PLATFORM_KEY:=test
 
 ifneq ($(filter $(FULL_TESTS),$(TEST)),)
 include tests/$(TEST)/rules.mk

common_features.mk

@@ -13,52 +13,42 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-SERIAL_DIR := $(QUANTUM_DIR)/serial_link
 SERIAL_PATH := $(QUANTUM_PATH)/serial_link
-SERIAL_SRC := $(wildcard $(SERIAL_PATH)/protocol/*.c)
-SERIAL_SRC += $(wildcard $(SERIAL_PATH)/system/*.c)
-SERIAL_DEFS += -DSERIAL_LINK_ENABLE
-COMMON_VPATH += $(SERIAL_PATH)
+
+QUANTUM_SRC += \
+    $(QUANTUM_DIR)/quantum.c \
+    $(QUANTUM_DIR)/keymap_common.c \
+    $(QUANTUM_DIR)/keycode_config.c
 
 ifeq ($(strip $(API_SYSEX_ENABLE)), yes)
     OPT_DEFS += -DAPI_SYSEX_ENABLE
-    SRC += $(QUANTUM_DIR)/api/api_sysex.c
     OPT_DEFS += -DAPI_ENABLE
-    SRC += $(QUANTUM_DIR)/api.c
     MIDI_ENABLE=yes
+    SRC += $(QUANTUM_DIR)/api/api_sysex.c
+    SRC += $(QUANTUM_DIR)/api.c
 endif
 
-MUSIC_ENABLE := 0
-
 ifeq ($(strip $(AUDIO_ENABLE)), yes)
     OPT_DEFS += -DAUDIO_ENABLE
-    MUSIC_ENABLE := 1
+    MUSIC_ENABLE = yes
     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
-        SRC += $(QUANTUM_DIR)/audio/audio_arm.c
-    endif
+    SRC += $(QUANTUM_DIR)/audio/audio_$(PLATFORM_KEY).c
     SRC += $(QUANTUM_DIR)/audio/voices.c
     SRC += $(QUANTUM_DIR)/audio/luts.c
 endif
 
 ifeq ($(strip $(MIDI_ENABLE)), yes)
     OPT_DEFS += -DMIDI_ENABLE
-    MUSIC_ENABLE := 1
+    MUSIC_ENABLE = yes
     SRC += $(QUANTUM_DIR)/process_keycode/process_midi.c
 endif
 
-ifeq ($(MUSIC_ENABLE), 1)
+MUSIC_ENABLE ?= no
+ifeq ($(MUSIC_ENABLE), yes)
     SRC += $(QUANTUM_DIR)/process_keycode/process_music.c
 endif
 
-ifeq ($(strip $(COMBO_ENABLE)), yes)
-    OPT_DEFS += -DCOMBO_ENABLE
-    SRC += $(QUANTUM_DIR)/process_keycode/process_combo.c
-endif
-
 ifeq ($(strip $(STENO_ENABLE)), yes)
     OPT_DEFS += -DSTENO_ENABLE
     VIRTSER_ENABLE ?= yes
@@ -80,26 +70,64 @@ ifeq ($(strip $(POINTING_DEVICE_ENABLE)), yes)
     SRC += $(QUANTUM_DIR)/pointing_device.c
 endif
 
-ifeq ($(strip $(UCIS_ENABLE)), yes)
-    OPT_DEFS += -DUCIS_ENABLE
-    UNICODE_COMMON := yes
-    SRC += $(QUANTUM_DIR)/process_keycode/process_ucis.c
-endif
-
-ifeq ($(strip $(UNICODEMAP_ENABLE)), yes)
-    OPT_DEFS += -DUNICODEMAP_ENABLE
-    UNICODE_COMMON := yes
-    SRC += $(QUANTUM_DIR)/process_keycode/process_unicodemap.c
-endif
-
-ifeq ($(strip $(UNICODE_ENABLE)), yes)
-    OPT_DEFS += -DUNICODE_ENABLE
-    UNICODE_COMMON := yes
-    SRC += $(QUANTUM_DIR)/process_keycode/process_unicode.c
-endif
-
-ifeq ($(strip $(UNICODE_COMMON)), yes)
-    SRC += $(QUANTUM_DIR)/process_keycode/process_unicode_common.c
+VALID_EEPROM_DRIVER_TYPES := vendor custom transient i2c spi
+EEPROM_DRIVER ?= vendor
+ifeq ($(filter $(EEPROM_DRIVER),$(VALID_EEPROM_DRIVER_TYPES)),)
+  $(error EEPROM_DRIVER="$(EEPROM_DRIVER)" is not a valid EEPROM driver)
+else
+  OPT_DEFS += -DEEPROM_ENABLE
+  ifeq ($(strip $(EEPROM_DRIVER)), custom)
+    OPT_DEFS += -DEEPROM_DRIVER -DEEPROM_CUSTOM
+    COMMON_VPATH += $(DRIVER_PATH)/eeprom
+    SRC += eeprom_driver.c
+  else ifeq ($(strip $(EEPROM_DRIVER)), i2c)
+    OPT_DEFS += -DEEPROM_DRIVER -DEEPROM_I2C
+    COMMON_VPATH += $(DRIVER_PATH)/eeprom
+    QUANTUM_LIB_SRC += i2c_master.c
+    SRC += eeprom_driver.c eeprom_i2c.c
+  else ifeq ($(strip $(EEPROM_DRIVER)), spi)
+    OPT_DEFS += -DEEPROM_DRIVER -DEEPROM_SPI
+    COMMON_VPATH += $(DRIVER_PATH)/eeprom
+    QUANTUM_LIB_SRC += spi_master.c
+    SRC += eeprom_driver.c eeprom_spi.c
+  else ifeq ($(strip $(EEPROM_DRIVER)), transient)
+    OPT_DEFS += -DEEPROM_DRIVER -DEEPROM_TRANSIENT
+    COMMON_VPATH += $(DRIVER_PATH)/eeprom
+    SRC += eeprom_driver.c eeprom_transient.c
+  else ifeq ($(strip $(EEPROM_DRIVER)), vendor)
+    OPT_DEFS += -DEEPROM_VENDOR
+    ifeq ($(PLATFORM),AVR)
+      # Automatically provided by avr-libc, nothing required
+    else ifeq ($(PLATFORM),CHIBIOS)
+      ifeq ($(MCU_SERIES), STM32F3xx)
+        SRC += $(PLATFORM_COMMON_DIR)/eeprom_stm32.c
+        SRC += $(PLATFORM_COMMON_DIR)/flash_stm32.c
+        OPT_DEFS += -DEEPROM_EMU_STM32F303xC
+        OPT_DEFS += -DSTM32_EEPROM_ENABLE
+      else ifeq ($(MCU_SERIES), STM32F1xx)
+        SRC += $(PLATFORM_COMMON_DIR)/eeprom_stm32.c
+        SRC += $(PLATFORM_COMMON_DIR)/flash_stm32.c
+        OPT_DEFS += -DEEPROM_EMU_STM32F103xB
+        OPT_DEFS += -DSTM32_EEPROM_ENABLE
+      else ifeq ($(MCU_SERIES)_$(MCU_LDSCRIPT), STM32F0xx_STM32F072xB)
+        SRC += $(PLATFORM_COMMON_DIR)/eeprom_stm32.c
+        SRC += $(PLATFORM_COMMON_DIR)/flash_stm32.c
+        OPT_DEFS += -DEEPROM_EMU_STM32F072xB
+        OPT_DEFS += -DSTM32_EEPROM_ENABLE
+      else ifneq ($(filter $(MCU_SERIES),STM32L0xx STM32L1xx),)
+        OPT_DEFS += -DEEPROM_DRIVER
+        COMMON_VPATH += $(DRIVER_PATH)/eeprom
+        SRC += eeprom_driver.c eeprom_stm32_L0_L1.c
+      else
+        # This will effectively work the same as "transient" if not supported by the chip
+        SRC += $(PLATFORM_COMMON_DIR)/eeprom_teensy.c
+      endif
+    else ifeq ($(PLATFORM),ARM_ATSAM)
+      SRC += $(PLATFORM_COMMON_DIR)/eeprom.c
+    else ifeq ($(PLATFORM),TEST)
+      SRC += $(PLATFORM_COMMON_DIR)/eeprom.c
+    endif
+  endif
 endif
 
 ifeq ($(strip $(RGBLIGHT_ENABLE)), yes)
@@ -108,7 +136,6 @@ ifeq ($(strip $(RGBLIGHT_ENABLE)), yes)
     SRC += $(QUANTUM_DIR)/color.c
     SRC += $(QUANTUM_DIR)/rgblight.c
     CIE1931_CURVE := yes
-    LED_BREATHING_TABLE := yes
     RGB_KEYCODES_ENABLE := yes
     ifeq ($(strip $(RGBLIGHT_CUSTOM_DRIVER)), yes)
         OPT_DEFS += -DRGBLIGHT_CUSTOM_DRIVER
@@ -124,7 +151,9 @@ ifneq ($(strip $(LED_MATRIX_ENABLE)), no)
     ifeq ($(filter $(LED_MATRIX_ENABLE),$(VALID_MATRIX_TYPES)),)
         $(error LED_MATRIX_ENABLE="$(LED_MATRIX_ENABLE)" is not a valid matrix type)
     else
-        OPT_DEFS += -DLED_MATRIX_ENABLE -DBACKLIGHT_ENABLE -DBACKLIGHT_CUSTOM_DRIVER
+        BACKLIGHT_ENABLE = yes
+        BACKLIGHT_DRIVER = custom
+        OPT_DEFS += -DLED_MATRIX_ENABLE
         SRC += $(QUANTUM_DIR)/led_matrix.c
         SRC += $(QUANTUM_DIR)/led_matrix_drivers.c
     endif
@@ -193,31 +222,18 @@ ifeq ($(strip $(RGB_KEYCODES_ENABLE)), yes)
     SRC += $(QUANTUM_DIR)/process_keycode/process_rgb.c
 endif
 
-ifeq ($(strip $(TAP_DANCE_ENABLE)), yes)
-    OPT_DEFS += -DTAP_DANCE_ENABLE
-    SRC += $(QUANTUM_DIR)/process_keycode/process_tap_dance.c
-endif
-
-ifeq ($(strip $(KEY_LOCK_ENABLE)), yes)
-    OPT_DEFS += -DKEY_LOCK_ENABLE
-    SRC += $(QUANTUM_DIR)/process_keycode/process_key_lock.c
-endif
-
 ifeq ($(strip $(PRINTING_ENABLE)), yes)
     OPT_DEFS += -DPRINTING_ENABLE
     SRC += $(QUANTUM_DIR)/process_keycode/process_printer.c
     SRC += $(TMK_DIR)/protocol/serial_uart.c
 endif
 
-ifeq ($(strip $(AUTO_SHIFT_ENABLE)), yes)
-    OPT_DEFS += -DAUTO_SHIFT_ENABLE
-    SRC += $(QUANTUM_DIR)/process_keycode/process_auto_shift.c
-    ifeq ($(strip $(AUTO_SHIFT_MODIFIERS)), yes)
-        OPT_DEFS += -DAUTO_SHIFT_MODIFIERS
-    endif
-endif
-
 ifeq ($(strip $(SERIAL_LINK_ENABLE)), yes)
+    SERIAL_SRC := $(wildcard $(SERIAL_PATH)/protocol/*.c)
+    SERIAL_SRC += $(wildcard $(SERIAL_PATH)/system/*.c)
+    SERIAL_DEFS += -DSERIAL_LINK_ENABLE
+    COMMON_VPATH += $(SERIAL_PATH)
+
     SRC += $(patsubst $(QUANTUM_PATH)/%,%,$(SERIAL_SRC))
     OPT_DEFS += $(SERIAL_DEFS)
     VAPTH += $(SERIAL_PATH)
@@ -249,23 +265,19 @@ ifeq ($(strip $(BACKLIGHT_ENABLE)), yes)
         $(error BACKLIGHT_DRIVER="$(BACKLIGHT_DRIVER)" is not a valid backlight type)
     endif
 
-    ifeq ($(strip $(VISUALIZER_ENABLE)), yes)
-        CIE1931_CURVE := yes
-    endif
-
     COMMON_VPATH += $(QUANTUM_DIR)/backlight
     SRC += $(QUANTUM_DIR)/backlight/backlight.c
+    SRC += $(QUANTUM_DIR)/process_keycode/process_backlight.c
     OPT_DEFS += -DBACKLIGHT_ENABLE
 
     ifeq ($(strip $(BACKLIGHT_DRIVER)), custom)
         OPT_DEFS += -DBACKLIGHT_CUSTOM_DRIVER
-    else ifeq ($(strip $(BACKLIGHT_DRIVER)), software)
-        SRC += $(QUANTUM_DIR)/backlight/backlight_soft.c
     else
-        ifeq ($(PLATFORM),AVR)
-            SRC += $(QUANTUM_DIR)/backlight/backlight_avr.c
+        SRC += $(QUANTUM_DIR)/backlight/backlight_driver_common.c
+        ifeq ($(strip $(BACKLIGHT_DRIVER)), pwm)
+            SRC += $(QUANTUM_DIR)/backlight/backlight_$(PLATFORM_KEY).c
         else
-            SRC += $(QUANTUM_DIR)/backlight/backlight_arm.c
+            SRC += $(QUANTUM_DIR)/backlight/backlight_$(strip $(BACKLIGHT_DRIVER)).c
         endif
     endif
 endif
@@ -292,13 +304,12 @@ ifeq ($(strip $(WS2812_DRIVER_REQUIRED)), yes)
     endif
 endif
 
-ifeq ($(strip $(CIE1931_CURVE)), yes)
-    OPT_DEFS += -DUSE_CIE1931_CURVE
-    LED_TABLES := yes
+ifeq ($(strip $(VISUALIZER_ENABLE)), yes)
+    CIE1931_CURVE := yes
 endif
 
-ifeq ($(strip $(LED_BREATHING_TABLE)), yes)
-    OPT_DEFS += -DUSE_LED_BREATHING_TABLE
+ifeq ($(strip $(CIE1931_CURVE)), yes)
+    OPT_DEFS += -DUSE_CIE1931_CURVE
     LED_TABLES := yes
 endif
 
@@ -316,34 +327,16 @@ ifeq ($(strip $(USB_HID_ENABLE)), yes)
     include $(TMK_DIR)/protocol/usb_hid.mk
 endif
 
+ifeq ($(strip $(WPM_ENABLE)), yes)
+    SRC += $(QUANTUM_DIR)/wpm.c
+    OPT_DEFS += -DWPM_ENABLE
+endif
+
 ifeq ($(strip $(ENCODER_ENABLE)), yes)
     SRC += $(QUANTUM_DIR)/encoder.c
     OPT_DEFS += -DENCODER_ENABLE
 endif
 
-HAPTIC_ENABLE ?= no
-ifneq ($(strip $(HAPTIC_ENABLE)),no)
-	COMMON_VPATH += $(DRIVER_PATH)/haptic
-	SRC += haptic.c
-	OPT_DEFS += -DHAPTIC_ENABLE
-endif
-
-ifneq ($(filter DRV2605L, $(HAPTIC_ENABLE)), )
-    SRC += DRV2605L.c
-    QUANTUM_LIB_SRC += i2c_master.c
-    OPT_DEFS += -DDRV2605L
-endif
-
-ifneq ($(filter SOLENOID, $(HAPTIC_ENABLE)), )
-    SRC += solenoid.c
-    OPT_DEFS += -DSOLENOID_ENABLE
-endif
-
-ifeq ($(strip $(HD44780_ENABLE)), yes)
-    SRC += drivers/avr/hd44780.c
-    OPT_DEFS += -DHD44780_ENABLE
-endif
-
 ifeq ($(strip $(VELOCIKEY_ENABLE)), yes)
     OPT_DEFS += -DVELOCIKEY_ENABLE
     SRC += $(QUANTUM_DIR)/velocikey.c
@@ -362,20 +355,11 @@ ifeq ($(strip $(DYNAMIC_KEYMAP_ENABLE)), yes)
     SRC += $(QUANTUM_DIR)/dynamic_keymap.c
 endif
 
-ifeq ($(strip $(LEADER_ENABLE)), yes)
-  SRC += $(QUANTUM_DIR)/process_keycode/process_leader.c
-  OPT_DEFS += -DLEADER_ENABLE
+ifeq ($(strip $(DIP_SWITCH_ENABLE)), yes)
+    OPT_DEFS += -DDIP_SWITCH_ENABLE
+    SRC += $(QUANTUM_DIR)/dip_switch.c
 endif
 
-include $(DRIVER_PATH)/qwiic/qwiic.mk
-
-QUANTUM_SRC:= \
-    $(QUANTUM_DIR)/quantum.c \
-    $(QUANTUM_DIR)/keymap_common.c \
-    $(QUANTUM_DIR)/keycode_config.c
-
-
-
 VALID_CUSTOM_MATRIX_TYPES:= yes lite no
 
 CUSTOM_MATRIX ?= no
@@ -418,13 +402,44 @@ ifeq ($(strip $(SPLIT_KEYBOARD)), yes)
         QUANTUM_SRC += $(QUANTUM_DIR)/split_common/transport.c
         # Functions added via QUANTUM_LIB_SRC are only included in the final binary if they're called.
         # Unused functions are pruned away, which is why we can add multiple drivers here without bloat.
-        QUANTUM_LIB_SRC += $(QUANTUM_DIR)/split_common/serial.c \
-                           i2c_master.c \
-                           i2c_slave.c
+        ifeq ($(PLATFORM),AVR)
+            QUANTUM_LIB_SRC += i2c_master.c \
+                               i2c_slave.c
+        endif
+
+        SERIAL_DRIVER ?= bitbang
+        ifeq ($(strip $(SERIAL_DRIVER)), bitbang)
+            QUANTUM_LIB_SRC += serial.c
+        else
+            QUANTUM_LIB_SRC += serial_$(strip $(SERIAL_DRIVER)).c
+        endif
     endif
     COMMON_VPATH += $(QUANTUM_PATH)/split_common
 endif
 
+HAPTIC_ENABLE ?= no
+ifneq ($(strip $(HAPTIC_ENABLE)),no)
+    COMMON_VPATH += $(DRIVER_PATH)/haptic
+    SRC += haptic.c
+    OPT_DEFS += -DHAPTIC_ENABLE
+endif
+
+ifneq ($(filter DRV2605L, $(HAPTIC_ENABLE)), )
+    SRC += DRV2605L.c
+    QUANTUM_LIB_SRC += i2c_master.c
+    OPT_DEFS += -DDRV2605L
+endif
+
+ifneq ($(filter SOLENOID, $(HAPTIC_ENABLE)), )
+    SRC += solenoid.c
+    OPT_DEFS += -DSOLENOID_ENABLE
+endif
+
+ifeq ($(strip $(HD44780_ENABLE)), yes)
+    SRC += drivers/avr/hd44780.c
+    OPT_DEFS += -DHD44780_ENABLE
+endif
+
 ifeq ($(strip $(OLED_DRIVER_ENABLE)), yes)
     OPT_DEFS += -DOLED_DRIVER_ENABLE
     COMMON_VPATH += $(DRIVER_PATH)/oled
@@ -432,10 +447,34 @@ ifeq ($(strip $(OLED_DRIVER_ENABLE)), yes)
     SRC += oled_driver.c
 endif
 
+include $(DRIVER_PATH)/qwiic/qwiic.mk
+
+ifeq ($(strip $(UCIS_ENABLE)), yes)
+    OPT_DEFS += -DUCIS_ENABLE
+    UNICODE_COMMON := yes
+    SRC += $(QUANTUM_DIR)/process_keycode/process_ucis.c
+endif
+
+ifeq ($(strip $(UNICODEMAP_ENABLE)), yes)
+    OPT_DEFS += -DUNICODEMAP_ENABLE
+    UNICODE_COMMON := yes
+    SRC += $(QUANTUM_DIR)/process_keycode/process_unicodemap.c
+endif
+
+ifeq ($(strip $(UNICODE_ENABLE)), yes)
+    OPT_DEFS += -DUNICODE_ENABLE
+    UNICODE_COMMON := yes
+    SRC += $(QUANTUM_DIR)/process_keycode/process_unicode.c
+endif
+
+ifeq ($(strip $(UNICODE_COMMON)), yes)
+    SRC += $(QUANTUM_DIR)/process_keycode/process_unicode_common.c
+endif
+
 SPACE_CADET_ENABLE ?= yes
 ifeq ($(strip $(SPACE_CADET_ENABLE)), yes)
-  SRC += $(QUANTUM_DIR)/process_keycode/process_space_cadet.c
-  OPT_DEFS += -DSPACE_CADET_ENABLE
+    SRC += $(QUANTUM_DIR)/process_keycode/process_space_cadet.c
+    OPT_DEFS += -DSPACE_CADET_ENABLE
 endif
 
 MAGIC_ENABLE ?= yes
@@ -444,12 +483,41 @@ ifeq ($(strip $(MAGIC_ENABLE)), yes)
     OPT_DEFS += -DMAGIC_KEYCODE_ENABLE
 endif
 
+GRAVE_ESC_ENABLE ?= yes
+ifeq ($(strip $(GRAVE_ESC_ENABLE)), yes)
+    SRC += $(QUANTUM_DIR)/process_keycode/process_grave_esc.c
+    OPT_DEFS += -DGRAVE_ESC_ENABLE
+endif
+
 ifeq ($(strip $(DYNAMIC_MACRO_ENABLE)), yes)
     SRC += $(QUANTUM_DIR)/process_keycode/process_dynamic_macro.c
     OPT_DEFS += -DDYNAMIC_MACRO_ENABLE
 endif
 
-ifeq ($(strip $(DIP_SWITCH_ENABLE)), yes)
-  SRC += $(QUANTUM_DIR)/dip_switch.c
-  OPT_DEFS += -DDIP_SWITCH_ENABLE
+ifeq ($(strip $(COMBO_ENABLE)), yes)
+    SRC += $(QUANTUM_DIR)/process_keycode/process_combo.c
+    OPT_DEFS += -DCOMBO_ENABLE
+endif
+
+ifeq ($(strip $(TAP_DANCE_ENABLE)), yes)
+    SRC += $(QUANTUM_DIR)/process_keycode/process_tap_dance.c
+    OPT_DEFS += -DTAP_DANCE_ENABLE
+endif
+
+ifeq ($(strip $(KEY_LOCK_ENABLE)), yes)
+    SRC += $(QUANTUM_DIR)/process_keycode/process_key_lock.c
+    OPT_DEFS += -DKEY_LOCK_ENABLE
+endif
+
+ifeq ($(strip $(LEADER_ENABLE)), yes)
+    SRC += $(QUANTUM_DIR)/process_keycode/process_leader.c
+    OPT_DEFS += -DLEADER_ENABLE
+endif
+
+ifeq ($(strip $(AUTO_SHIFT_ENABLE)), yes)
+    SRC += $(QUANTUM_DIR)/process_keycode/process_auto_shift.c
+    OPT_DEFS += -DAUTO_SHIFT_ENABLE
+    ifeq ($(strip $(AUTO_SHIFT_MODIFIERS)), yes)
+        OPT_DEFS += -DAUTO_SHIFT_MODIFIERS
+    endif
 endif

docs/ChangeLog/20200229.md

@@ -0,0 +1,75 @@
+# QMK Breaking Change - 2020 Feb 29 Changelog
+
+Four times a year QMK runs a process for merging Breaking Changes. A Breaking Change is any change which modifies how QMK behaves in a way that is incompatible or potentially dangerous. We limit these changes to 4 times per year so that users can have confidence that updating their QMK tree will not break their keymaps.
+
+
+## Update ChibiOS/ChibiOS-Contrib/uGFX submodules
+
+* General Notes
+    * A `make git-submodule` may be required after pulling the latest QMK firmware code to update affected submodules to the upgraded revisions
+    * Enabling link-time-optimization (`LINK_TIME_OPTIMIZATION_ENABLE = yes`) should work on a lot more boards
+* Upgrade to ChibiOS ver19.1.3
+    * This will allow QMK to update to upstream ChibiOS a lot easier -- the old version was ~2 years out of date. Automated update scripts have been made available to simplify future upgrades.
+    * Includes improved MCU support and bugfixes
+    * ChibiOS revision is now included in Command output
+    * Timers should now be more accurate
+* Upgrade to newer ChibiOS-Contrib
+    * Also includes improved MCU support and bugfixes
+    * ChibiOS-Contrib revision is now included in Command output
+* Upgrade to newer uGFX
+    * Required in order to support updated ChibiOS
+
+
+## Fix ChibiOS timer overflow for 16-bit SysTick devices
+
+* On 16-bit SysTick devices, the timer subsystem in QMK was incorrectly dealing with overflow.
+    * When running at a 100000 SysTick frequency (possible on 16-bit devices, but uncommon), this overflow would occur after 0.65 seconds.
+* Timers are now correctly handling this overflow case and timing should now be correct on ChibiOS/ARM.
+
+
+## Update LUFA submodule
+
+* Updates the LUFA submodule to include updates from upstream (abcminiuser/lufa)
+* Includes some cleanup for QMK DFU generation
+
+
+## Encoder flip
+
+* Flips the encoder direction so that `clockwise == true` is for actually turning the knob clockwise
+* Adds `ENCODER_DIRECTION_FLIP` define, so that reversing the expected dirction is simple for users.
+* Cleans up documentation page for encoders
+
+
+## Adding support for `BACKLIGHT_ON_STATE` for hardware PWM backlight
+
+* Previously, the define only affected software PWM, and hardware PWM always assumed an N-channel MOSFET.
+* The hardware PWM backlight setup has been updated to respect this option.
+* The default "on" state has been changed to `1` - **this impacts all keyboards using software PWM backlight that do not define it explicitly**. If your keyboard's backlight is acting strange, it may have a P-channel MOSFET, and will need to have `#define BACKLIGHT_ON_STATE 0` added to the keyboard-level `config.h`. Please see the PR for more detailed information.
+
+
+## Migrating `ACTION_LAYER_TAP_KEY()` entries in `fn_actions` to `LT()` keycodes
+
+* `fn_actions` is deprecated, and its functionality has been superseded by direct keycodes and `process_record_user()`
+* The end result of removing this obsolete feature should result in a decent reduction in firmware size and code complexity
+* All keymaps affected are recommended to switch away from `fn_actions` in favour of the [custom keycode](https://docs.qmk.fm/#/custom_quantum_functions) and [macro](https://docs.qmk.fm/#/feature_macros) features
+
+
+## Moving backlight keycode handling to `process_keycode/`
+
+* This refactors the backlight keycode logic to be clearer and more modular.
+* All backlight-related keycodes are now actioned in a single file.
+* The `ACTION_BACKLIGHT_*` macros have also been deleted. If you are still using these in a `fn_actions[]` block, please switch to using the backlight keycodes or functions directly.
+
+
+## Refactor Planck keymaps to use Layout Macros
+
+* Refactor Planck keymaps to use layout macros instead of raw matrix assignments
+* Makes keymaps revision-agnostic
+* Should reduce noise and errors in Travis CI logs
+
+
+## GON NerD codebase refactor
+
+* Splits the codebase for GON NerD 60 and NerdD TKL PCBs into two separate directories.
+* If your keymap is for a NerD 60 PCB, your `make` command is now `make gon/nerd60:<keymap>`.
+* If your keymap is for a NerD TKL PCB, your `make` command is now `make gon/nerdtkl:<keymap>`.

docs/README.md

@@ -9,24 +9,35 @@
 
 ## What is QMK Firmware?
 
-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.
+QMK (*Quantum Mechanical Keyboard*) is an open source community centered around developing computer input devices. The community encompasses all sorts of input devices, such as keyboards, mice, and MIDI devices. A core group of collaborators maintains [QMK Firmware](https://github.com/qmk/qmk_firmware), [QMK Configurator](https://config.qmk.fm), [QMK Toolbox](https://github.com/qmk/qmk_toolbox), [qmk.fm](https://qmk.fm), and this documentation with the help of community members like you.
 
-## How to Get It
+## Get Started
 
-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.
+Totally new to QMK? There are two ways to get started:
 
-Otherwise, you can clone it directly with `git clone https://github.com/qmk/qmk_firmware`. Do not download the zip or tar files; a git repository is required to download the submodules in order to compile.
+* Basic: [QMK Configurator](https://config.qmk.fm)
+    * Just select your keyboard from the dropdown and program your keyboard.
+    * We have an [introductory video](https://www.youtube.com/watch?v=-imgglzDMdY) you can watch.
+    * There is also an overview [document you can read](newbs_building_firmware_configurator.md).
+* Advanced: [Use The Source](newbs.md)
+    * More powerful, but harder to use
 
-## How to Compile
+## Make It Yours
 
-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:
+QMK has lots of [features](features.md) to explore, and a good deal of reference documentation to dig through. Most features are taken advantage of by modifying your [keymap](keymap.md), and changing the [keycodes](keycodes.md).
 
-    make planck/rev4:default
+## Need help?
 
-This would build the `rev4` revision of the `planck` with the `default` keymap. Not all keyboards have revisions (also called subprojects or folders), in which case, it can be omitted:
+Check out the [support page](support.md) to see how you can get help using QMK.
 
-    make preonic:default
+## Give Back
 
-## How to Customize
+There are a lot of ways you can contribute to the QMK Community. The easiest way to get started is to use it and spread the word to your friends.
 
-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).
+* Help people out on our forums and chat rooms:
+    * [/r/olkb](https://www.reddit.com/r/olkb/)
+    * [Discord Server](https://discord.gg/Uq7gcHh)
+* Contribute to our documentation by clicking "Edit This Page" at the bottom
+* [Translate our documentation into your language](translating.md)
+* [Report a bug](https://github.com/qmk/qmk_firmware/issues/new/choose)
+* [Open a Pull Request](contributing.md)

docs/_summary.md

@@ -1,128 +1,172 @@
-* [Complete Newbs Guide](newbs.md)
-  * [Getting Started](newbs_getting_started.md)
+* Tutorial
+  * [Introduction](newbs.md)
+  * [Setup](newbs_getting_started.md)
   * [Building Your First Firmware](newbs_building_firmware.md)
   * [Flashing Firmware](newbs_flashing.md)
   * [Testing and Debugging](newbs_testing_debugging.md)
-  * [Best Git Practices](newbs_git_best_practices.md)
-    * [Using Your Fork's Master](newbs_git_using_your_master_branch.md)
-    * [Resolving Merge Conflicts](newbs_git_resolving_merge_conflicts.md)
-    * [Resynchronizing a Branch](newbs_git_resynchronize_a_branch.md)
-  * [Learning Resources](newbs_learn_more_resources.md)
+  * [Getting Help/Support](support.md)
+  * [Other Resources](newbs_learn_more_resources.md)
+  * [Syllabus](syllabus.md)
 
-* [QMK Basics](README.md)
-  * [QMK Introduction](getting_started_introduction.md)
-  * [QMK CLI](cli.md)
-  * [QMK CLI Config](cli_configuration.md)
-  * [Contributing to QMK](contributing.md)
-  * [How to Use Github](getting_started_github.md)
-  * [Getting Help](getting_started_getting_help.md)
-
-* [Breaking Changes](breaking_changes.md)
-  * [2019 Aug 30](ChangeLog/20190830.md)
-
-* [FAQ](faq.md)
+* FAQs
   * [General FAQ](faq_general.md)
   * [Build/Compile QMK](faq_build.md)
   * [Debugging/Troubleshooting QMK](faq_debug.md)
-  * [Keymap](faq_keymap.md)
-  * [Driver Installation with Zadig](driver_installation_zadig.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)
-  * [Compatible Microcontrollers](compatible_microcontrollers.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)
-  * [Coding Conventions - C](coding_conventions_c.md)
-  * [Coding Conventions - Python](coding_conventions_python.md)
-  * [Documentation Best Practices](documentation_best_practices.md)
-  * [Documentation Templates](documentation_templates.md)
+  * [Keymap FAQ](faq_keymap.md)
   * [Glossary](reference_glossary.md)
-  * [Unit Testing](unit_testing.md)
-  * [Useful Functions](ref_functions.md)
-  * [Configurator Support](reference_configurator_support.md)
-  * [info.json Format](reference_info_json.md)
-  * [Python CLI Development](cli_development.md)
 
-* [Features](features.md)
-  * [Basic Keycodes](keycodes_basic.md)
-  * [US ANSI Shifted Keys](keycodes_us_ansi_shifted.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)
-  * [Combos](feature_combo.md)
-  * [Command](feature_command.md)
-  * [Debounce API](feature_debounce_type.md)
-  * [DIP Switch](feature_dip_switch.md)
-  * [Dynamic Macros](feature_dynamic_macros.md)
-  * [Encoders](feature_encoders.md)
-  * [Grave Escape](feature_grave_esc.md)
-  * [Haptic Feedback](feature_haptic_feedback.md)
-  * [HD44780 LCD Controller](feature_hd44780.md)
-  * [Key Lock](feature_key_lock.md)
-  * [Layouts](feature_layouts.md)
-  * [Leader Key](feature_leader_key.md)
-  * [LED Matrix](feature_led_matrix.md)
-  * [Macros](feature_macros.md)
-  * [Mouse Keys](feature_mouse_keys.md)
-  * [OLED Driver](feature_oled_driver.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](feature_space_cadet.md)
-  * [Split Keyboard](feature_split_keyboard.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)
-  * [Velocikey](feature_velocikey.md)
+* Configurator
+  * [Overview](newbs_building_firmware_configurator.md)
+  * [Step by Step](configurator_step_by_step.md)
+  * [Troubleshooting](configurator_troubleshooting.md)
+  * QMK API
+    * [Overview](api_overview.md)
+    * [API Documentation](api_docs.md)
+    * [Keyboard Support](reference_configurator_support.md)
 
-* For Makers and Modders
-  * [Hand Wiring Guide](hand_wire.md)
-  * [ISP Flashing Guide](isp_flashing_guide.md)
-  * [ARM Debugging Guide](arm_debugging.md)
-  * [ADC Driver](adc_driver.md)
-  * [I2C Driver](i2c_driver.md)
-  * [WS2812 Driver](ws2812_driver.md)
-  * [GPIO Controls](internals_gpio_control.md)
-  * [Custom Matrix](custom_matrix.md)
-  * [Proton C Conversion](proton_c_conversion.md)
+* CLI
+    * [Overview](cli.md)
+    * [Configuration](cli_configuration.md)
+    * [Commands](cli_commands.md)
 
-* For a Deeper Understanding
-  * [How Keyboards Work](how_keyboards_work.md)
-  * [Understanding QMK](understanding_qmk.md)
+* Using QMK
+  * Guides
+    * [Customizing Functionality](custom_quantum_functions.md)
+    * [Driver Installation with Zadig](driver_installation_zadig.md)
+    * [Keymap Overview](keymap.md)
+    * Development Environments
+      * [Docker Guide](getting_started_docker.md)
+      * [Vagrant Guide](getting_started_vagrant.md)
+    * Flashing
+      * [Flashing](flashing.md)
+      * [Flashing ATmega32A (ps2avrgb)](flashing_bootloadhid.md)
+    * IDEs
+      * [Using Eclipse with QMK](other_eclipse.md)
+      * [Using VSCode with QMK](other_vscode.md)
+    * Git Best Practices
+      * [Introduction](newbs_git_best_practices.md)
+      * [Your Fork](newbs_git_using_your_master_branch.md)
+      * [Merge Conflicts](newbs_git_resolving_merge_conflicts.md)
+      * [Fixing Your Branch](newbs_git_resynchronize_a_branch.md)
+    * Keyboard Building
+      * [Hand Wiring Guide](hand_wire.md)
+      * [ISP Flashing Guide](isp_flashing_guide.md)
 
-* Other Topics
-  * [Using Eclipse with QMK](other_eclipse.md)
-  * [Using VSCode with QMK](other_vscode.md)
-  * [Support](support.md)
-  * [Translating the QMK Docs](translating.md)
+  * Simple Keycodes
+    * [Full List](keycodes.md)
+    * [Basic Keycodes](keycodes_basic.md)
+    * [Modifier Keys](feature_advanced_keycodes.md)
+    * [Quantum Keycodes](quantum_keycodes.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)
+  * Advanced Keycodes
+    * [Command](feature_command.md)
+    * [Dynamic Macros](feature_dynamic_macros.md)
+    * [Grave Escape](feature_grave_esc.md)
+    * [Leader Key](feature_leader_key.md)
+    * [Mod-Tap](mod_tap.md)
+    * [Macros](feature_macros.md)
+    * [Mouse Keys](feature_mouse_keys.md)
+    * [Space Cadet Shift](feature_space_cadet.md)
+    * [US ANSI Shifted Keys](keycodes_us_ansi_shifted.md)
+
+  * Software Features
+    * [Auto Shift](feature_auto_shift.md)
+    * [Combos](feature_combo.md)
+    * [Debounce API](feature_debounce_type.md)
+    * [Key Lock](feature_key_lock.md)
+    * [Layers](feature_layers.md)
+    * [One Shot Keys](one_shot_keys.md)
+    * [Pointing Device](feature_pointing_device.md)
+    * [Raw HID](feature_rawhid.md)
+    * [Swap Hands](feature_swap_hands.md)
+    * [Tap Dance](feature_tap_dance.md)
+    * [Tap-Hold Configuration](tap_hold.md)
+    * [Terminal](feature_terminal.md)
+    * [Unicode](feature_unicode.md)
+    * [Userspace](feature_userspace.md)
+    * [WPM Calculation](feature_wpm.md)
+
+  * Hardware Features
+    * Displays
+      * [HD44780 LCD Controller](feature_hd44780.md)
+      * [OLED Driver](feature_oled_driver.md)
+    * Lighting
+      * [Backlight](feature_backlight.md)
+      * [LED Matrix](feature_led_matrix.md)
+      * [RGB Lighting](feature_rgblight.md)
+      * [RGB Matrix](feature_rgb_matrix.md)
+    * [Audio](feature_audio.md)
+    * [Bluetooth](feature_bluetooth.md)
+    * [Bootmagic](feature_bootmagic.md)
+    * [Custom Matrix](custom_matrix.md)
+    * [DIP Switch](feature_dip_switch.md)
+    * [Encoders](feature_encoders.md)
+    * [Haptic Feedback](feature_haptic_feedback.md)
+    * [Proton C Conversion](proton_c_conversion.md)
+    * [PS/2 Mouse](feature_ps2_mouse.md)
+    * [Split Keyboard](feature_split_keyboard.md)
+    * [Stenography](feature_stenography.md)
+    * [Thermal Printer](feature_thermal_printer.md)
+    * [Velocikey](feature_velocikey.md)
+
+* Developing QMK
+  * Breaking Changes
+    * [Overview](breaking_changes.md)
+    * [My Pull Request Was Flagged](breaking_changes_instructions.md)
+    * History
+      * [2020 Feb 29](ChangeLog/20200229.md)
+      * [2019 Aug 30](ChangeLog/20190830.md)
+
+  * C Development
+    * [ARM Debugging Guide](arm_debugging.md)
+    * [AVR Processors](hardware_avr.md)
+    * [Coding Conventions](coding_conventions_c.md)
+    * [Compatible Microcontrollers](compatible_microcontrollers.md)
+    * [Drivers](hardware_drivers.md)
+      * [ADC Driver](adc_driver.md)
+      * [I2C Driver](i2c_driver.md)
+      * [SPI Driver](spi_driver.md)
+      * [WS2812 Driver](ws2812_driver.md)
+      * [EEPROM Driver](eeprom_driver.md)
+      * ['serial' Driver](serial_driver.md)
+    * [GPIO Controls](internals_gpio_control.md)
+    * [Keyboard Guidelines](hardware_keyboard_guidelines.md)
+
+  * Python Development
+    * [Coding Conventions](coding_conventions_python.md)
+    * [QMK CLI Development](cli_development.md)
+
+  * Configurator Development
+    * QMK API
+      * [Development Environment](api_development_environment.md)
+      * [Architecture Overview](api_development_overview.md)
+
+  * Hardware Platform Development
+    * Arm/ChibiOS
+      * [Early initialization](platformdev_chibios_earlyinit.md)
+
+  * QMK Reference
+    * [Contributing to QMK](contributing.md)
+    * [Translating the QMK Docs](translating.md)
+    * [Config Options](config_options.md)
+    * [Make Documentation](getting_started_make_guide.md)
+    * [Documentation Best Practices](documentation_best_practices.md)
+    * [Documentation Templates](documentation_templates.md)
+    * [Community Layouts](feature_layouts.md)
+    * [Unit Testing](unit_testing.md)
+    * [Useful Functions](ref_functions.md)
+    * [info.json Format](reference_info_json.md)
+
+  * For a Deeper Understanding
+    * [How Keyboards Work](how_keyboards_work.md)
+    * [How a Matrix Works](how_a_matrix_works.md)
+    * [Understanding QMK](understanding_qmk.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/adc_driver.md

@@ -2,7 +2,7 @@
 
 QMK can leverage the Analog-to-Digital Converter (ADC) on supported MCUs to measure voltages on certain pins. This can be useful for implementing things such as battery level indicators for Bluetooth keyboards, or volume controls using a potentiometer, as opposed to a [rotary encoder](feature_encoders.md).
 
-This driver is currently AVR-only. The values returned are 10-bit integers (0-1023) mapped between 0V and VCC (usually 5V or 3.3V).
+This driver currently supports both AVR and a limited selection of ARM devices. The values returned are 10-bit integers (0-1023) mapped between 0V and VCC (usually 5V or 3.3V for AVR, 3.3V only for ARM), however on ARM there is more flexibility in control of operation through `#define`s if you need more precision.
 
 ## Usage
 
@@ -20,6 +20,8 @@ Then place this include at the top of your code:
 
 ## Channels
 
+### AVR
+
 |Channel|AT90USB64/128|ATmega16/32U4|ATmega32A|ATmega328P|
 |-------|-------------|-------------|---------|----------|
 |0      |`F0`         |`F0`         |`A0`     |`C0`      |
@@ -39,8 +41,84 @@ Then place this include at the top of your code:
 
 <sup>\* The ATmega328P possesses two extra ADC channels; however, they are not present on the DIP pinout, and are not shared with GPIO pins. You can use `adc_read()` directly to gain access to these.</sup>
 
+### ARM
+
+Note that some of these pins are doubled-up on ADCs with the same channel. This is because the pins can be used for either ADC.
+
+Also note that the F0 and F3 use different numbering schemes. The F0 has a single ADC and the channels are 0-based, whereas the F3 has 4 ADCs and the channels are 1 based. This is because the F0 uses the `ADCv1` implementation of the ADC, whereas the F3 uses the `ADCv3` implementation.
+
+|ADC|Channel|STM32F0XX|STM32F3XX|
+|---|-------|---------|---------|
+|1  |0      |`A0`     |         |
+|1  |1      |`A1`     |`A0`     |
+|1  |2      |`A2`     |`A1`     |
+|1  |3      |`A3`     |`A2`     |
+|1  |4      |`A4`     |`A3`     |
+|1  |5      |`A5`     |`F4`     |
+|1  |6      |`A6`     |`C0`     |
+|1  |7      |`A7`     |`C1`     |
+|1  |8      |`B0`     |`C2`     |
+|1  |9      |`B1`     |`C3`     |
+|1  |10     |`C0`     |`F2`     |
+|1  |11     |`C1`     |         |
+|1  |12     |`C2`     |         |
+|1  |13     |`C3`     |         |
+|1  |14     |`C4`     |         |
+|1  |15     |`C5`     |         |
+|1  |16     |         |         |
+|2  |1      |         |`A4`     |
+|2  |2      |         |`A5`     |
+|2  |3      |         |`A6`     |
+|2  |4      |         |`A7`     |
+|2  |5      |         |`C4`     |
+|2  |6      |         |`C0`     |
+|2  |7      |         |`C1`     |
+|2  |8      |         |`C2`     |
+|2  |9      |         |`C3`     |
+|2  |10     |         |`F2`     |
+|2  |11     |         |`C5`     |
+|2  |12     |         |`B2`     |
+|2  |13     |         |         |
+|2  |14     |         |         |
+|2  |15     |         |         |
+|2  |16     |         |         |
+|3  |1      |         |`B1`     |
+|3  |2      |         |`E9`     |
+|3  |3      |         |`E13`    |
+|3  |4      |         |         |
+|3  |5      |         |         |
+|3  |6      |         |`E8`     |
+|3  |7      |         |`D10`    |
+|3  |8      |         |`D11`    |
+|3  |9      |         |`D12`    |
+|3  |10     |         |`D13`    |
+|3  |11     |         |`D14`    |
+|3  |12     |         |`B0`     |
+|3  |13     |         |`E7`     |
+|3  |14     |         |`E10`    |
+|3  |15     |         |`E11`    |
+|3  |16     |         |`E12`    |
+|4  |1      |         |`E14`    |
+|4  |2      |         |`B12`    |
+|4  |3      |         |`B13`    |
+|4  |4      |         |`B14`    |
+|4  |5      |         |`B15`    |
+|4  |6      |         |`E8`     |
+|4  |7      |         |`D10`    |
+|4  |8      |         |`D11`    |
+|4  |9      |         |`D12`    |
+|4  |10     |         |`D13`    |
+|4  |11     |         |`D14`    |
+|4  |12     |         |`D8`     |
+|4  |13     |         |`D9`     |
+|4  |14     |         |         |
+|4  |15     |         |         |
+|4  |16     |         |         |
+
 ## Functions
 
+### AVR
+
 |Function                    |Description                                                                                                        |
 |----------------------------|-------------------------------------------------------------------------------------------------------------------|
 |`analogReference(mode)`     |Sets the analog voltage reference source. Must be one of `ADC_REF_EXTERNAL`, `ADC_REF_POWER` or `ADC_REF_INTERNAL`.|
@@ -48,3 +126,28 @@ Then place this include at the top of your code:
 |`analogReadPin(pin)`        |Reads the value from the specified QMK pin, eg. `F6` for ADC6 on the ATmega32U4.                                   |
 |`pinToMux(pin)`             |Translates a given QMK pin to a mux value. If an unsupported pin is given, returns the mux value for "0V (GND)".   |
 |`adc_read(mux)`             |Reads the value from the ADC according to the specified mux. See your MCU's datasheet for more information.        |
+
+### ARM
+
+Note that care was taken to match all of the functions used for AVR devices, however complications in the ARM platform prevent that from always being possible. For example, the `STM32` chips do not have assigned Arduino pins. We could use the default pin numbers, but those numbers change based on the package type of the device. For this reason, please specify your target pins with their identifiers (`A0`, `F3`, etc.). Also note that there are some variants of functions that accept the target ADC for the pin. Some pins can be used for multiple ADCs, and this specified can help you pick which ADC will be used to interact with that pin.
+
+|Function                    |Description                                                                                                         |
+|----------------------------|--------------------------------------------------------------------------------------------------------------------|
+|`analogReadPin(pin)`        |Reads the value from the specified QMK pin, eg. `A0` for channel 0 on the STM32F0 and ADC1 channel 1 on the STM32F3. Note that if a pin can be used for multiple ADCs, it will pick the lower numbered ADC for this function. eg. `C0` will be channel 6 of ADC 1 when it could be used for ADC 2 as well.|
+|`analogReadPinAdc(pin, adc)`|Reads the value from the specified QMK pin and ADC, eg. `C0, 1` will read from channel 6, ADC 2 instead of ADC 1. Note that the ADCs are 0-indexed for this function.|
+|`pinToMux(pin)`             |Translates a given QMK pin to a channel and ADC combination. If an unsupported pin is given, returns the mux value for "0V (GND)".|
+|`adc_read(mux)`             |Reads the value from the ADC according to the specified pin and adc combination. See your MCU's datasheet for more information.|
+
+## Configuration
+
+## ARM
+
+The ARM implementation of the ADC has a few additional options that you can override in your own keyboards and keymaps to change how it operates.
+
+|`#define`          |Type  |Default              |Description|
+|-------------------|------|---------------------|-----------|
+|ADC_CIRCULAR_BUFFER|`bool`|`false`              |If `TRUE`, then the implementation will use a circular buffer.|
+|ADC_NUM_CHANNELS   |`int` |`1`                  |Sets the number of channels that will be scanned as part of an ADC operation. The current implementation only supports `1`.|
+|ADC_BUFFER_DEPTH   |`int` |`2`                  |Sets the depth of each result. Since we are only getting a 12-bit result by default, we set this to `2` bytes so we can contain our one value. This could be set to 1 if you opt for a 8-bit or lower result.|
+|ADC_SAMPLING_RATE  |`int` |`ADC_SMPR_SMP_1P5`   |Sets the sampling rate of the ADC. By default, it is set to the fastest setting. Please consult the corresponding `hal_adc_lld.h` in ChibiOS for your specific microcontroller for further documentation on your available options.|
+|ADC_RESOLUTION     |`int` |`ADC_CFGR1_RES_12BIT`|The resolution of your result. We choose 12 bit by default, but you can opt for 12, 10, 8, or 6 bit. Please consult the corresponding `hal_adc_lld.h` in ChibiOS for your specific microcontroller for further documentation on your available options.|

docs/api_development_environment.md

@@ -0,0 +1,3 @@
+# Development Environment Setup
+
+To setup a development stack head over to the [qmk_web_stack](https://github.com/qmk/qmk_web_stack).

docs/api_development_overview.md

@@ -0,0 +1,44 @@
+# QMK Compiler Development Guide
+
+This page attempts to introduce developers to the QMK Compiler. It does not go into nitty gritty details- for that you should read code. What this will give you is a framework to hang your understanding on as you read the code.
+
+# Overview
+
+The QMK Compile API consists of a few movings parts:
+
+![Architecture Diagram](https://raw.githubusercontent.com/qmk/qmk_api/master/docs/architecture.svg)
+
+API Clients interact exclusively with the API service. This is where they submit jobs, check status, and download results. The API service inserts compile jobs into [Redis Queue](https://python-rq.org) and checks both RQ and S3 for the results of those jobs.
+
+Workers fetch new compile jobs from RQ, compile them, and then upload the source and the binary to an S3 compatible storage engine.
+
+# Workers
+
+QMK Compiler Workers are responsible for doing the actual building. When a worker pulls a job from RQ it does several things to complete that job:
+
+* Make a fresh qmk_firmware checkout
+* Use the supplied layers and keyboard metadata to build a `keymap.c`
+* Build the firmware
+* Zip a copy of the source
+* Upload the firmware, source zip, and a metadata file to S3.
+* Report the status of the job to RQ
+
+# API Service
+
+The API service is a relatively simple Flask application. There are a few main views you should understand.
+
+## @app.route('/v1/compile', methods=['POST'])
+
+This is the main entrypoint for the API. A client's interaction starts here. The client POST's a JSON document describing their keyboard, and the API does some (very) basic validation of that JSON before submitting the compile job.
+
+## @app.route('/v1/compile/<string:job_id>', methods=['GET'])
+
+This is the most frequently called endpoint. It pulls the job details from redis, if they're still available, or the cached job details on S3 if they're not.
+
+## @app.route('/v1/compile/<string:job_id>/download', methods=['GET'])
+
+This method allows users to download the compiled firmware file.
+
+## @app.route('/v1/compile/<string:job_id>/source', methods=['GET'])
+
+This method allows users to download the source for their firmware.

docs/api_docs.md

@@ -0,0 +1,68 @@
+# QMK API
+
+This page describes using the QMK API. If you are an application developer you can use this API to compile firmware for any [QMK](https://qmk.fm) Keyboard.
+
+## Overview
+
+This service is an asynchronous API for compiling custom keymaps. You POST some JSON to the API, periodically check the status, and when your firmware has finished compiling you can download the resulting firmware and (if desired) source code for that firmware.
+
+#### Example JSON Payload:
+
+```json
+{
+  "keyboard": "clueboard/66/rev2",
+  "keymap": "my_awesome_keymap",
+  "layout": "LAYOUT_all",
+  "layers": [
+    ["KC_GRV","KC_1","KC_2","KC_3","KC_4","KC_5","KC_6","KC_7","KC_8","KC_9","KC_0","KC_MINS","KC_EQL","KC_GRV","KC_BSPC","KC_PGUP","KC_TAB","KC_Q","KC_W","KC_E","KC_R","KC_T","KC_Y","KC_U","KC_I","KC_O","KC_P","KC_LBRC","KC_RBRC","KC_BSLS","KC_PGDN","KC_CAPS","KC_A","KC_S","KC_D","KC_F","KC_G","KC_H","KC_J","KC_K","KC_L","KC_SCLN","KC_QUOT","KC_NUHS","KC_ENT","KC_LSFT","KC_NUBS","KC_Z","KC_X","KC_C","KC_V","KC_B","KC_N","KC_M","KC_COMM","KC_DOT","KC_SLSH","KC_RO","KC_RSFT","KC_UP","KC_LCTL","KC_LGUI","KC_LALT","KC_MHEN","KC_SPC","KC_SPC","KC_HENK","KC_RALT","KC_RCTL","MO(1)","KC_LEFT","KC_DOWN","KC_RIGHT"],
+    ["KC_ESC","KC_F1","KC_F2","KC_F3","KC_F4","KC_F5","KC_F6","KC_F7","KC_F8","KC_F9","KC_F10","KC_F11","KC_F12","KC_TRNS","KC_DEL","BL_STEP","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","_______","KC_TRNS","KC_PSCR","KC_SLCK","KC_PAUS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(2)","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_PGUP","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(1)","KC_LEFT","KC_PGDN","KC_RGHT"],
+    ["KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","RESET","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(2)","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(1)","KC_TRNS","KC_TRNS","KC_TRNS"]
+  ]
+}
+```
+
+As you can see the payload describes all aspects of a keyboard necessary to create and generate a firmware. Each layer is a single list of QMK keycodes the same length as the keyboard's `LAYOUT` macro. If a keyboard supports mulitple `LAYOUT` macros you can specify which macro to use.
+
+## Submitting a Compile Job
+
+To compile your keymap into a firmware simply POST your JSON to the `/v1/compile` endpoint. In the following example we've placed the JSON payload into a file named `json_data`.
+
+```
+$ curl -H "Content-Type: application/json" -X POST -d "$(< json_data)" http://api.qmk.fm/v1/compile
+{
+  "enqueued": true,
+  "job_id": "ea1514b3-bdfc-4a7b-9b5c-08752684f7f6"
+}
+```
+
+## Checking The Status
+
+After submitting your keymap you can check the status using a simple HTTP GET call:
+
+```
+$ curl http://api.qmk.fm/v1/compile/ea1514b3-bdfc-4a7b-9b5c-08752684f7f6
+{
+  "created_at": "Sat, 19 Aug 2017 21:39:12 GMT",
+  "enqueued_at": "Sat, 19 Aug 2017 21:39:12 GMT",
+  "id": "f5f9b992-73b4-479b-8236-df1deb37c163",
+  "status": "running",
+  "result": null
+}
+```
+
+This shows us that the job has made it through the queue and is currently running. There are 5 possible statuses:
+
+* **failed**: Something about the compiling service has broken.
+* **finished**: The compilation is complete and you should check `result` to see the results.
+* **queued**: The keymap is waiting for a compilation server to become available.
+* **running**: The compilation is in progress and should be complete soon.
+* **unknown**: A serious error has occurred and you should [file a bug](https://github.com/qmk/qmk_compiler/issues).
+
+## Examining Finished Results
+
+Once your compile job has finished you'll check the `result` key. The value of this key is a hash containing several key bits of information:
+
+* `firmware_binary_url`: A list of URLs for the the flashable firmware
+* `firmware_keymap_url`: A list of URLs for the the `keymap.c`
+* `firmware_source_url`: A list of URLs for the full firmware source code
+* `output`: The stdout and stderr for this compile job. Errors will be found here.

docs/api_overview.md

@@ -0,0 +1,15 @@
+# QMK API
+
+The QMK API provides an asynchronous API that Web and GUI tools can use to compile arbitrary keymaps for any keyboard supported by [QMK](http://qmk.fm/). The stock keymap template supports all QMK keycodes that do not require supporting C code. Keyboard maintainers can supply their own custom templates to enable more functionality.
+
+## App Developers
+
+If you are an app developer interested in using this API in your application you should head over to [Using The API](api_docs.md).
+
+## Keyboard Maintainers
+
+If you would like to enhance your keyboard's support in the QMK Compiler API head over to the [Keyboard Support](reference_configurator_support.md) section.
+
+## Backend Developers
+
+If you are interested in working on the API itself you should start by setting up a [Development Environment](api_development_environment.md), then check out [Hacking On The API](api_development_overview.md).

docs/becoming_a_qmk_collaborator.md

@@ -1,9 +0,0 @@
-# Becoming a QMK Collaborator
-
-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/breaking_changes.md

@@ -6,20 +6,21 @@ The breaking change period is when we will merge PR's that change QMK in dangero
 
 ## What has been included in past Breaking Changes?
 
+* [2020 Feb 29](ChangeLog/20200229.md)
 * [2019 Aug 30](ChangeLog/20190830.md)
 
 ## When is the next Breaking Change?
 
-The next Breaking Change is scheduled for February 29, 2020.
+The next Breaking Change is scheduled for May 30, 2020.
 
 ### Important Dates
 
-* [x] 2019 Sep 21 - `future` is created. It will be rebased weekly.
-* [ ] 2020 Feb 1 - `future` closed to new PR's.
-* [ ] 2020 Feb 1 - Call for testers.
-* [ ] 2020 Feb 26 - `master` is locked, no PR's merged.
-* [ ] 2020 Feb 28 - Merge `future` to `master`.
-* [ ] 2020 Feb 29 - `master` is unlocked. PR's can be merged again.
+* [x] 2020 Feb 29 - `future` is created. It will be rebased weekly.
+* [ ] 2020 May 2 - `future` closed to new PR's.
+* [ ] 2020 May 2 - Call for testers.
+* [ ] 2020 May 28 - `master` is locked, no PR's merged.
+* [ ] 2020 May 30 - Merge `future` to `master`.
+* [ ] 2020 May 30 - `master` is unlocked. PR's can be merged again.
 
 ## What changes will be included?
 

docs/breaking_changes_instructions.md

@@ -0,0 +1,42 @@
+# Breaking Changes: My Pull Request Was Flagged
+
+A QMK member may have replied to your pull request stating that your submission is a breaking change. In their judgment, the changes you have proposed have greater implications for either QMK, or its users.
+
+Some things that may cause a pull request to be flagged are:
+
+- **Edits to User Keymaps**
+  A user may submit their keymap to QMK, then some time later open a pull request with further updates, only to find it can't be merged because it was edited in the `qmk/qmk_firmware` repository. As not all users are proficient at using Git or GitHub, the user may find themself unable to fix the issue on their own.
+- **Changes to Expected Behavior**
+  Changes to QMK behavior may cause users to believe their hardware or QMK is broken if they flash new firmware that incorporates changes to existing QMK features, and find themselves without a means to restore the desired behavior.
+- **Changes Requiring User Action**
+  Changes may also require action to be taken by users, such as updating a toolchain or taking some action in Git.
+- **Changes Necessitating Increased Scrutiny**
+  On occasion, a submission may have implications for QMK as a project. This could be copyright/licensing issues, coding conventions, large feature overhauls, "high-risk" changes that need wider testing by our community, or something else entirely.
+- **Changes Requiring Communication to End Users**
+  This includes warnings about future deprecations, outdated practices, and anything else that needs to be communicated but doesn't fit into one of the above categories.
+
+## What Do I Do?
+
+If it is determined that your submission is a breaking change, there are a few things you can do to smooth the process:
+
+### Consider Splitting Up Your PR
+
+If you are contributing core code, and the only reason it needs to go through breaking changes is that you are updating keymaps to match your change, consider whether you can submit your feature in a way that the old keymaps continue to work. Then submit a separate PR that goes through the breaking changes process to remove the old code.
+
+### Contribute a ChangeLog Entry
+
+We require submissions that go through the Breaking Change process to include a changelog entry. The entry should be a short summary of the changes your pull request makes – [each section here started as a changelog](ChangeLog/20190830.md "n.b. This should link to the 2019 Aug 30 Breaking Changes doc  - @noroadsleft").
+
+Your changelog should be located at `docs/ChangeLog/YYYYMMDD/PR####.md`, where `YYYYMMDD` is the date on which QMK's breaking change branch – usually named `future` – will be merged into the `master` branch, and `####` is the number of your pull request.
+
+If your submission requires action on the part of users, your changelog should instruct users what action(s) must be taken, or link to a location that does so.
+
+### Document Your Changes
+
+Understanding the purpose for your submission, and possible implications or actions it will require can make the review process more straightforward. A changelog may suffice for this purpose, but more extensive changes may require a level of detail that is ill-suited for a changelog.
+
+Commenting on your pull request and being responsive to questions, comments, and change requests is much appreciated.
+
+### Ask for Help
+
+Having your submission flagged may have caught you off guard. If you find yourself intimidated or overwhelmed, let us know. Comment on your pull request, or [reach out to the QMK team on Discord](https://discord.gg/Uq7gcHh).

docs/cli.md

@@ -1,45 +1,34 @@
-# QMK CLI
+# QMK CLI :id=qmk-cli
 
-This page describes how to setup and use the QMK CLI.
-
-# Overview
+## Overview :id=overview
 
 The QMK CLI makes building and working with QMK keyboards easier. We have provided a number of commands to simplify and streamline tasks such as obtaining and compiling the QMK firmware, creating keymaps, and more.
 
-* [Global CLI](#global-cli)
-* [Local CLI](#local-cli)
-* [CLI Commands](#cli-commands)
+### Requirements :id=requirements
 
-# Requirements
+QMK requires Python 3.6 or greater. We try to keep the number of requirements small but you will also need to install the packages listed in [`requirements.txt`](https://github.com/qmk/qmk_firmware/blob/master/requirements.txt). These are installed automatically when you install the QMK CLI.
 
-The CLI requires Python 3.5 or greater. We try to keep the number of requirements small but you will also need to install the packages listed in [`requirements.txt`](https://github.com/qmk/qmk_firmware/blob/master/requirements.txt).
-
-# Global CLI
-
-QMK provides an installable CLI that can be used to setup your QMK build environment, work with QMK, and which makes working with multiple copies of `qmk_firmware` easier. We recommend installing and updating this periodically.
-
-## Install Using Homebrew (macOS, some Linux)
+### Install Using Homebrew (macOS, some Linux) :id=install-using-homebrew
 
 If you have installed [Homebrew](https://brew.sh) you can tap and install QMK:
 
 ```
-brew tap qmk/qmk
-brew install qmk
+brew install qmk/qmk/qmk
 export QMK_HOME='~/qmk_firmware' # Optional, set the location for `qmk_firmware`
 qmk setup  # This will clone `qmk/qmk_firmware` and optionally set up your build environment
 ```
 
-## Install Using easy_install or pip
+### Install Using pip :id=install-using-easy_install-or-pip
 
-If your system is not listed above you can install QMK manually. First ensure that you have python 3.5 (or later) installed and have installed pip. Then install QMK with this command:
+If your system is not listed above you can install QMK manually. First ensure that you have Python 3.6 (or later) installed and have installed pip. Then install QMK with this command:
 
 ```
-pip3 install qmk
+python3 -m pip install qmk
 export QMK_HOME='~/qmk_firmware' # Optional, set the location for `qmk_firmware`
 qmk setup  # This will clone `qmk/qmk_firmware` and optionally set up your build environment
 ```
 
-## Packaging For Other Operating Systems
+### Packaging For Other Operating Systems :id=packaging-for-other-operating-systems
 
 We are looking for people to create and maintain a `qmk` package for more operating systems. If you would like to create a package for your OS please follow these guidelines:
 
@@ -47,176 +36,3 @@ We are looking for people to create and maintain a `qmk` package for more operat
     * Document why in a comment when you do deviate
 * Install using a virtualenv
 * Instruct the user to set the environment variable `QMK_HOME` to have the firmware source checked out somewhere other than `~/qmk_firmware`.
-
-# Local CLI
-
-If you do not want to use the global CLI there is a local CLI bundled with `qmk_firmware`. You can find it in `qmk_firmware/bin/qmk`. You can run the `qmk` command from any directory and it will always operate on that copy of `qmk_firmware`.
-
-**Example**:
-
-```
-$ ~/qmk_firmware/bin/qmk hello
-Ψ Hello, World!
-```
-
-## Local CLI Limitations
-
-There are some limitations to the local CLI compared to the global CLI:
-
-* The local CLI does not support `qmk setup` or `qmk clone`
-* The local CLI always operates on the same `qmk_firmware` tree, even if you have multiple repositories cloned.
-* The local CLI does not run in a virtualenv, so it's possible that dependencies will conflict
-
-# CLI Commands
-
-## `qmk cformat`
-
-This command formats C code using clang-format. Run it with no arguments to format all core code, or pass filenames on the command line to run it on specific files.
-
-**Usage**:
-
-```
-qmk cformat [file1] [file2] [...] [fileN]
-```
-
-## `qmk compile`
-
-This command allows you to compile firmware from any directory. You can compile JSON exports from <https://config.qmk.fm> or compile keymaps in the repo.
-
-**Usage for Configurator Exports**:
-
-```
-qmk compile <configuratorExport.json>
-```
-
-**Usage for Keymaps**:
-
-```
-qmk compile -kb <keyboard_name> -km <keymap_name>
-```
-
-## `qmk flash`
-
-This command is similar to `qmk compile`, but can also target a bootloader. The bootloader is optional, and is set to `:flash` by default.
-To specify a different bootloader, use `-bl <bootloader>`. Visit <https://docs.qmk.fm/#/flashing>
-for more details of the available bootloaders.
-
-**Usage for Configurator Exports**:
-
-```
-qmk flash <configuratorExport.json> -bl <bootloader>
-```
-
-**Usage for Keymaps**:
-
-```
-qmk flash -kb <keyboard_name> -km <keymap_name> -bl <bootloader>
-```
-
-**Listing the Bootloaders**
-
-```
-qmk flash -b
-```
-
-## `qmk config`
-
-This command lets you configure the behavior of QMK. For the full `qmk config` documentation see [CLI Configuration](cli_configuration.md).
-
-**Usage**:
-
-```
-qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN]
-```
-
-## `qmk docs`
-
-This command starts a local HTTP server which you can use for browsing or improving the docs. Default port is 8936.
-
-**Usage**:
-
-```
-qmk docs [-p PORT]
-```
-
-## `qmk doctor`
-
-This command examines your environment and alerts you to potential build or flash problems.
-
-**Usage**:
-
-```
-qmk doctor
-```
-
-## `qmk json-keymap`
-
-Creates a keymap.c from a QMK Configurator export.
-
-**Usage**:
-
-```
-qmk json-keymap [-o OUTPUT] filename
-```
-
-## `qmk kle2json`
-
-This command allows you to convert from raw KLE data to QMK Configurator JSON. It accepts either an absolute file path, or a file name in the current directory. By default it will not overwrite `info.json` if it is already present. Use the `-f` or `--force` flag to overwrite.
-
-**Usage**:
-
-```
-qmk kle2json [-f] <filename>
-```
-
-**Examples**:
-
-```
-$ qmk kle2json kle.txt 
-☒ File info.json already exists, use -f or --force to overwrite.
-```
-
-```
-$ qmk kle2json -f kle.txt -f
-Ψ Wrote out to info.json
-```
-
-## `qmk list-keyboards`
-
-This command lists all the keyboards currently defined in `qmk_firmware`
-
-**Usage**:
-
-```
-qmk list-keyboards
-```
-
-## `qmk new-keymap`
-
-This command creates a new keymap based on a keyboard's existing default keymap.
-
-**Usage**:
-
-```
-qmk new-keymap [-kb KEYBOARD] [-km KEYMAP]
-```
-
-## `qmk pyformat`
-
-This command formats python code in `qmk_firmware`.
-
-**Usage**:
-
-```
-qmk pyformat
-```
-
-## `qmk pytest`
-
-This command runs the python test suite. If you make changes to python code you should ensure this runs successfully.
-
-**Usage**:
-
-```
-qmk pytest
-```

docs/cli_commands.md

@@ -0,0 +1,258 @@
+# QMK CLI Commands
+
+# User Commands
+
+## `qmk compile`
+
+This command allows you to compile firmware from any directory. You can compile JSON exports from <https://config.qmk.fm>, compile keymaps in the repo, or compile the keyboard in the current working directory.
+
+**Usage for Configurator Exports**:
+
+```
+qmk compile <configuratorExport.json>
+```
+
+**Usage for Keymaps**:
+
+```
+qmk compile -kb <keyboard_name> -km <keymap_name>
+```
+
+**Usage in Keyboard Directory**:  
+
+Must be in keyboard directory with a default keymap, or in keymap directory for keyboard, or supply one with `--keymap <keymap_name>`
+```
+qmk compile
+```
+
+**Usage for building all keyboards that support a specific keymap**:
+
+```
+qmk compile -kb all -km <keymap_name>
+```
+
+**Example**:
+```
+$ qmk config compile.keymap=default
+$ cd ~/qmk_firmware/keyboards/planck/rev6
+$ qmk compile
+Ψ Compiling keymap with make planck/rev6:default
+...
+```
+or with optional keymap argument
+
+```
+$ cd ~/qmk_firmware/keyboards/clueboard/66/rev4 
+$ qmk compile -km 66_iso
+Ψ Compiling keymap with make clueboard/66/rev4:66_iso
+...
+```
+or in keymap directory
+
+```
+$ cd ~/qmk_firmware/keyboards/gh60/satan/keymaps/colemak
+$ qmk compile
+Ψ Compiling keymap with make make gh60/satan:colemak
+...
+```
+
+**Usage in Layout Directory**:  
+
+Must be under `qmk_firmware/layouts/`, and in a keymap folder.
+```
+qmk compile -kb <keyboard_name>
+```
+
+**Example**:
+```
+$ cd ~/qmk_firmware/layouts/community/60_ansi/mechmerlin-ansi
+$ qmk compile -kb dz60
+Ψ Compiling keymap with make dz60:mechmerlin-ansi
+...
+```
+
+## `qmk flash`
+
+This command is similar to `qmk compile`, but can also target a bootloader. The bootloader is optional, and is set to `:flash` by default.
+To specify a different bootloader, use `-bl <bootloader>`. Visit the [Flashing Firmware](flashing.md) guide for more details of the available bootloaders.
+
+**Usage for Configurator Exports**:
+
+```
+qmk flash <configuratorExport.json> -bl <bootloader>
+```
+
+**Usage for Keymaps**:
+
+```
+qmk flash -kb <keyboard_name> -km <keymap_name> -bl <bootloader>
+```
+
+**Listing the Bootloaders**
+
+```
+qmk flash -b
+```
+
+## `qmk config`
+
+This command lets you configure the behavior of QMK. For the full `qmk config` documentation see [CLI Configuration](cli_configuration.md).
+
+**Usage**:
+
+```
+qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN]
+```
+
+## `qmk doctor`
+
+This command examines your environment and alerts you to potential build or flash problems. It can fix many of them if you want it to.
+
+**Usage**:
+
+```
+qmk doctor [-y] [-n]
+```
+
+**Examples**:
+
+Check your environment for problems and prompt to fix them:
+
+    qmk doctor
+
+Check your environment and automatically fix any problems found:
+
+    qmk doctor -y
+
+Check your environment and report problems only:
+
+    qmk doctor -n
+
+## `qmk json2c`
+
+Creates a keymap.c from a QMK Configurator export.
+
+**Usage**:
+
+```
+qmk json2c [-o OUTPUT] filename
+```
+
+## `qmk list-keyboards`
+
+This command lists all the keyboards currently defined in `qmk_firmware`
+
+**Usage**:
+
+```
+qmk list-keyboards
+```
+
+## `qmk list-keymaps`
+
+This command lists all the keymaps for a specified keyboard (and revision).
+
+**Usage**:
+
+```
+qmk list-keymaps -kb planck/ez
+```
+
+## `qmk new-keymap`
+
+This command creates a new keymap based on a keyboard's existing default keymap.
+
+**Usage**:
+
+```
+qmk new-keymap [-kb KEYBOARD] [-km KEYMAP]
+```
+
+---
+
+# Developer Commands
+
+## `qmk cformat`
+
+This command formats C code using clang-format. 
+
+Run it with no arguments to format all core code that has been changed. Default checks `origin/master` with `git diff`, branch can be changed using `-b <branch_name>`
+
+Run it with `-a` to format all core code, or pass filenames on the command line to run it on specific files.
+
+**Usage for specified files**:
+
+```
+qmk cformat [file1] [file2] [...] [fileN]
+```
+
+**Usage for all core files**:
+
+```
+qmk cformat -a
+```
+
+**Usage for only changed files against origin/master**:
+
+```
+qmk cformat
+```
+
+**Usage for only changed files against branch_name**:
+
+```
+qmk cformat -b branch_name
+```
+
+## `qmk docs`
+
+This command starts a local HTTP server which you can use for browsing or improving the docs. Default port is 8936.
+
+**Usage**:
+
+```
+qmk docs [-p PORT]
+```
+
+## `qmk kle2json`
+
+This command allows you to convert from raw KLE data to QMK Configurator JSON. It accepts either an absolute file path, or a file name in the current directory. By default it will not overwrite `info.json` if it is already present. Use the `-f` or `--force` flag to overwrite.
+
+**Usage**:
+
+```
+qmk kle2json [-f] <filename>
+```
+
+**Examples**:
+
+```
+$ qmk kle2json kle.txt 
+☒ File info.json already exists, use -f or --force to overwrite.
+```
+
+```
+$ qmk kle2json -f kle.txt -f
+Ψ Wrote out to info.json
+```
+
+## `qmk pyformat`
+
+This command formats python code in `qmk_firmware`.
+
+**Usage**:
+
+```
+qmk pyformat
+```
+
+## `qmk pytest`
+
+This command runs the python test suite. If you make changes to python code you should ensure this runs successfully.
+
+**Usage**:
+
+```
+qmk pytest
+```
+

docs/cli_configuration.md

@@ -4,7 +4,7 @@ This document explains how `qmk config` works.
 
 # Introduction
 
-Configuration for QMK CLI is a key/value system. Each key consists of a subcommand and an argument name separated by a period. This allows for a straightforward and direct translation between config keys and the arguments they set.
+Configuration for the QMK CLI is a key/value system. Each key consists of a subcommand and an argument name separated by a period. This allows for a straightforward and direct translation between config keys and the arguments they set.
 
 ## Simple Example
 

docs/cli_development.md

@@ -6,6 +6,18 @@ This document has useful information for developers wishing to write new `qmk` s
 
 The QMK CLI operates using the subcommand pattern made famous by git. The main `qmk` script is simply there to setup the environment and pick the correct entrypoint to run. Each subcommand is a self-contained module with an entrypoint (decorated by `@cli.subcommand()`) that performs some action and returns a shell returncode, or None.
 
+## Developer mode:
+
+If you intend to maintain keyboards and/or contribute to QMK, you can enable the CLI's "Developer" mode:
+
+`qmk config user.developer=True`
+
+This will allow you to see all available subcommands.  
+**Note:** You will have to install additional requirements:  
+```bash
+python3 -m pip install -r requirements-dev.txt
+```
+
 # Subcommands
 
 [MILC](https://github.com/clueboard/milc) is the CLI framework `qmk` uses to handle argument parsing, configuration, logging, and many other features. It lets you focus on writing your tool without wasting your time writing glue code.
@@ -32,7 +44,7 @@ def hello(cli):
 
 First we import the `cli` object from `milc`. This is how we interact with the user and control the script's behavior. We use `@cli.argument()` to define a command line flag, `--name`. This also creates a configuration variable named `hello.name` (and the corresponding `user.name`) which the user can set so they don't have to specify the argument. The `cli.subcommand()` decorator designates this function as a subcommand. The name of the subcommand will be taken from the name of the function.
 
-Once inside our function we find a typical "Hello, World!" program. We use `cli.log` to access the underlying [Logger Object](https://docs.python.org/3.5/library/logging.html#logger-objects), whose behavior is user controllable. We also access the value for name supplied by the user as `cli.config.hello.name`. The value for `cli.config.hello.name` will be determined by looking at the `--name` argument supplied by the user, if not provided it will use the value in the `qmk.ini` config file, and if neither of those is provided it will fall back to the default supplied in the `cli.argument()` decorator.
+Once inside our function we find a typical "Hello, World!" program. We use `cli.log` to access the underlying [Logger Object](https://docs.python.org/3.6/library/logging.html#logger-objects), whose behavior is user controllable. We also access the value for name supplied by the user as `cli.config.hello.name`. The value for `cli.config.hello.name` will be determined by looking at the `--name` argument supplied by the user, if not provided it will use the value in the `qmk.ini` config file, and if neither of those is provided it will fall back to the default supplied in the `cli.argument()` decorator.
 
 # User Interaction
 
@@ -44,13 +56,13 @@ There are two main methods for outputting text in a subcommand- `cli.log` and `c
 
 You can use special tokens to colorize your text, to make it easier to understand the output of your program. See [Colorizing Text](#colorizing-text) below.
 
-Both of these methods support built-in string formatting using python's [printf style string format operations](https://docs.python.org/3.5/library/stdtypes.html#old-string-formatting). You can use tokens such as `%s` and `%d` within your text strings then pass the values as arguments. See our Hello, World program above for an example.
+Both of these methods support built-in string formatting using python's [printf style string format operations](https://docs.python.org/3.6/library/stdtypes.html#old-string-formatting). You can use tokens such as `%s` and `%d` within your text strings then pass the values as arguments. See our Hello, World program above for an example.
 
 You should never use the format operator (`%`) directly, always pass values as arguments.
 
 ### Logging (`cli.log`)
 
-The `cli.log` object gives you access to a [Logger Object](https://docs.python.org/3.5/library/logging.html#logger-objects). We have configured our log output to show the user a nice emoji for each log level (or the log level name if their terminal does not support unicode.) This way the user can tell at a glance which messages are most important when something goes wrong.
+The `cli.log` object gives you access to a [Logger Object](https://docs.python.org/3.6/library/logging.html#logger-objects). We have configured our log output to show the user a nice emoji for each log level (or the log level name if their terminal does not support unicode.) This way the user can tell at a glance which messages are most important when something goes wrong.
 
 The default log level is `INFO`. If the user runs `qmk -v <subcommand>` the default log level will be set to `DEBUG`.
 

docs/coding_conventions_c.md

@@ -20,11 +20,11 @@ Most of our style is pretty easy to pick up on, but right now it's not entirely
 * We accept both forms of preprocessor if's: `#ifdef DEFINED` and `#if defined(DEFINED)`
   * If you are not sure which to prefer use the `#if defined(DEFINED)` form.
   * Do not change existing code from one style to the other, except when moving to a multiple condition `#if`.
-  * Do not put whitespace between `#` and `if`.
-  * When deciding how (or if) to indent directives keep these points in mind:
-    * Readability is more important than consistency.
-    * Follow the file's existing style. If the file is mixed follow the style that makes sense for the section you are modifying.
-    * When choosing to indent you can follow the indention level of the surrounding C code, or preprocessor directives can have their own indent level. Choose the style that best communicates the intent of your code.
+* When deciding how (or if) to indent preprocessor directives, keep these points in mind:
+  * Readability is more important than consistency.
+  * Follow the file's existing style. If the file is mixed, follow the style that makes sense for the section you are modifying.
+  * When indenting, keep the hash at the start of the line and add whitespace between `#` and `if`, starting with 4 spaces after the `#`.
+  * You can follow the indention level of the surrounding C code, or preprocessor directives can have their own indentation levels. Choose the style that best communicates the intent of your code.
 
 Here is an example for easy reference:
 

docs/coding_conventions_python.md

@@ -2,7 +2,7 @@
 
 Most of our style follows PEP8 with some local modifications to make things less nit-picky. 
 
-* We target Python 3.5 for compatability with all supported platforms.
+* We target Python 3.6 for compatability with all supported platforms.
 * We indent using four (4) spaces (soft tabs)
 * We encourage liberal use of comments
   * Think of them as a story describing the feature
@@ -317,7 +317,7 @@ At the time of this writing our tests are not very comprehensive. Looking at the
 
 ## Integration Tests
 
-Integration tests can be found in `lib/python/qmk/tests/test_cli_commands.py`. This is where CLI commands are actually run and their overall behavior is verified. We use [`subprocess`](https://docs.python.org/3.5/library/subprocess.html#module-subprocess) to launch each CLI command and a combination of checking output and returncode to determine if the right thing happened.
+Integration tests can be found in `lib/python/qmk/tests/test_cli_commands.py`. This is where CLI commands are actually run and their overall behavior is verified. We use [`subprocess`](https://docs.python.org/3.6/library/subprocess.html#module-subprocess) to launch each CLI command and a combination of checking output and returncode to determine if the right thing happened.
 
 ## Unit Tests
 

docs/config_options.md

@@ -53,6 +53,8 @@ This is a C header file that is one of the first things included, and will persi
   * pins of the rows, from top to bottom
 * `#define MATRIX_COL_PINS { F1, F0, B0, C7, F4, F5, F6, F7, D4, D6, B4, D7 }`
   * pins of the columns, from left to right
+* `#define MATRIX_IO_DELAY 30`
+  * the delay in microseconds when between changing matrix pin state and reading values
 * `#define UNUSED_PINS { D1, D2, D3, B1, B2, B3 }`
   * pins unused by the keyboard for reference
 * `#define MATRIX_HAS_GHOST`
@@ -78,7 +80,7 @@ This is a C header file that is one of the first things included, and will persi
 * `#define BACKLIGHT_PIN B7`
   * pin of the backlight
 * `#define BACKLIGHT_LEVELS 3`
-  * number of levels your backlight will have (maximum 15 excluding off)
+  * number of levels your backlight will have (maximum 31 excluding off)
 * `#define BACKLIGHT_BREATHING`
   * enables backlight breathing
 * `#define BREATHING_PERIOD 6`
@@ -113,9 +115,9 @@ If you define these options you will disable the associated feature, which can s
 * `#define NO_ACTION_ONESHOT`
   * disable one-shot modifiers
 * `#define NO_ACTION_MACRO`
-  * disable old style macro handling: MACRO() & action_get_macro
+  * disable old-style macro handling using `MACRO()`, `action_get_macro()` _(deprecated)_
 * `#define NO_ACTION_FUNCTION`
-  * disable calling of action_function() from the fn_actions array (deprecated)
+  * disable old-style function handling using `fn_actions`, `action_function()` _(deprecated)_
 
 ## Features That Can Be Enabled
 
@@ -134,20 +136,22 @@ If you define these options you will enable the associated feature, which may in
   * enables handling for per key `TAPPING_TERM` settings
 * `#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
+  * See [Retro Tapping](tap_hold.md#retro-tapping) for details
 * `#define TAPPING_TOGGLE 2`
   * how many taps before triggering the toggle
 * `#define PERMISSIVE_HOLD`
   * makes tap and hold keys trigger the hold if another key is pressed before releasing, even if it hasn't hit the `TAPPING_TERM`
-  * See [Permissive Hold](feature_advanced_keycodes.md#permissive-hold) for details
+  * See [Permissive Hold](tap_hold.md#permissive-hold) for details
+* `#define PERMISSIVE_HOLD_PER_KEY`
+  * enabled handling for per key `PERMISSIVE_HOLD` settings
 * `#define IGNORE_MOD_TAP_INTERRUPT`
   * makes it possible to do rolling combos (zx) with keys that convert to other keys on hold, by enforcing the `TAPPING_TERM` for both keys.
-  * See [Mod tap interrupt](feature_advanced_keycodes.md#ignore-mod-tap-interrupt) for details
+  * See [Ignore Mod Tap Interrupt](tap_hold.md#ignore-mod-tap-interrupt) for details
 * `#define IGNORE_MOD_TAP_INTERRUPT_PER_KEY`
   * enables handling for per key `IGNORE_MOD_TAP_INTERRUPT` settings
 * `#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#tapping-force-hold)
+  * See [Tapping Force Hold](tap_hold.md#tapping-force-hold)
   * Breaks any Tap Toggle functionality (`TT` or the One Shot Tap Toggle)
 * `#define TAPPING_FORCE_HOLD_PER_KEY`
   * enables handling for per key `TAPPING_FORCE_HOLD` settings
@@ -186,6 +190,13 @@ If you define these options you will enable the associated feature, which may in
   * pin the DI on the WS2812 is hooked-up to
 * `#define RGBLIGHT_ANIMATIONS`
   * run RGB animations
+* `#define RGBLIGHT_LAYERS`
+  * Lets you define [lighting layers](feature_rgblight.md?id=lighting-layers) that can be toggled on or off. Great for showing the current keyboard layer or caps lock state.
+* `#define RGBLIGHT_MAX_LAYERS`
+  * Defaults to 8. Can be expanded up to 32 if more [lighting layers](feature_rgblight.md?id=lighting-layers) are needed.
+  * Note: Increasing the maximum will increase the firmware size and slow sync on split keyboards.
+* `#define RGBLIGHT_LAYER_BLINK` 
+  * Adds ability to [blink](feature_rgblight.md?id=lighting-layer-blink) a lighting layer for a specified number of milliseconds (e.g. to acknowledge an action).
 * `#define RGBLED_NUM 12`
   * number of LEDs
 * `#define RGBLIGHT_SPLIT`
@@ -276,9 +287,12 @@ There are a few different ways to set handedness for split keyboards (listed in
   * Default behavior for ARM
   * Required for AVR Teensy
 
-* `#define SPLIT_USB_TIMEOUT 2500`
+* `#define SPLIT_USB_TIMEOUT 2000`
   * Maximum timeout when detecting master/slave when using `SPLIT_USB_DETECT`
 
+* `#define SPLIT_USB_TIMEOUT_POLL 10`
+  * Poll frequency when detecting master/slave when using `SPLIT_USB_DETECT`
+
 # 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.
@@ -308,10 +322,10 @@ This is a [make](https://www.gnu.org/software/make/manual/make.html) file that i
 * `LAYOUTS`
   * A list of [layouts](feature_layouts.md) this keyboard supports.
 * `LINK_TIME_OPTIMIZATION_ENABLE`
-  * Enables Link Time Optimization (`LTO`) when compiling the keyboard.  This makes the process take longer, but can significantly reduce the compiled size (and since the firmware is small, the added time is not noticeable).  However, this will automatically disable the old Macros and Functions features automatically, as these break when `LTO` is enabled.
-  It does this by automatically defining `NO_ACTION_MACRO` and `NO_ACTION_FUNCTION`
+  * Enables Link Time Optimization (LTO) when compiling the keyboard.  This makes the process take longer, but it can significantly reduce the compiled size (and since the firmware is small, the added time is not noticeable).
+However, this will automatically disable the legacy TMK Macros and Functions features, as these break when LTO is enabled.  It does this by automatically defining `NO_ACTION_MACRO` and `NO_ACTION_FUNCTION`.  (Note: This does not affect QMK [Macros](feature_macros.md) and [Layers](feature_layers.md).)
 * `LTO_ENABLE`
-  * It has the same meaning as LINK_TIME_OPTIMIZATION_ENABLE.  You can use `LTO_ENABLE` instead of `LINK_TIME_OPTIMIZATION_ENABLE`.
+  * Has the same meaning as `LINK_TIME_OPTIMIZATION_ENABLE`.  You can use `LTO_ENABLE` instead of `LINK_TIME_OPTIMIZATION_ENABLE`.
 
 ## AVR MCU Options
 * `MCU = atmega32u4`
@@ -328,7 +342,7 @@ This is a [make](https://www.gnu.org/software/make/manual/make.html) file that i
   * `bootloadHID`
   * `USBasp`
 
-## Feature Options
+## Feature Options :id=feature-options
 
 Use these to enable or disable building certain features. The more you have enabled the bigger your firmware will be, and you run the risk of building a firmware too large for your MCU.
 

docs/configurator_step_by_step.md

@@ -0,0 +1,58 @@
+# QMK Configurator: Step by Step
+
+This page describes the steps for building your firmware in QMK Configurator.
+
+## Step 1: Select Your Keyboard
+
+Click the drop down box and select the keyboard you want to create a keymap for.
+
+?> If your keyboard has several versions, make sure you select the correct one.
+
+I'll say that again because it's important:
+
+!> **MAKE SURE YOU SELECT THE RIGHT VERSION!**
+
+If your keyboard has been advertised to be powered by QMK but is not in the list, chances are a developer hasn't gotten to it yet or we haven't had a chance to merge it in yet. File an issue at [qmk_firmware](https://github.com/qmk/qmk_firmware/issues) requesting to support that particular keyboard, if there is no active [Pull Request](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+is%3Apr+label%3Akeyboard) for it. There are also QMK powered keyboards that are in their manufacturer's own github accounts. Double check for that as well.  <!-- FIXME(skullydazed): This feels too wordy and I'm not sure we want to encourage these kinds of issues. Also, should we prompt them to bug the manufacutrer? -->
+
+## Step 2: Select Your Keyboard Layout
+
+Choose the layout that best represents the keymap you want to create. Some keyboards do not have enough layouts or correct layouts defined yet. They will be supported in the future.
+
+!> Sometimes there isn't a layout that supports your exact build. In that case select `LAYOUT_all`.
+
+## Step 3: Name Your Keymap
+
+Call this keymap what you want.
+
+?> If you are running into issues when compiling, it may be worth changing this name, as it may already exist in the QMK Firmware repo.
+
+## Step 4: Define Your Keymap
+
+Keycode Entry is accomplished in one of 3 ways:
+
+1. Drag and drop
+2. Clicking on an empty spot on the layout, then clicking the keycode you desire
+3. Clicking on an empty spot on the layout, then pressing the physical key on your keyboard
+
+?> Hover your mouse over a key and a short blurb will tell you what that keycode does. For a more verbose description please see:
+
+* [Basic Keycode Reference](keycodes_basic.md)
+* [Advanced Keycode Reference](feature_advanced_keycodes.md)
+
+!> If your selected layout doesn't match your physical build leave the unused keys blank. If you're not sure which key is in use, for example you have a one backspace key but `LAYOUT_all` has 2 keys, put the same keycode in both locations.
+
+## Step 5: Save Your Keymap for Future Changes
+
+When you're satisfied with your keymap or just want to work on it later, press the `Export Keymap` button. It will save your keymap to your computer. You can then load this .json file in the future by pressing the `Import Keymap` button.
+
+!> **CAUTION:** This is not the same type of .json file used for kbfirmware.com or any other tool. If you try to use this for those tools, or the .json from those tools with QMK Configurator, you will encounter problems.
+
+## Step 6: Compile Your Firmware File
+
+Press the green `Compile` button.
+
+When the compilation is done, you will be able to press the green `Download Firmware` button.
+
+## Next steps: Flashing Your Keyboard
+
+Please refer to [Flashing Firmware](newbs_flashing.md).

docs/configurator_troubleshooting.md

@@ -0,0 +1,26 @@
+# Configurator Troubleshooting
+
+## My .json file is not working
+
+If the .json file was generated with QMK Configurator, congratulations you have stumbled upon a bug. File an issue at [qmk_configurator](https://github.com/qmk/qmk_configurator/issues).
+
+If not... how did you miss the big bold message at the top saying not to use other .json files?
+
+## There are extra spaces in my layout? What do I do?
+
+If you're referring to having three spots for space bar, the best course of action is to just fill them all with Space. The same can be done for Backspace and Shift keys.
+
+## What is the keycode for...
+
+Please see:
+
+* [Basic Keycode Reference](keycodes_basic.md)
+* [Advanced Keycode Reference](feature_advanced_keycodes.md)
+
+## It won't compile
+
+Please double check the other layers of your keymap to make sure there are no random keys present.
+
+## Problems and Bugs
+
+We are always accepting customer requests and bug reports. Please file them at [qmk_configurator](https://github.com/qmk/qmk_configurator/issues).

docs/contributing.md

@@ -101,7 +101,7 @@ enum my_keycodes {
 };
 ```
 
-### Previewing the Documentation
+### Previewing the Documentation :id=previewing-the-documentation
 
 Before opening a pull request, you can preview your changes if you have set up the development environment by running this command from the `qmk_firmware/` folder:
 

docs/custom_quantum_functions.md

@@ -4,7 +4,7 @@ For a lot of people a custom keyboard is about more than sending button presses
 
 This page does not assume any special knowledge about QMK, but reading [Understanding QMK](understanding_qmk.md) will help you understand what is going on at a more fundamental level.
 
-## A Word on Core vs Keyboards vs Keymap
+## A Word on Core vs Keyboards vs Keymap :id=a-word-on-core-vs-keyboards-vs-keymap
 
 We have structured QMK as a hierarchy:
 
@@ -34,7 +34,7 @@ enum my_keycodes {
 };
 ```
 
-## Programming the Behavior of Any Keycode
+## Programming the Behavior of Any Keycode :id=programming-the-behavior-of-any-keycode
 
 When you want to override the behavior of an existing key, or define the behavior for a new key, you should use the `process_record_kb()` and `process_record_user()` functions. These are called by QMK during key processing before the actual key event is handled. If these functions return `true` QMK will process the keycodes as usual. That can be handy for extending the functionality of a key rather than replacing it. If these functions return `false` QMK will skip the normal key handling, and it will be up to you to send any key up or down events that are required.
 
@@ -313,7 +313,7 @@ void suspend_wakeup_init_user(void) {
 * 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
+# Layer Change Code :id=layer-change-code
 
 This runs code every time that the layers get changed.  This can be useful for layer indication, or custom layer handling.
 

docs/de/_summary.md

@@ -77,7 +77,7 @@
   * [Macros](de/feature_macros.md)
   * [Mouse Keys](de/feature_mouse_keys.md)
   * [OLED Driver](de/feature_oled_driver.md)
-  * [One Shot Keys](de/feature_advanced_keycodes.md#one-shot-keys)
+  * [One Shot Keys](de/one_shot_keys.md)
   * [Pointing Device](de/feature_pointing_device.md)
   * [PS/2 Mouse](de/feature_ps2_mouse.md)
   * [RGB Lighting](de/feature_rgblight.md)
@@ -98,6 +98,7 @@
   * [ISP Flashing Guide](de/isp_flashing_guide.md)
   * [ARM Debugging Guide](de/arm_debugging.md)
   * [I2C Driver](de/i2c_driver.md)
+  * [SPI Driver](de/spi_driver.md)
   * [GPIO Controls](de/internals_gpio_control.md)
   * [Proton C Conversion](de/proton_c_conversion.md)
 
@@ -108,7 +109,7 @@
 * Andere Themen
   * [Eclipse mit QMK](de/other_eclipse.md)
   * [VSCode mit QMK](de/other_vscode.md)
-  * [Support](de/support.md)
+  * [Support](de/getting_started_getting_help.md)
   * [Übersetzungen](de/translating.md)
 
 * QMK Internals (In Progress)

docs/documentation_templates.md

@@ -2,7 +2,7 @@
 
 This page documents the templates you should use when submitting new Keymaps and Keyboards to QMK.
 
-## Keymap `readme.md` Template
+## Keymap `readme.md` Template :id=keyboard-readmemd-template
 
 Most keymaps have an image depicting the layout. You can use [Keyboard Layout Editor](http://keyboard-layout-editor.com) to create an image. Upload it to [Imgur](http://imgur.com) or another hosting service, please do not include images in your Pull Request.
 

docs/eeprom_driver.md

@@ -0,0 +1,71 @@
+# EEPROM Driver Configuration :id=eeprom-driver-configuration
+
+The EEPROM driver can be swapped out depending on the needs of the keyboard, or whether extra hardware is present.
+
+Driver                             | Description
+-----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+`EEPROM_DRIVER = vendor` (default) | Uses the on-chip driver provided by the chip manufacturer. For AVR, this is provided by avr-libc. This is supported on ARM for a subset of chips -- STM32F3xx, STM32F1xx, and STM32F072xB will be emulated by writing to flash. STM32L0xx and STM32L1xx will use the onboard dedicated true EEPROM. Other chips will generally act as "transient" below.
+`EEPROM_DRIVER = i2c`              | Supports writing to I2C-based 24xx EEPROM chips. See the driver section below.
+`EEPROM_DRIVER = spi`              | Supports writing to SPI-based 25xx EEPROM chips. See the driver section below.
+`EEPROM_DRIVER = transient`        | Fake EEPROM driver -- supports reading/writing to RAM, and will be discarded when power is lost.
+
+## Vendor Driver Configuration :id=vendor-eeprom-driver-configuration
+
+#### STM32 L0/L1 Configuration :id=stm32l0l1-eeprom-driver-configuration
+
+!> Resetting EEPROM using an STM32L0/L1 device takes up to 1 second for every 1kB of internal EEPROM used.
+
+`config.h` override                 | Description                                                                                                              | Default Value
+------------------------------------|--------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------
+`#define STM32_ONBOARD_EEPROM_SIZE` | The size of the EEPROM to use, in bytes. Erase times can be high, so it's configurable here, if not using the default value. | Minimum required to cover base _eeconfig_ data, or `1024` if VIA is enabled.
+
+## I2C Driver Configuration :id=i2c-eeprom-driver-configuration
+
+Currently QMK supports 24xx-series chips over I2C. As such, requires a working i2c_master driver configuration. You can override the driver configuration via your config.h:
+
+`config.h` override                         | Description                                                                         | Default Value
+------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------
+`#define EXTERNAL_EEPROM_I2C_BASE_ADDRESS`  | Base I2C address for the EEPROM -- shifted left by 1 as per i2c_master requirements | 0b10100000
+`#define EXTERNAL_EEPROM_I2C_ADDRESS(addr)` | Calculated I2C address for the EEPROM                                               | `(EXTERNAL_EEPROM_I2C_BASE_ADDRESS)`
+`#define EXTERNAL_EEPROM_BYTE_COUNT`        | Total size of the EEPROM in bytes                                                   | 8192
+`#define EXTERNAL_EEPROM_PAGE_SIZE`         | Page size of the EEPROM in bytes, as specified in the datasheet                     | 32
+`#define EXTERNAL_EEPROM_ADDRESS_SIZE`      | The number of bytes to transmit for the memory location within the EEPROM           | 2
+`#define EXTERNAL_EEPROM_WRITE_TIME`        | Write cycle time of the EEPROM, as specified in the datasheet                       | 5
+
+Default values and extended descriptions can be found in `drivers/eeprom/eeprom_i2c.h`.
+
+Alternatively, there are pre-defined hardware configurations for available chips/modules:
+
+Module           | Equivalent `#define`            | Source
+-----------------|---------------------------------|------------------------------------------
+CAT24C512 EEPROM | `#define EEPROM_I2C_CAT24C512`  | <https://www.sparkfun.com/products/14764>
+RM24C512C EEPROM | `#define EEPROM_I2C_RM24C512C`  | <https://www.sparkfun.com/products/14764>
+24LC128 EEPROM   | `#define EEPROM_I2C_24LC128`    | <https://www.microchip.com/wwwproducts/en/24LC128>
+24LC256 EEPROM   | `#define EEPROM_I2C_24LC256`    | <https://www.sparkfun.com/products/525>
+MB85RC256V FRAM  | `#define EEPROM_I2C_MB85RC256V` | <https://www.adafruit.com/product/1895>
+
+?> If you find that the EEPROM is not cooperating, ensure you've correctly shifted up your EEPROM address by 1. For example, the datasheet might state the address as `0b01010000` -- the correct value of `EXTERNAL_EEPROM_I2C_BASE_ADDRESS` needs to be `0b10100000`.
+
+## SPI Driver Configuration :id=spi-eeprom-driver-configuration
+
+Currently QMK supports 25xx-series chips over SPI. As such, requires a working spi_master driver configuration. You can override the driver configuration via your config.h:
+
+`config.h` override                            | Description                                                                          | Default Value
+-----------------------------------------------|--------------------------------------------------------------------------------------|--------------
+`#define EXTERNAL_EEPROM_SPI_SLAVE_SELECT_PIN` | SPI Slave select pin in order to inform that the EEPROM is currently being addressed | _none_
+`#define EXTERNAL_EEPROM_SPI_CLOCK_DIVISOR`    | Clock divisor used to divide the peripheral clock to derive the SPI frequency        | `64`
+`#define EXTERNAL_EEPROM_BYTE_COUNT`           | Total size of the EEPROM in bytes                                                    | 8192
+`#define EXTERNAL_EEPROM_PAGE_SIZE`            | Page size of the EEPROM in bytes, as specified in the datasheet                      | 32
+`#define EXTERNAL_EEPROM_ADDRESS_SIZE`         | The number of bytes to transmit for the memory location within the EEPROM            | 2
+
+!> There's no way to determine if there is an SPI EEPROM actually responding. Generally, this will result in reads of nothing but zero.
+
+## Transient Driver configuration :id=transient-eeprom-driver-configuration
+
+The only configurable item for the transient EEPROM driver is its size:
+
+`config.h` override             | Description                               | Default Value
+------------------------------- | ----------------------------------------- | -------------
+`#define TRANSIENT_EEPROM_SIZE` | Total size of the EEPROM storage in bytes | 64
+
+Default values and extended descriptions can be found in `drivers/eeprom/eeprom_transient.h`.

docs/es/_summary.md

@@ -77,7 +77,7 @@
   * [Macros](es/feature_macros.md)
   * [Teclas del ratón](es/feature_mouse_keys.md)
   * [Driver OLED](es/feature_oled_driver.md)
-  * [Teclas One Shot](es/feature_advanced_keycodes.md#one-shot-keys)
+  * [Teclas One Shot](es/one_shot_keys.md)
   * [Dispositivo de apuntado](es/feature_pointing_device.md)
   * [Ratón PS/2](es/feature_ps2_mouse.md)
   * [Iluminación RGB](es/feature_rgblight.md)
@@ -98,6 +98,7 @@
   * [Guía de flasheado de ISP](es/isp_flashing_guide.md)
   * [Guía de depuración de ARM](es/arm_debugging.md)
   * [Driver I2C](es/i2c_driver.md)
+  * [Driver SPI](es/spi_driver.md)
   * [Controles GPIO](es/internals_gpio_control.md)
   * [Conversión Proton C](es/proton_c_conversion.md)
 
@@ -108,7 +109,7 @@
 * Otros temas
   * [Usando Eclipse con QMK](es/other_eclipse.md)
   * [Usando VSCode con QMK](es/other_vscode.md)
-  * [Soporte](es/support.md)
+  * [Soporte](es/getting_started_getting_help.md)
   * [Cómo añadir traducciones](es/translating.md)
 
 * QMK Internals (En progreso)

docs/es/becoming_a_qmk_collaborator.md

@@ -1,9 +0,0 @@
-# Llegar a ser un colaborador QMK
-
-Un colaborador QMK es un maker o diseñador de teclados que tiene interés en ayudar a QMK a crecer y mantener sus teclado(s), y alentar a los usuarios y clientes a presentar herramientas, ideas, y keymaps. Siempre procuramos agregar más teclados y colaboradores, pero pedimos que cumplan los siguientes requisitos:
-
-* **Tener un PCB disponible a la venta.** Desafortunadamente, hay demasiada variación y complicaciones con teclados cableados a mano.
-* **Realizar el mantenimiento de tu teclado en QMK.** Este podría requirir un setup inicial para hacer que tu teclado funcione, pero también podría incluir adaptarse a cambios hecho al base de QMK que podrían descomponer o rendir código superfluo.
-* **Aprobar e incorporar pull requests de keymaps para tu teclado.** Nos gusta alentar a los usuarios a contribuir sus keymaps para que otros los vean y los puedan usar para crear sus propios.
-
-Si sientes que cumples los requisitos, ¡mándanos un email a hello@qmk.fm con una introducción y algunos enlaces para tu teclado!

docs/es/newbs_building_firmware_configurator.md

@@ -4,7 +4,7 @@ El [Configurador QMK](https://config.qmk.fm) es un entorno gráfico online que g
 
 ?> **Por favor sigue estos pasos en orden.**
 
-Ve el [Video tutorial](https://youtu.be/tx54jkRC9ZY)
+Ve el [Video tutorial](https://www.youtube.com/watch?v=-imgglzDMdY)
 
 El Configurador QMK functiona mejor con Chrome/Firefox. 
 

docs/faq.md

@@ -1,6 +0,0 @@
-# Frequently Asked Questions
-
-* [General](faq_general.md)
-* [Building or Compiling QMK](faq_build.md)
-* [Debugging and Troubleshooting QMK](faq_debug.md)
-* [Keymap](faq_keymap.md)

docs/faq_build.md

@@ -113,26 +113,16 @@ OPT_DEFS += -DBOOTLOADER_SIZE=2048
 ```
 
 ## `avr-gcc: internal compiler error: Abort trap: 6 (program cc1)` on MacOS
+
 This is an issue with updating on brew, causing symlinks that avr-gcc depend on getting mangled.
 
 The solution is to remove and reinstall all affected modules.
 
 ```
-brew rm avr-gcc
-brew rm avr-gcc@8
-brew rm dfu-programmer
-brew rm dfu-util
-brew rm gcc-arm-none-eabi
-brew rm arm-gcc-bin@8
-brew rm avrdude
-brew install avr-gcc@8
-brew install dfu-programmer
-brew install dfu-util
-brew install arm-gcc-bin@8
-brew install avrdude
+brew rm avr-gcc avr-gcc@8 dfu-programmer dfu-util gcc-arm-none-eabi arm-gcc-bin@8 avrdude qmk
+brew install qmk/qmk/qmk
 brew link --force avr-gcc@8
 brew link --force arm-gcc-bin@8
-
 ```
 
 ### `avr-gcc` and LUFA

docs/faq_debug.md

@@ -160,10 +160,3 @@ As of now root of its cause is not clear but some build options seem to be relat
 
 https://github.com/tmk/tmk_keyboard/issues/266
 https://geekhack.org/index.php?topic=41989.msg1967778#msg1967778
-
-
-
-## FLIP Doesn't Work
-### `AtLibUsbDfu.dll` Not Found
-Remove current driver and reinstall one FLIP provides from DeviceManager.
-http://imgur.com/a/bnwzy

docs/faq_general.md

@@ -4,6 +4,44 @@
 
 [QMK](https://github.com/qmk), short for Quantum Mechanical Keyboard, is a group of people building tools for custom keyboards. We started with the [QMK firmware](https://github.com/qmk/qmk_firmware), a heavily modified fork of [TMK](https://github.com/tmk/tmk_keyboard).
 
+## I don't know where to start!
+
+If this is the case, then you should start with our [Newbs Guide](newbs.md). There is a lot of great info there, and that should cover everything you need to get started.
+
+If that's an issue, hop onto the [QMK Configurator](https://config.qmk.fm), as that will handle a majority of what you need there.
+
+## How can I flash the firmware I built?
+
+First, head to the [Compiling/Flashing FAQ Page](faq_build.md). There is a good deal of info there, and you'll find a bunch of solutions to common issues there.
+
+## What if I have an issue that isn't covered here?
+
+Okay, that's fine. Then please check the [open issues in our GitHub](https://github.com/qmk/qmk_firmware/issues) to see if somebody is experiencing the same thing (make sure it's not just similar, but actually the same).
+
+If you can't find anything, then please open a [new issue](https://github.com/qmk/qmk_firmware/issues/new)!
+
+## What if I found a bug?
+
+Then please open an [issue](https://github.com/qmk/qmk_firmware/issues/new), and if you know how to fix it, open up a Pull Request on GitHub with the fix.
+
+## But `git` and `GitHub` are intimidating!
+
+Don't worry, we have some pretty nice [Guidelines](newbs_git_best_practices.md) on how to start using `git` and GitHub to make things easier to develop.
+
+Additionally, you can find additional `git` and GitHub related links [here](newbs_learn_more_resources.md).
+
+## I have a Keyboard that I want to add support for
+
+Awesome! Open up a Pull Request for it. We'll review the code, and merge it!
+
+### What if I want to do brand it with `QMK`?
+
+That's amazing! We would love to assist you with that!
+
+In fact, we have a [whole page](https://qmk.fm/powered/) dedicated to adding QMK Branding to your page and keyboard. This covers pretty much everything you need (knowledge and images) to officially support QMK.
+
+If you have any questions about this, open an issue or head to [Discord](https://discord.gg/Uq7gcHh).
+
 ## What Differences Are There Between QMK and TMK?
 
 TMK was originally designed and implemented by [Jun Wako](https://github.com/tmk). QMK started as [Jack Humbert](https://github.com/jackhumbert)'s fork of TMK for the Planck. After a while Jack's fork had diverged quite a bit from TMK, and in 2015 Jack decided to rename his fork to QMK.

docs/faq_keymap.md

@@ -14,6 +14,17 @@ There are 3 standard keyboard layouts in use around the world- ANSI, ISO, and JI
 <!-- Source for this image: http://www.keyboard-layout-editor.com/#/gists/bf431647d1001cff5eff20ae55621e9a -->
 ![Keyboard Layout Image](https://i.imgur.com/5wsh5wM.png)
 
+## How Can I Make Custom Names For Complex Keycodes?
+
+Sometimes, for readability's sake, it's useful to define custom names for some keycodes. People often define custom names using `#define`. For example:
+
+```c
+#define FN_CAPS LT(_FL, KC_CAPSLOCK)
+#define ALT_TAB LALT(KC_TAB)
+```
+
+This will allow you to use `FN_CAPS` and `ALT_TAB` in your keymap, keeping it more readable.
+
 ## Some Of My Keys Are Swapped Or Not Working
 
 QMK has two features, Bootmagic and Command, which allow you to change the behavior of your keyboard on the fly. This includes, but is not limited to, swapping Ctrl/Caps, disabling Gui, swapping Alt/Gui, swapping Backspace/Backslash, disabling all keys, and other behavioral modifications. 

docs/feature_advanced_keycodes.md

@@ -1,62 +1,4 @@
-# Advanced Keycodes
-
-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
-
-People often define custom names using `#define`. For example:
-
-```c
-#define FN_CAPS LT(_FL, KC_CAPSLOCK)
-#define ALT_TAB LALT(KC_TAB)
-```
-
-This will allow you to use `FN_CAPS` and `ALT_TAB` in your keymap, keeping it more readable.
-
-## Caveats
-
-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. If you need to apply modifiers to your tapped keycode, [Tap Dance](feature_tap_dance.md#example-5-using-tap-dance-for-advanced-mod-tap-and-layer-tap-keys) can be used to accomplish this.
-
-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. 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). When using momentary layer switching with MO(), LM(), TT(), or LT(), make sure to leave the key on the above layers transparent or it may not work as intended.
-
-* `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: `MOD_LCTL`, `MOD_LSFT`, `MOD_LALT`, `MOD_LGUI` (note the use of `MOD_` constants instead of `KC_`). These modifiers can be combined using bitwise OR, e.g. `LM(_RAISE, MOD_LCTL | MOD_LALT)`.
-* `LT(layer, kc)` - momentarily activates *layer* when held, and sends *kc* when tapped. Only supports layers 0-15.
-* `OSL(layer)` - momentarily activates *layer* until the next key is pressed. See [One Shot Keys](#one-shot-keys) for details and additional functionality.
-* `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
-
-Care must be taken when switching layers, it's possible to lock yourself into a layer with no way to deactivate that layer (without unplugging your keyboard.) We've created some guidelines to help users avoid the most common problems.
-
-## Beginners
-
-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 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.
-* 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
-
-Sometimes you need more than one base layer. For example, if you want to switch between QWERTY and Dvorak, switch between layouts for different countries, or switch your layout for different videogames. Your base layers should always be the lowest numbered layers. When you have multiple base layers you should always treat them as mutually exclusive. When one base layer is on the others are off.
-
-## Advanced Users
-
-Once you have a good feel for how layers work and what you can do, you can get more creative. The rules listed in the beginner section will help you be successful by avoiding some of the tricker details but they can be constraining, especially for ultra-compact keyboard users. Understanding how layers work will allow you to use them in more advanced ways.
-
-Layers stack on top of each other in numerical order. When determining what a keypress does, QMK scans the layers from the top down, stopping when it reaches the first active layer that is not set to `KC_TRNS`. As a result if you activate a layer that is numerically lower than your current layer, and your current layer (or another layer that is active and higher than your target layer) has something other than `KC_TRNS`, that is the key that will be sent, not the key on the layer you just activated. This is the cause of most people's "why doesn't my layer get switched" problem.
-
-Sometimes, you might want to switch between layers in a macro or as part of a tap dance routine. `layer_on` activates a layer, and `layer_off` deactivates it. More layer-related functions can be found in [action_layer.h](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/action_layer.h).
-
-# Modifier Keys
+# Modifier Keys :id=modifier-keys
 
 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.
 
@@ -64,11 +6,11 @@ These allow you to combine a modifier with a keycode. When pressed, the keydown
 |----------|-------------------------------|----------------------------------------------------|
 |`LCTL(kc)`|`C(kc)`                        |Hold Left Control and press `kc`                    |
 |`LSFT(kc)`|`S(kc)`                        |Hold Left Shift and press `kc`                      |
-|`LALT(kc)`|`A(kc)`                        |Hold Left Alt and press `kc`                        |
+|`LALT(kc)`|`A(kc)`, `LOPT(kc)`            |Hold Left Alt and press `kc`                        |
 |`LGUI(kc)`|`G(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)`|`ALGR(kc)`                     |Hold Right Alt and press `kc`                       |
+|`RALT(kc)`|`ROPT(kc)`, `ALGR(kc)`         |Hold Right Alt and press `kc`                       |
 |`RGUI(kc)`|`RCMD(kc)`, `LWIN(kc)`         |Hold Right GUI 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`            |
@@ -76,291 +18,24 @@ These allow you to combine a modifier with a keycode. When pressed, the keydown
 |`MEH(kc)` |                               |Hold Left Control, Shift and Alt and press `kc`     |
 |`HYPR(kc)`|                               |Hold Left Control, Shift, Alt and GUI and press `kc`|
 
-You can also chain them, for example `LCTL(LALT(KC_DEL))` makes a key that sends Control+Alt+Delete with a single keypress.
+You can also chain them, for example `LCTL(LALT(KC_DEL))` or `C(A(KC_DEL))` makes a key that sends Control+Alt+Delete with a single keypress.
 
-# Mod-Tap
+# Legacy Content :id=legacy-content
 
-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.
+This page used to encompass a large set of features. We have moved many sections that used to be part of this page to their own pages. Everything below this point is simply a redirect so that people following old links on the web find what they're looking for.
 
-The modifiers this keycode and `OSM()` accept are prefixed with `MOD_`, not `KC_`:
+## Layers :id=switching-and-toggling-layers
 
-|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 (AltGr)                       |
-|`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)      |
+* [Layers](feature_layers.md)
 
-You can combine these by ORing them together like so:
+## Mod-Tap :id=mod-tap
 
-```c
-MT(MOD_LCTL | MOD_LSFT, KC_ESC)
-```
+* [Mod-Tap](mod_tap.md)
 
-This key would activate Left Control and Left Shift when held, and send Escape when tapped.
+## One Shot Keys :id=one-shot-keys
 
-For convenience, QMK includes some Mod-Tap shortcuts to make common combinations more compact in your keymap:
+* [One Shot Keys](one_shot_keys.md)
 
-|Key         |Aliases                                                          |Description                                            |
-|------------|-----------------------------------------------------------------|-------------------------------------------------------|
-|`LCTL_T(kc)`|`CTL_T(kc)`                                                      |Left Control when held, `kc` when tapped               |
-|`LSFT_T(kc)`|`SFT_T(kc)`                                                      |Left Shift when held, `kc` when tapped                 |
-|`LALT_T(kc)`|`ALT_T(kc)`                                                      |Left Alt when held, `kc` when tapped                   |
-|`LGUI_T(kc)`|`LCMD_T(kc)`, `LWIN_T(kc)`, `GUI_T(kc)`, `CMD_T(kc)`, `WIN_T(kc)`|Left GUI when held, `kc` when tapped                   |
-|`RCTL_T(kc)`|                                                                 |Right Control when held, `kc` when tapped              |
-|`RSFT_T(kc)`|                                                                 |Right Shift when held, `kc` when tapped                |
-|`RALT_T(kc)`|`ALGR_T(kc)`                                                     |Right Alt when held, `kc` when tapped                  |
-|`RGUI_T(kc)`|`RCMD_T(kc)`, `RWIN_T(kc)`                                       |Right GUI when held, `kc` when tapped                  |
-|`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       |
-|`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 |
-|`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|
-|`HYPR_T(kc)`|`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/)|
+## Tap-Hold Configuration Options :id=tap-hold-configuration-options
 
-## Caveats
-
-Unfortunately, these keycodes cannot be used in Mod-Taps or Layer-Taps, since any modifiers specified in the keycode are ignored.
-
-Additionally, you may run into issues when using Remote Desktop Connection on Windows. Because these codes send shift very fast, Remote Desktop may miss the codes.
-
-To fix this, open Remote Desktop Connection, click on "Show Options", open the the "Local Resources" tab. In the keyboard section, change the drop down to "On this Computer". This will fix the issue, and allow the characters to work correctly.
-
-# One Shot Keys
-
-One shot keys are keys that remain active until the next key is pressed, and then are released. This allows you to type keyboard combinations without pressing more than one key at a time. These keys are usually called "Sticky keys" or "Dead keys".
-
-For example, if you define a key as `OSM(MOD_LSFT)`, you can type a capital A character by first pressing and releasing shift, and then pressing and releasing A. Your computer will see the shift key being held the moment shift is pressed, and it will see the shift key being released immediately after A is released.
-
-One shot keys also work as normal modifiers. If you hold down a one shot key and type other keys, your one shot will be released immediately after you let go of the key.
-
-Additionally, hitting keys five times in a short period will lock that key. This applies for both One Shot Modifiers and One Shot Layers, and is controlled by the `ONESHOT_TAP_TOGGLE` define.
-
-You can control the behavior of one shot keys by defining these in `config.h`:
-
-```c
-#define ONESHOT_TAP_TOGGLE 5  /* Tapping this number of times holds the key until tapped once again. */
-#define ONESHOT_TIMEOUT 5000  /* Time (in ms) before the one shot key is released */
-```
-
-* `OSM(mod)` - Momentarily hold down *mod*. You must use the `MOD_*` keycodes as shown in [Mod Tap](#mod-tap), not the `KC_*` codes.
-* `OSL(layer)` - momentary switch to *layer*.
-
-Sometimes, you want to activate a one-shot key as part of a macro or tap dance routine.  
-
-For one shot layers, you need to call `set_oneshot_layer(LAYER, ONESHOT_START)` on key down, and `clear_oneshot_layer_state(ONESHOT_OTHER_KEY_PRESSED)` on key up. If you want to cancel the oneshot, call `reset_oneshot_layer()`.
-
-For one shot mods, you need to call `set_oneshot_mods(MOD)` to set it, or `clear_oneshot_mods()` to cancel it.
-
-!> If you're having issues with OSM translating over Remote Desktop Connection, this can be fixed by opening the settings, going to the "Local Resources" tap, and in the keyboard section, change the drop down to "On this Computer".  This will fix the issue and allow OSM to function properly over Remote Desktop.
-
-## Callbacks
-
-When you'd like to perform custom logic when pressing a one shot key, there are several callbacks you can choose to implement. You could indicate changes in one shot keys by flashing an LED or making a sound, for example.
-
-There is a callback for `OSM(mod)`. It is called whenever the state of any one shot modifier key is changed: when it toggles on, but also when it is toggled off. You can use it like this:
-
-```c
-void oneshot_mods_changed_user(uint8_t mods) {
-  if (mods & MOD_MASK_SHIFT) {
-    println("Oneshot mods SHIFT");
-  }
-  if (mods & MOD_MASK_CTRL) {
-    println("Oneshot mods CTRL");
-  }
-  if (mods & MOD_MASK_ALT) {
-    println("Oneshot mods ALT");
-  }
-  if (mods & MOD_MASK_GUI) {
-    println("Oneshot mods GUI");
-  }
-  if (!mods) {
-    println("Oneshot mods off");
-  }
-}
-```
-
-The `mods` argument contains the active mods after the change, so it reflects the current state.
-
-When you use One Shot Tap Toggle (by adding `#define ONESHOT_TAP_TOGGLE 2` in your `config.h` file), you may lock a modifier key by pressing it the specified amount of times. There's a callback for that, too:
-
-```c
-void oneshot_locked_mods_changed_user(uint8_t mods) {
-  if (mods & MOD_MASK_SHIFT) {
-    println("Oneshot locked mods SHIFT");
-  }
-  if (mods & MOD_MASK_CTRL) {
-    println("Oneshot locked mods CTRL");
-  }
-  if (mods & MOD_MASK_ALT) {
-    println("Oneshot locked mods ALT");
-  }
-  if (mods & MOD_MASK_GUI) {
-    println("Oneshot locked mods GUI");
-  }
-  if (!mods) {
-    println("Oneshot locked mods off");
-  }
-}
-```
-
-Last, there is also a callback for the `OSL(layer)` one shot key:
-
-```c
-void oneshot_layer_changed_user(uint8_t layer) {
-  if (layer == 1) {
-    println("Oneshot layer 1 on");
-  }
-  if (!layer) {
-    println("Oneshot layer off");
-  }
-}
-```
-
-If any one shot layer is switched off, `layer` will be zero. When you're looking to do something on any layer change instead of one shot layer changes, `layer_state_set_user` is a better callback to use.
-
-If you are making your own keyboard, there are also `_kb` equivalent functions:
-
-```c
-void oneshot_locked_mods_changed_kb(uint8_t mods);
-void oneshot_mods_changed_kb(uint8_t mods);
-void oneshot_layer_changed_kb(uint8_t layer);
-```
-
-As with any callback, be sure to call the `_user` variant to allow for further customizability.
-
-# Tap-Hold Configuration Options
-
-While Tap-Hold options are fantastic, they are not without their issues.  We have tried to configure them with reasonal defaults, but that may still cause issues for some people. 
-
-These options let you modify the behavior of the Tap-Hold keys.
-
-## Permissive Hold
-
-As of [PR#1359](https://github.com/qmk/qmk_firmware/pull/1359/), there is a new `config.h` option:
-
-```c
-#define PERMISSIVE_HOLD
-```
-
-This makes tap and hold keys (like Mod Tap) work better for fast typist, or for high `TAPPING_TERM` settings. 
-
-If you press a Mod Tap key, tap another key (press and release) and then release the Mod Tap key, all within the tapping term, it will output the "tapping" function for both keys.
-
-For Instance:
-
-- `SFT_T(KC_A)` Down
-- `KC_X` Down
-- `KC_X` Up
-- `SFT_T(KC_A)` Up
-
-Normally, if you do all this within the `TAPPING_TERM` (default: 200ms) this will be registered as `ax` by the firmware and host system. With permissive hold enabled, this modifies how this is handled by considering the Mod Tap keys as a Mod if another key is tapped, and would registered as `X` (`SHIFT`+`x`). 
-
-?> If you have `Ignore Mod Tap Interrupt` enabled, as well, this will modify how both work. The regular key has the modifier added if the first key is released first or if both keys are held longer than the `TAPPING_TERM`.
-
-## Ignore Mod Tap Interrupt
-
-To enable this setting, add this to your `config.h`:
-
-```c
-#define IGNORE_MOD_TAP_INTERRUPT
-```
-
-Similar to Permissive Hold, this alters how the firmware processes input for fast typist. If you press a Mod Tap key, press another key, release the Mod Tap key, and then release the normal key, it would normally output the "tapping" function for both keys. This may not be desirable for rolling combo keys. 
-
-Setting `Ignore Mod Tap Interrupt` requires  holding both keys for the `TAPPING_TERM` to trigger the hold function (the mod).
-
-For Instance:
-
-- `SFT_T(KC_A)` Down
-- `KC_X` Down
-- `SFT_T(KC_A)` Up
-- `KC_X` Up
-
-Normally, this would send `X` (`SHIFT`+`x`). With `Ignore Mod Tap Interrupt` enabled, holding both keys are required for the `TAPPING_TERM` to register the hold action. A quick tap will output `ax` in this case, while a hold on both will still output `X`  (`SHIFT`+`x`).
-
-
-?> __Note__: This only concerns modifiers and not layer switching keys.
-
-?> If you have `Permissive Hold` enabled, as well, this will modify how both work. The regular key has the modifier added if the first key is released first or if both keys are held longer than the `TAPPING_TERM`.
-
-For more granular control of this feature, you can add the following to your `config.h`:
-
-```c
-#define IGNORE_MOD_TAP_INTERRUPT_PER_KEY
-```
-
-You can then add the following function to your keymap:
-
-```c
-bool get_ignore_mod_tap_interrupt(uint16_t keycode) {
-  switch (keycode) {
-    case SFT_T(KC_SPC):
-      return true;
-    default:
-      return false;
-  }
-}
-```
-
-## Tapping Force Hold
-
-To enable `tapping force hold`, add the following to your `config.h`: 
-
-```c
-#define TAPPING_FORCE_HOLD
-```
-
-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.  
-
-Example:
-
-- SFT_T(KC_A) Down
-- SFT_T(KC_A) Up
-- SFT_T(KC_A) Down
-- wait more than tapping term...
-- SFT_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).
-
-For more granular control of this feature, you can add the following to your `config.h`:
-
-```c
-#define TAPPING_FORCE_HOLD_PER_KEY
-```
-
-You can then add the following function to your keymap:
-
-```c
-bool get_tapping_force_hold(uint16_t keycode, keyrecord_t *record) {
-  switch (keycode) {
-    case LT(1, KC_BSPC):
-      return true;
-    default:
-      return false;
-  }
-}
-```
-
-## Retro Tapping
-
-To enable `retro tapping`, add the following to your `config.h`: 
-
-```c
-#define RETRO_TAPPING
-```
-
-Holding and releasing a dual function key without pressing another key will result in nothing happening. With retro tapping enabled, releasing the key without pressing another will send the original keycode even if it is outside the tapping term.
-
-For instance, holding and releasing `LT(2, KC_SPACE)` without hitting another key will result in nothing happening. With this enabled, it will send `KC_SPACE` instead.
+* [Tap-Hold Configuration Options](tap_hold.md)

docs/feature_backlight.md

@@ -119,10 +119,22 @@ When both timers are in use for Audio, the backlight PWM will not use a hardware
 
 To change the behavior of the backlighting, `#define` these in your `config.h`:
 
-|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_PINS`     |*Not defined*|experimental: see below for more information                                                                  |
+|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_PINS`     |*Not defined*|experimental: see below for more information                                                                 |
+|`BACKLIGHT_LEVELS`   |`3`          |The number of brightness levels (maximum 31 excluding off)                                                   |
+|`BACKLIGHT_CAPS_LOCK`|*Not defined*|Enable Caps Lock indicator using backlight (for keyboards without dedicated LED)                             |
+|`BACKLIGHT_BREATHING`|*Not defined*|Enable backlight breathing, if supported                                                                     |
+|`BREATHING_PERIOD`   |`6`          |The length of one backlight "breath" in seconds                                                              |
+|`BACKLIGHT_ON_STATE` |`1`          |The state of the backlight pin when the backlight is "on" - `1` for high, `0` for low                        |
+
+### Backlight On State
+
+Most backlight circuits are driven by an N-channel MOSFET or NPN transistor. This means that to turn the transistor *on* and light the LEDs, you must drive the backlight pin, connected to the gate or base, *high*.
+Sometimes, however, a P-channel MOSFET, or a PNP transistor is used. In this case, when the transistor is on, the pin is driven *low* instead.
+
+This functionality is configured at the keyboard level with the `BACKLIGHT_ON_STATE` define.
 
 ### Multiple backlight pins
 
@@ -167,7 +179,7 @@ BACKLIGHT_DRIVER = pwm
 
 Currently only hardware PWM is supported, not timer assisted, and does not provide automatic configuration.
 
-?> STMF072 support is being investigated.
+?> Backlight support for STMF072 has had limited testing, YMMV. If unsure, set `BACKLIGHT_ENABLE = no` in your rules.mk.
 
 ### ARM Configuration
 
@@ -180,7 +192,7 @@ To change the behavior of the backlighting, `#define` these in your `config.h`:
 |`BACKLIGHT_PWM_CHANNEL` |`3`          |The PWM channel to use, see ST datasheets for pin to PWM channel mapping. Unless you are designing your own keyboard, you shouldn't need to change this|
 |`BACKLIGHT_PAL_MODE`    |`2`          |The pin alternative function to use, see ST datasheets for pin AF mapping. Unless you are designing your own keyboard, you shouldn't need to change this|
 
-## Software PWM Driver
+## Software PWM Driver :id=software-pwm-driver
 
 Emulation of PWM while running other keyboard tasks, it offers maximum hardware compatibility without extra platform configuration. The tradeoff is the backlight might jitter when the keyboard is busy. To enable, add this to your rules.mk:
 ```makefile

docs/feature_bootmagic.md

@@ -54,7 +54,7 @@ Hold down the Bootmagic key (Space by default) and the desired hotkey while plug
 |`6`               |Make layer 6 the default layer               |
 |`7`               |Make layer 7 the default layer               |
 
-## Keycodes
+## Keycodes :id=keycodes
 
 |Key                               |Aliases  |Description                                                               |
 |----------------------------------|---------|--------------------------------------------------------------------------|
@@ -121,9 +121,9 @@ If you would like to change the hotkey assignments for Bootmagic, `#define` thes
 |`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                     |
 
-# Bootmagic Lite
+# Bootmagic Lite :id=bootmagic-lite
 
-In addition to the full blown Bootmagic feature, is the Bootmagic Lite feature that only handles jumping into the bootloader.  This is great for boards that don't have a physical reset button but you need a way to jump into the bootloader, and don't want to deal with the headache that Bootmagic can cause.
+In addition to the full blown Bootmagic feature, is the Bootmagic Lite feature that only handles jumping into the bootloader. This is great for boards that don't have a physical reset button but you need a way to jump into the bootloader, and don't want to deal with the headache that Bootmagic can cause.
 
 To enable this version of Bootmagic, you need to enable it in your `rules.mk` with:
 
@@ -131,7 +131,7 @@ To enable this version of Bootmagic, you need to enable it in your `rules.mk` wi
 BOOTMAGIC_ENABLE = lite
 ```
 
-Additionally, you may want to specify which key to use.  This is especially useful for keyboards that have unusual matrices.  To do so, you need to specify the row and column of the key that you want to use. Add these entries to your `config.h` file:
+Additionally, you may want to specify which key to use. This is especially useful for keyboards that have unusual matrices. To do so, you need to specify the row and column of the key that you want to use. Add these entries to your `config.h` file:
 
 ```c
 #define BOOTMAGIC_LITE_ROW 0
@@ -144,9 +144,20 @@ And to trigger the bootloader, you hold this key down when plugging the keyboard
 
 !> Using bootmagic lite will **always reset** the EEPROM, so you will lose any settings that have been saved.
 
+## Split Keyboards
+
+When handedness is predetermined via an option like `SPLIT_HAND_PIN`, you might need to configure a different key between halves. This To do so, add these entries to your `config.h` file:
+
+```c
+#define BOOTMAGIC_LITE_ROW_RIGHT 4
+#define BOOTMAGIC_LITE_COLUMN_RIGHT 1
+```
+
+By default, these values are not set.
+
 ## Advanced Bootmagic Lite
 
-The `bootmagic_lite` function is defined weakly, so that you can replace this in your code, if you need.  A great example of this is the Zeal60 boards that have some additional handling needed.
+The `bootmagic_lite` function is defined weakly, so that you can replace this in your code, if you need. A great example of this is the Zeal60 boards that have some additional handling needed.
 
 To replace the function, all you need to do is add something like this to your code:
 
@@ -163,4 +174,4 @@ void bootmagic_lite(void) {
 }
 ```
 
-You can additional feature here. For instance, resetting the eeprom or requiring additional keys to be pressed to trigger bootmagic.  Keep in mind that `bootmagic_lite` is called before a majority of features are initialized in the firmware.
+You can additional feature here. For instance, resetting the eeprom or requiring additional keys to be pressed to trigger bootmagic. Keep in mind that `bootmagic_lite` is called before a majority of features are initialized in the firmware.

docs/feature_debounce_type.md

@@ -38,5 +38,6 @@ For use in keyboards where refreshing ```NUM_KEYS``` 8-bit counters is computati
 appropriate for the ErgoDox models; the matrix is rotated 90°, and hence its "rows" are really columns, and each finger only hits a single "row" at a time in normal use.
 * eager_pk - debouncing per key. On any state change, response is immediate, followed by ```DEBOUNCE``` milliseconds of no further input for that key
 * sym_g - debouncing per keyboard. On any state change, a global timer is set. When ```DEBOUNCE``` milliseconds of no changes has occured, all input changes are pushed.
+* sym_pk - debouncing per key. On any state change, a per-key timer is set. When ```DEBOUNCE``` milliseconds of no changes have occured on that key, the key status change is pushed.
 
 

docs/feature_encoders.md

@@ -2,23 +2,35 @@
 
 Basic encoders are supported by adding this to your `rules.mk`:
 
-    ENCODER_ENABLE = yes
+```make
+ENCODER_ENABLE = yes
+```
 
 and this to your `config.h`:
 
-    #define ENCODERS_PAD_A { B12 }
-    #define ENCODERS_PAD_B { B13 }
+```c
+#define ENCODERS_PAD_A { B12 }
+#define ENCODERS_PAD_B { B13 }
+```
 
 Each PAD_A/B variable defines an array so multiple encoders can be defined, e.g.:
 
-    #define ENCODERS_PAD_A { encoder1a, encoder2a }
-    #define ENCODERS_PAD_B { encoder1b, encoder2b }
+```c
+#define ENCODERS_PAD_A { encoder1a, encoder2a }
+#define ENCODERS_PAD_B { encoder1b, encoder2b }
+```
 
-If your encoder's clockwise directions are incorrect, you can swap the A & B pad definitions.
+If your encoder's clockwise directions are incorrect, you can swap the A & B pad definitions.  They can also be flipped with a define:
+
+```c
+#define ENCODER_DIRECTION_FLIP
+```
 
 Additionally, the resolution can be specified in the same file (the default & suggested is 4):
 
-    #define ENCODER_RESOLUTION 4
+```c
+#define ENCODER_RESOLUTION 4
+```
 
 ## Split Keyboards
 
@@ -33,27 +45,31 @@ If you are using different pinouts for the encoders on each half of a split keyb
 
 The callback functions can be inserted into your `<keyboard>.c`:
 
-    void encoder_update_kb(uint8_t index, bool clockwise) {
-        encoder_update_user(index, clockwise);
-    }
+```c
+void encoder_update_kb(uint8_t index, bool clockwise) {
+    encoder_update_user(index, clockwise);
+}
+```
 
 or `keymap.c`:
 
-    void encoder_update_user(uint8_t index, bool clockwise) {
-      if (index == 0) { /* First encoder */
+```c
+void encoder_update_user(uint8_t index, bool clockwise) {
+    if (index == 0) { /* First encoder */
         if (clockwise) {
-          tap_code(KC_PGDN);
+            tap_code(KC_PGDN);
         } else {
-          tap_code(KC_PGUP);
+            tap_code(KC_PGUP);
         }
-      } else if (index == 1) { /* Second encoder */  
+    } else if (index == 1) { /* Second encoder */
         if (clockwise) {
-          tap_code(KC_UP);
+            tap_code(KC_DOWN);
         } else {
-          tap_code(KC_DOWN);
+            tap_code(KC_UP);
         }
-      }
     }
+}
+```
 
 ## Hardware
 

docs/feature_hd44780.md

@@ -1,6 +1,6 @@
 # HD44780 LCD Displays
 
-This is an integration of Peter Fleury's LCD library. This page will explain the basics. [For in depth documentation visit his page.](http://homepage.hispeed.ch/peterfleury/doxygen/avr-gcc-libraries/group__pfleury__lcd.html)
+This is an integration of Peter Fleury's LCD library. This page will explain the basics. [For in depth documentation visit his page.](http://www.peterfleury.epizy.com/doxygen/avr-gcc-libraries/group__pfleury__lcd.html)
 
 You can enable support for HD44780 Displays by setting the `HD44780_ENABLE` flag in your keyboards `rules.mk` to yes.
 
@@ -50,8 +50,8 @@ LCD_DISP_ON_CURSOR_BLINK : display on, cursor on flashing
 ````
 This is best done in your keyboards `matrix_init_kb` or your keymaps `matrix_init_user`.  
 It is advised to clear the display before use.  
-To do so call `lcd_clrsrc()`.
+To do so call `lcd_clrscr()`.
 
 To now print something to your Display you first call `lcd_gotoxy(column, line)`. To go to the start of the first line you would call `lcd_gotoxy(0, 0)` and then print a string with `lcd_puts("example string")`.
 
-There are more methods available to control the display. [For in depth documentation please visit the linked page.](http://homepage.hispeed.ch/peterfleury/doxygen/avr-gcc-libraries/group__pfleury__lcd.html)
+There are more methods available to control the display. [For in depth documentation please visit the linked page.](http://www.peterfleury.epizy.com/doxygen/avr-gcc-libraries/group__pfleury__lcd.html)

docs/feature_key_lock.md

@@ -16,7 +16,7 @@ First, enable Key Lock by setting `KEY_LOCK_ENABLE = yes` in your `rules.mk`. Th
 
 ## Caveats
 
-Key Lock is only able to hold standard action keys and [One Shot modifier](feature_advanced_keycodes.md#one-shot-keys) keys (for example, if you have your Shift defined as `OSM(KC_LSFT)`).
+Key Lock is only able to hold standard action keys and [One Shot modifier](one_shot_keys.md) keys (for example, if you have your Shift defined as `OSM(KC_LSFT)`).
 This does not include any of the QMK special functions (except One Shot modifiers), or shifted versions of keys such as `KC_LPRN`. If it's in the [Basic Keycodes](keycodes_basic.md) list, it can be held.
 
 Switching layers will not cancel the Key Lock.

docs/feature_layers.md

@@ -0,0 +1,94 @@
+# Layers :id=layers
+
+One of the most powerful and well used features of QMK Firmware is the ability to use layers.  For most people, this amounts to a function key that allows for different keys, much like what you would see on a laptop or tablet keyboard. 
+
+For a detailed explanation of how the layer stack works, checkout [Keymap Overview](keymap.md#keymap-and-layers).
+
+## Switching and Toggling Layers :id=switching-and-toggling-layers
+
+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. When using momentary layer switching with MO(), LM(), TT(), or LT(), make sure to leave the key on the above layers transparent or it may not work as intended.
+
+* `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: `MOD_LCTL`, `MOD_LSFT`, `MOD_LALT`, `MOD_LGUI` (note the use of `MOD_` constants instead of `KC_`). These modifiers can be combined using bitwise OR, e.g. `LM(_RAISE, MOD_LCTL | MOD_LALT)`.
+* `LT(layer, kc)` - momentarily activates *layer* when held, and sends *kc* when tapped. Only supports layers 0-15.
+* `OSL(layer)` - momentarily activates *layer* until the next key is pressed. See [One Shot Keys](one_shot_keys.md) for details and additional functionality.
+* `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.
+
+### Caveats :id=caveats
+
+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`. Specifically, dual function keys like `LT` and `MT` use a 16 bit keycode. 4 bits are used for the function identifier, the next 12 are divided into the parameters. Layer Tap uses 4 bits for the layer (and is why it's limited to layers 0-16, actually), while Mod Tap does the same, 4 bits for the identifier, 4 bits for which mods are used, and all of them use 8 bits for the keycode. Because of this, the keycode used is limited to `0xFF` (0-255), which are the basic keycodes only. 
+
+Expanding this would be complicated, at best. Moving to a 32-bit keycode would solve a lot of this, but would double the amount of space that the keymap matrix uses. And it could potentially cause issues, too. If you need to apply modifiers to your tapped keycode, [Tap Dance](feature_tap_dance.md#example-5-using-tap-dance-for-advanced-mod-tap-and-layer-tap-keys) can be used to accomplish this.
+
+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.
+
+## Working with Layers :id=working-with-layers
+
+Care must be taken when switching layers, it's possible to lock yourself into a layer with no way to deactivate that layer (without unplugging your keyboard.) We've created some guidelines to help users avoid the most common problems.
+
+### Beginners :id=beginners
+
+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 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.
+* 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 :id=intermediate-users
+
+Sometimes you need more than one base layer. For example, if you want to switch between QWERTY and Dvorak, switch between layouts for different countries, or switch your layout for different videogames. Your base layers should always be the lowest numbered layers. When you have multiple base layers you should always treat them as mutually exclusive. When one base layer is on the others are off.
+
+### Advanced Users :id=advanced-users
+
+Once you have a good feel for how layers work and what you can do, you can get more creative. The rules listed in the beginner section will help you be successful by avoiding some of the tricker details but they can be constraining, especially for ultra-compact keyboard users. Understanding how layers work will allow you to use them in more advanced ways.
+
+Layers stack on top of each other in numerical order. When determining what a keypress does, QMK scans the layers from the top down, stopping when it reaches the first active layer that is not set to `KC_TRNS`. As a result if you activate a layer that is numerically lower than your current layer, and your current layer (or another layer that is active and higher than your target layer) has something other than `KC_TRNS`, that is the key that will be sent, not the key on the layer you just activated. This is the cause of most people's "why doesn't my layer get switched" problem.
+
+Sometimes, you might want to switch between layers in a macro or as part of a tap dance routine. `layer_on` activates a layer, and `layer_off` deactivates it. More layer-related functions can be found in [action_layer.h](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/action_layer.h).
+
+## Functions :id=functions
+
+There are a number of functions (and variables) related to how you can use or manipulate the layers.
+
+|Function                                      |Description                                                                                              |
+|----------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| `layer_state_set(layer_mask)`                | Directly sets the layer state (recommended, do not use unless you know what you are doing).             |
+| `layer_clear()`                              | Clears all layers (turns them all off).                                                                 |
+| `layer_move(layer)`                          | Turns specified layer on, and all other layers off.                                                     |
+| `layer_on(layer)`                            | Turns specified layer on, leaves all other layers in existing state.                                    |
+| `layer_off(layer)`                           | Turns specified layer off, leaves all other layers in existing state.                                   |
+| `layer_invert(layer)`                        | Interverts/toggles the state of the specified layer                                                     |
+| `layer_or(layer_mask)`                       | Turns on layers based on matching bits between specifed layer and existing layer state.                 |
+| `layer_and(layer_mask)`                      | Turns on layers based on matching enabled bits between specifed layer and existing layer state.         |
+| `layer_xor(layer_mask)`                      | Turns on layers based on non-matching bits between specifed layer and existing layer state.             |
+| `layer_debug(layer_mask)`                    | Prints out the current bit mask and highest active layer to debugger console.                           |
+| `default_layer_set(layer_mask)`              | Directly sets the default layer state (recommended, do not use unless you know what you are doing).     |
+| `default_layer_or(layer_mask)`               | Turns on layers based on matching bits between specifed layer and existing default layer state.         |
+| `default_layer_and(layer_mask)`              | Turns on layers based on matching enabled bits between specifed layer and existing default layer state. |
+| `default_layer_xor(layer_mask)`              | Turns on layers based on non-matching bits between specifed layer and existing default layer state.     |
+| `default_layer_debug(layer_mask)`            | Prints out the current bit mask and highest active default layer to debugger console.                   |
+| [`set_single_persistent_default_layer(layer)`](ref_functions.md#setting-the-persistent-default-layer) | Sets the default layer and writes it to persistent memory (EEPROM).  |
+| [`update_tri_layer(x, y, z)`](ref_functions.md#update_tri_layerx-y-z) | Checks if layers `x` and `y` are both on, and sets `z` based on that (on if both on, otherwise off). |
+| [`update_tri_layer_state(state, x, y, z)`](ref_functions.md#update_tri_layer_statestate-x-y-z) | Does the same as `update_tri_layer(x, y, z)`, but from `layer_state_set_*` functions. |
+
+
+In additional to the functions that you can call, there are a number of callback functions that get called every time the layer changes. This passed the layer state to the function, which can be read or modified.
+
+|Callbacks                                     |Description                                                                                    |
+|-----------------------------------------------------|----------------------------------------------------------------------------------------|
+| `layer_state_set_kb(layer_state_t state)`           | Callback for layer functions, for keyboard.                                            |
+| `layer_state_set_user(layer_state_t state)`         | Callback for layer functions, for users.                                               |
+| `default_layer_state_set_kb(layer_state_t state)`   | Callback for default layer functions, for keyboard. Called on keyboard initialization. |
+| `default_layer_state_set_user(layer_state_t state)` | Callback for default layer functions, for users. Called on keyboard initialization.    |
+
+?> For additional details on how you can use these callbacks, check out the [Layer Change Code](custom_quantum_functions.md#layer-change-code) document.
+
+|Check functions                                                  |Description                                                                   |
+|-------------------------------------------|------------------------------------------------------------------------------|
+| `layer_state_cmp(cmp_layer_state, layer)` | This checks the `cmp_layer_state` to see if the specific `layer` is enabled. This is meant for use with the layer callbacks. |
+| `layer_state_is(layer)`                   | This checks the layer state to see if the specific `layer` is enabled. (calls `layer_state_cmp` for the global layer state). |
+
+!> There is `IS_LAYER_ON(layer)` as well, however the `layer_state_cmp` function has some additional handling to ensure that on layer 0 that it returns the correct value. Otherwise, if you check to see if layer 0 is on, you may get an incorrect value returned. 

docs/feature_leader_key.md

@@ -74,9 +74,9 @@ SEQ_THREE_KEYS(KC_C, KC_C, KC_C) {
 
 ## Strict Key Processing
 
-By default, the Leader Key feature will filter the keycode out of [`Mod-Tap`](feature_advanced_keycodes.md#mod-tap) and [`Layer Tap`](feature_advanced_keycodes.md#switching-and-toggling-layers) functions when checking for the Leader sequences. That means if you're using `LT(3, KC_A)`, it will pick this up as `KC_A` for the sequence, rather than `LT(3, KC_A)`, giving a more expected behavior for newer users.
+By default, the Leader Key feature will filter the keycode out of [`Mod-Tap`](mod_tap.md) and [`Layer Tap`](feature_layers.md#switching-and-toggling-layers) functions when checking for the Leader sequences. That means if you're using `LT(3, KC_A)`, it will pick this up as `KC_A` for the sequence, rather than `LT(3, KC_A)`, giving a more expected behavior for newer users.
 
-While, this may be fine for most, if you want to specify the whole keycode (eg, `LT(3, KC_A)` from the example above) in the sequence, you can enable this by added `#define LEADER_KEY_STRICT_KEY_PROCESSING` to your `config.h` file.  This well then disable the filtering, and you'll need to specify the whole keycode.
+While, this may be fine for most, if you want to specify the whole keycode (eg, `LT(3, KC_A)` from the example above) in the sequence, you can enable this by added `#define LEADER_KEY_STRICT_KEY_PROCESSING` to your `config.h` file.  This will then disable the filtering, and you'll need to specify the whole keycode.
 
 ## Customization 
 

docs/feature_macros.md

@@ -88,6 +88,46 @@ const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
 };
 ```
 
+### Advanced Macros
+
+In addition to the `process_record_user()` function, is the `post_process_record_user()` function. This runs after `process_record` and can be used to do things after a keystroke has been sent.  This is useful if you want to have a key pressed before and released after a normal key, for instance. 
+
+In this example, we modify most normal keypresses so that `F22` is pressed before the keystroke is normally sent, and release it __only after__ it's been released.
+
+```c
+static uint8_t f22_tracker;
+
+bool process_record_user(uint16_t keycode, keyrecord_t *record) {
+  switch (keycode) {
+    case KC_A ... KC_F21: //notice how it skips over F22
+    case KC_F23 ... KC_EXSEL: //exsel is the last one before the modifier keys
+      if (record->event.pressed) {
+        register_code(KC_F22); //this means to send F22 down
+        f22_tracker++;
+        register_code(keycode);
+        return false;
+      }
+      break;
+  }
+  return true;
+}
+
+void post_process_record_user(uint16_t keycode, keyrecord_t *record) {
+  switch (keycode) {
+    case KC_A ... KC_F21: //notice how it skips over F22
+    case KC_F23 ... KC_EXSEL: //exsel is the last one before the modifier keys
+      if (!record->event.pressed) {
+        f22_tracker--;
+        if (!f22_tracker) {
+            unregister_code(KC_F22); //this means to send F22 up
+        }
+      }
+      break;
+  }
+}
+```
+
+
 ### TAP, DOWN and UP
 
 You may want to use keys in your macros that you can't write down, such as `Ctrl` or `Home`.
@@ -107,15 +147,25 @@ Would tap `KC_HOME` - note how the prefix is now `X_`, and not `KC_`. You can al
 
 Which would send "VE" followed by a `KC_HOME` tap, and "LO" (spelling "LOVE" if on a newline).
 
+Delays can be also added to the string:
+
+* `SS_DELAY(msecs)` will delay for the specified number of milliseconds.
+
+For example:
+
+    SEND_STRING("VE" SS_DELAY(1000) SS_TAP(X_HOME) "LO");
+
+Which would send "VE" followed by a 1-second delay, then a `KC_HOME` tap, and "LO" (spelling "LOVE" if on a newline, but delayed in the middle).
+
 There's also a couple of mod shortcuts you can use:
 
 * `SS_LCTL(string)`
 * `SS_LSFT(string)`
-* `SS_LALT(string)`
+* `SS_LALT(string)` or `SS_LOPT(string)`
 * `SS_LGUI(string)`, `SS_LCMD(string)` or `SS_LWIN(string)`
 * `SS_RCTL(string)`
 * `SS_RSFT(string)`
-* `SS_RALT(string)` or `SS_ALGR(string)`
+* `SS_RALT(string)`, `SS_ROPT(string)` or `SS_ALGR(string)`
 * `SS_RGUI(string)`, `SS_RCMD(string)` or `SS_RWIN(string)`
 
 These press the respective modifier, send the supplied string and then release the modifier.
@@ -154,6 +204,8 @@ SEND_STRING(".."SS_TAP(X_END));
 
 There are some functions you may find useful in macro-writing. Keep in mind that while you can write some fairly advanced code within a macro, if your functionality gets too complex you may want to define a custom keycode instead. Macros are meant to be simple.
 
+?> You can also use the functions described in [Useful function](ref_functions.md) for additional functionality. For example `reset_keyboard()` allows you to reset the keyboard as part of a macro.
+
 ### `record->event.pressed`
 
 This is a boolean value that can be tested to see if the switch is being pressed or released. An example of this is
@@ -198,11 +250,11 @@ This will clear all mods currently pressed.
 
 This will clear all keys besides the mods currently pressed.
 
-## Advanced Example: 
+## Advanced Example:
 
 ### Super ALT↯TAB
 
-This macro will register `KC_LALT` and tap `KC_TAB`, then wait for 1000ms. If the key is tapped again, it will send another `KC_TAB`; if there is no tap, `KC_LALT` will be unregistered, thus allowing you to cycle through windows. 
+This macro will register `KC_LALT` and tap `KC_TAB`, then wait for 1000ms. If the key is tapped again, it will send another `KC_TAB`; if there is no tap, `KC_LALT` will be unregistered, thus allowing you to cycle through windows.
 
 ```c
 bool is_alt_tab_active = false;    # ADD this near the begining of keymap.c
@@ -219,7 +271,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
         if (!is_alt_tab_active) {
           is_alt_tab_active = true;
           register_code(KC_LALT);
-        } 
+        }
         alt_tab_timer = timer_read();
         register_code(KC_TAB);
       } else {
@@ -230,7 +282,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
   return true;
 }
 
-void matrix_scan_user(void) {     # The very important timer. 
+void matrix_scan_user(void) {     # The very important timer.
   if (is_alt_tab_active) {
     if (timer_elapsed(alt_tab_timer) > 1000) {
       unregister_code(KC_LALT);
@@ -319,7 +371,7 @@ const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
 ```
 
 
-## Advanced Example: 
+## Advanced Example:
 
 ### Single-Key Copy/Paste
 

docs/feature_mouse_keys.md

@@ -58,6 +58,8 @@ This is the default mode. You can adjust the cursor and scrolling acceleration u
 |`MOUSEKEY_INTERVAL`         |50     |Time between cursor movements                            |
 |`MOUSEKEY_MAX_SPEED`        |10     |Maximum cursor speed at which acceleration stops         |
 |`MOUSEKEY_TIME_TO_MAX`      |20     |Time until maximum cursor speed is reached               |
+|`MOUSEKEY_WHEEL_DELAY`      |300    |Delay between pressing a wheel key and wheel movement    |
+|`MOUSEKEY_WHEEL_INTERVAL`   |100    |Time between wheel movements                             |
 |`MOUSEKEY_WHEEL_MAX_SPEED`  |8      |Maximum number of scroll steps per scroll action         |
 |`MOUSEKEY_WHEEL_TIME_TO_MAX`|40     |Time until maximum scroll speed is reached               |
 
@@ -66,6 +68,7 @@ Tips:
 * Setting `MOUSEKEY_DELAY` too low makes the cursor unresponsive. Setting it too high makes small movements difficult.
 * For smoother cursor movements, lower the value of `MOUSEKEY_INTERVAL`. If the refresh rate of your display is 60Hz, you could set it to `16` (1/60). As this raises the cursor speed significantly, you may want to lower `MOUSEKEY_MAX_SPEED`.
 * Setting `MOUSEKEY_TIME_TO_MAX` or `MOUSEKEY_WHEEL_TIME_TO_MAX` to `0` will disable acceleration for the cursor or scrolling respectively. This way you can make one of them constant while keeping the other accelerated, which is not possible in constant speed mode.
+* Setting `MOUSEKEY_WHEEL_INTERVAL` too low will make scrolling too fast. Setting it too high will make scrolling too slow when the wheel key is held down.
 
 Cursor acceleration uses the same algorithm as the X Window System MouseKeysAccel feature. You can read more about it [on Wikipedia](https://en.wikipedia.org/wiki/Mouse_keys).
 

docs/feature_oled_driver.md

@@ -104,7 +104,7 @@ void oled_task_user(void) {
 |`OLED_DISPLAY_ADDRESS`     |`0x3C`           |The i2c address of the OLED Display                                                                                       |
 |`OLED_FONT_H`              |`"glcdfont.c"`   |The font code file to use for custom fonts                                                                                |
 |`OLED_FONT_START`          |`0`              |The starting characer index for custom fonts                                                                              |
-|`OLED_FONT_END`            |`224`            |The ending characer index for custom fonts                                                                                |
+|`OLED_FONT_END`            |`223`            |The ending characer index for custom fonts                                                                                |
 |`OLED_FONT_WIDTH`          |`6`              |The font width                                                                                                            |
 |`OLED_FONT_HEIGHT`         |`8`              |The font height (untested)                                                                                                |
 |`OLED_TIMEOUT`             |`60000`          |Turns off the OLED screen after 60000ms of keyboard inactivity. Helps reduce OLED Burn-in. Set to 0 to disable.           |
@@ -221,6 +221,12 @@ void oled_write(const char *data, bool invert);
 // Advances the cursor to the next page, wiring ' ' to the remainder of the current page
 void oled_write_ln(const char *data, bool invert);
 
+// Pans the buffer to the right (or left by passing true) by moving contents of the buffer
+// Useful for moving the screen in preparation for new drawing 
+// oled_scroll_left or oled_scroll_right should be preferred for all cases of moving a static
+// image such as a logo or to avoid burn-in as it's much, much less cpu intensive
+void oled_pan(bool left);
+
 // Writes a PROGMEM string to the buffer at current cursor position
 // Advances the cursor while writing, inverts the pixels if true
 // Remapped to call 'void oled_write(const char *data, bool invert);' on ARM
@@ -235,6 +241,9 @@ void oled_write_ln_P(const char *data, bool invert);
 // Writes a string to the buffer at current cursor position
 void oled_write_raw(const char *data, uint16_t size);
 
+// Writes a single byte into the buffer at the specified index
+void oled_write_raw_byte(const char data, uint16_t index);
+
 // Writes a PROGMEM string to the buffer at current cursor position
 void oled_write_raw_P(const char *data, uint16_t size);
 
@@ -252,12 +261,24 @@ void oled_task(void);
 // Called at the start of oled_task, weak function overridable by the user
 void oled_task_user(void);
 
-// Scrolls the entire display right
+// Set the specific 8 lines rows of the screen to scroll.
+// 0 is the default for start, and 7 for end, which is the entire
+// height of the screen.  For 128x32 screens, rows 4-7 are not used.
+void oled_scroll_set_area(uint8_t start_line, uint8_t end_line);
+
+// Sets scroll speed, 0-7, fastest to slowest. Default is three.
+// Does not take effect until scrolling is either started or restarted
+// the ssd1306 supports 8 speeds with the delay
+// listed below betwen each frame of the scrolling effect
+// 0=2, 1=3, 2=4, 3=5, 4=25, 5=64, 6=128, 7=256
+void oled_scroll_set_speed(uint8_t speed);
+
+// Begin scrolling the entire display right
 // Returns true if the screen was scrolling or starts scrolling
 // NOTE: display contents cannot be changed while scrolling
 bool oled_scroll_right(void);
 
-// Scrolls the entire display left
+// Begin scrolling the entire display left
 // Returns true if the screen was scrolling or starts scrolling
 // NOTE: display contents cannot be changed while scrolling
 bool oled_scroll_left(void);

docs/feature_pointing_device.md

@@ -1,10 +1,10 @@
-## Pointing Device
+# Pointing Device :id=pointing-device
 
 Pointing Device is a generic name for a feature intended to be generic: moving the system pointer around.  There are certainly other options for it - like mousekeys - but this aims to be easily modifiable and lightweight.  You can implement custom keys to control functionality, or you can gather information from other peripherals and insert it directly here - let QMK handle the processing for you.
 
 To enable Pointing Device, uncomment the following line in your rules.mk:
 
-```
+```makefile
 POINTING_DEVICE_ENABLE = yes
 ```
 
@@ -25,22 +25,19 @@ When the mouse report is sent, the x, y, v, and h values are set to 0 (this is d
 
 In the following example, a custom key is used to click the mouse and scroll 127 units vertically and horizontally, then undo all of that when released - because that's a totally useful function.  Listen, this is an example:
 
-```
+```c
 case MS_SPECIAL:
-	report_mouse_t currentReport = pointing_device_get_report();
-    if (record->event.pressed)
-    {
+    report_mouse_t currentReport = pointing_device_get_report();
+    if (record->event.pressed) {
         currentReport.v = 127;
-		currentReport.h = 127;
-		currentReport.buttons |= MOUSE_BTN1; //this is defined in report.h
-    }
-    else
-    {
+        currentReport.h = 127;
+        currentReport.buttons |= MOUSE_BTN1;  // this is defined in report.h
+    } else {
         currentReport.v = -127;
         currentReport.h = -127;
         currentReport.buttons &= ~MOUSE_BTN1;
     }
-	pointing_device_set_report(currentReport);
+    pointing_device_set_report(currentReport);
     break;
 ```
 

docs/feature_ps2_mouse.md

@@ -1,4 +1,4 @@
-## PS/2 Mouse Support
+# PS/2 Mouse Support :id=ps2-mouse-support
 
 Its possible to hook up a PS/2 mouse (for example touchpads or trackpoints) to your keyboard as a composite device.
 
@@ -6,7 +6,7 @@ To hook up a Trackpoint, you need to obtain a Trackpoint module (i.e. harvest fr
 
 There are three available modes for hooking up PS/2 devices: USART (best), interrupts (better) or busywait (not recommended).
 
-### The Cirtuitry between Trackpoint and Controller
+## The Circuitry between Trackpoint and Controller :id=the-circuitry-between-trackpoint-and-controller
 
 To get the things working, a 4.7K drag is needed between the two lines DATA and CLK and the line 5+. 
 
@@ -24,20 +24,20 @@ MODULE    5+  --------+--+--------- PWR   CONTROLLER
 ```
 
 
-### Busywait Version
+## Busywait Version :id=busywait-version
 
 Note: This is not recommended, you may encounter jerky movement or unsent inputs. Please use interrupt or USART version if possible.
 
 In rules.mk:
 
-```
+```makefile
 PS2_MOUSE_ENABLE = yes
 PS2_USE_BUSYWAIT = yes
 ```
 
 In your keyboard config.h:
 
-```
+```c
 #ifdef PS2_USE_BUSYWAIT
 #   define PS2_CLOCK_PORT  PORTD
 #   define PS2_CLOCK_PIN   PIND
@@ -50,20 +50,20 @@ In your keyboard config.h:
 #endif
 ```
 
-### Interrupt Version
+## Interrupt Version :id=interrupt-version
 
 The following example uses D2 for clock and D5 for data. You can use any INT or PCINT pin for clock, and any pin for data.
 
 In rules.mk:
 
-```
+```makefile
 PS2_MOUSE_ENABLE = yes
 PS2_USE_INT = yes
 ```
 
 In your keyboard config.h:
 
-```
+```c
 #ifdef PS2_USE_INT
 #define PS2_CLOCK_PORT  PORTD
 #define PS2_CLOCK_PIN   PIND
@@ -88,20 +88,20 @@ In your keyboard config.h:
 #endif
 ```
 
-### USART Version
+## USART Version :id=usart-version
 
 To use USART on the ATMega32u4, you have to use PD5 for clock and PD2 for data. If one of those are unavailable, you need to use interrupt version.
 
 In rules.mk:
 
-```
+```makefile
 PS2_MOUSE_ENABLE = yes
 PS2_USE_USART = yes
 ```
 
 In your keyboard config.h:
 
-```
+```c
 #ifdef PS2_USE_USART
 #define PS2_CLOCK_PORT  PORTD
 #define PS2_CLOCK_PIN   PIND
@@ -145,13 +145,13 @@ In your keyboard config.h:
 #endif
 ```
 
-### Additional Settings
+## Additional Settings :id=additional-settings
 
-#### PS/2 Mouse Features
+### PS/2 Mouse Features :id=ps2-mouse-features
 
 These enable settings supported by the PS/2 mouse protocol.
 
-```
+```c
 /* Use remote mode instead of the default stream mode (see link) */
 #define PS2_MOUSE_USE_REMOTE_MODE
 
@@ -170,7 +170,7 @@ These enable settings supported by the PS/2 mouse protocol.
 
 You can also call the following functions from ps2_mouse.h
 
-```
+```c
 void ps2_mouse_disable_data_reporting(void);
 
 void ps2_mouse_enable_data_reporting(void);
@@ -188,36 +188,36 @@ void ps2_mouse_set_resolution(ps2_mouse_resolution_t resolution);
 void ps2_mouse_set_sample_rate(ps2_mouse_sample_rate_t sample_rate);
 ```
 
-#### Fine Control
+### Fine Control :id=fine-control
 
 Use the following defines to change the sensitivity and speed of the mouse.
 Note: you can also use `ps2_mouse_set_resolution` for the same effect (not supported on most touchpads).
 
-```
+```c
 #define PS2_MOUSE_X_MULTIPLIER 3
 #define PS2_MOUSE_Y_MULTIPLIER 3
 #define PS2_MOUSE_V_MULTIPLIER 1
 ```
 
-#### Scroll Button
+### Scroll Button :id=scroll-button
 
 If you're using a trackpoint, you will likely want to be able to use it for scrolling.
 It's possible to enable a "scroll button/s" that when pressed will cause the mouse to scroll instead of moving.
 To enable the feature, you must set a scroll button mask as follows:
 
-```
+```c
 #define PS2_MOUSE_SCROLL_BTN_MASK (1<<PS2_MOUSE_BUTTON_MIDDLE) /* Default */
 ```
 
 To disable the scroll button feature:
 
-```
+```c
 #define PS2_MOUSE_SCROLL_BTN_MASK 0
 ```
 
 The available buttons are:
 
-```
+```c
 #define PS2_MOUSE_BTN_LEFT      0
 #define PS2_MOUSE_BTN_RIGHT     1
 #define PS2_MOUSE_BTN_MIDDLE    2
@@ -229,27 +229,28 @@ Once you've configured your scroll button mask, you must configure the scroll bu
 This is the interval before which if the scroll buttons were released they would be sent to the host.
 After this interval, they will cause the mouse to scroll and will not be sent.
 
-```
+```c
 #define PS2_MOUSE_SCROLL_BTN_SEND 300 /* Default */
 ```
 
 To disable sending the scroll buttons:
-```
+
+```c
 #define PS2_MOUSE_SCROLL_BTN_SEND 0
 ```
 
 Fine control over the scrolling is supported with the following defines:
 
-```
+```c
 #define PS2_MOUSE_SCROLL_DIVISOR_H 2
 #define PS2_MOUSE_SCROLL_DIVISOR_V 2
 ```
 
-#### Invert Mouse and Scroll Axes
+### Invert Mouse and Scroll Axes :id=invert-mouse-and-scroll-axes
 
 To invert the X and Y axes you can put:
 
-```
+```c
 #define PS2_MOUSE_INVERT_X
 #define PS2_MOUSE_INVERT_Y
 ```
@@ -258,18 +259,37 @@ into config.h.
 
 To reverse the scroll axes you can put:
 
-```
+```c
 #define PS2_MOUSE_INVERT_H
 #define PS2_MOUSE_INVERT_V
 ```
 
 into config.h.
 
-#### Debug Settings
+### Rotate Mouse Axes :id=rotate-mouse-axes
+
+Transform the output of the device with a clockwise rotation of 90, 180, or 270
+degrees.
+
+When compensating for device orientation, rotate the output the same amount in
+the opposite direction.  E.g. if the normal device orientation is considered to
+be North-facing, compensate as follows:
+
+```c
+#define PS2_MOUSE_ROTATE 270 /* Compensate for East-facing device orientation. */
+```
+```c
+#define PS2_MOUSE_ROTATE 180 /* Compensate for South-facing device orientation. */
+```
+```c
+#define PS2_MOUSE_ROTATE 90 /* Compensate for West-facing device orientation. */
+```
+
+### Debug Settings :id=debug-settings
 
 To debug the mouse, add `debug_mouse = true` or enable via bootmagic.
 
-```
+```c
 /* To debug the mouse reports */
 #define PS2_MOUSE_DEBUG_HID
 #define PS2_MOUSE_DEBUG_RAW

docs/feature_rawhid.md

@@ -0,0 +1,69 @@
+# Raw HID
+
+Raw HID allows for bidirectional communication between QMK and the host computer over an HID interface. This has many potential use cases, such as switching keymaps on the fly or changing RGB LED colors and modes.
+
+There are two main components to getting raw HID working with your keyboard.
+
+## Keyboard firmware
+
+The implementation is fairly straightforward for the firmware.
+In your `rules.mk` add:
+
+```make
+RAW_ENABLE = yes
+```
+
+In your `keymap.c` include `"raw_hid.h"` and implement the following:
+
+```C
+void raw_hid_receive(uint8_t *data, uint8_t length) {
+    // Your code goes here. data is the packet received from host.
+}
+```
+
+The `"raw_hid.h"` header also declares `void raw_hid_send(uint8_t *data, uint8_t length);` which allows sending packets from keyboard to host. As an example, it can also be used for debugging when building your host application by returning all data back to the host.
+
+```C
+void raw_hid_receive(uint8_t *data, uint8_t length) {
+    raw_hid_send(data, length);
+}
+```
+
+`raw_hid_receive` can receive variable size packets from host with maximum length `RAW_EPSIZE`. `raw_hid_send` on the other hand can send packets to host of exactly `RAW_EPSIZE` length, therefore it should be used with data of length `RAW_EPSIZE`.
+
+Make sure to flash raw enabled firmware before proceeding with working on the host side.
+
+## Host (Windows/macOS/Linux)
+
+This is the more complicated part as it will require some digging.
+
+To connect your host computer to your keyboard with raw HID you need four pieces of information about your keyboard:
+
+1. Vendor ID
+2. Product ID
+3. Usage Page
+4. Usage
+
+The first two can easily be found in your keyboard's `config.h` in the keyboard's main directory under `VENDOR_ID` and `PRODUCT_ID`.
+
+The final two can be overridden in your keyboard's `config.h` in the keyboard's main directory by redefining the values: `#define RAW_USAGE_PAGE 0xFF60` and `#define RAW_USAGE_ID 0x61`.
+
+By default, **Usage Page** is `0xFF60` and **Usage** is `0x61`.
+
+### Building your host
+
+You can build your host using any language that has an available HID implementation library if you don't wish to make your own. The ones we know of for popular languages are:
+
+* Node: [node-hid](https://github.com/node-hid/node-hid).
+* C: [hidapi](https://github.com/libusb/hidapi).
+* Java: [purejavahidapi](https://github.com/nyholku/purejavahidapi) and [hid4java](https://github.com/gary-rowe/hid4java).
+* Python: [pyhidapi](https://pypi.org/project/hid/).
+
+This is not an exhaustive cross-platform list but should get you started. There are no special requirements for using raw HID so any HID library should work.
+
+Now that you have all four pieces of information required to open HID interface to your keyboard. All you need to do is use your library's available functions to open the device with its ID parameters.
+
+Note that Vendor ID and Product ID are not actually required to open the device. They are used only to filter to a specific device out of the many HID devices you have plugged in. Many libraries will give you the option to open the device using Product Name or Manufacturer Name instead, `node-hid` being a prime example. This will create issues for devices with builtin USB Hub or any extra HID interfaces where you will have multiple interfaces with the same name or from the same manufacturer. The Vendor ID together with Product ID create a unique designation to a single interface and will not exhibit this problem. Therefore, even if your library doesn't require you to, it is best to use them to avoid issues.
+Unlike Vendor ID and Product ID though, Usage Page and Usage are necessary for successful communication.
+
+It should go without saying that regardless of the library you're using, you should always make sure to close the interface when finished. Depending on the operating system and your particular environment there may be issues connecting to it again afterwards with another client or another instance of the same client if it's not explicitly closed.

docs/feature_rgb_matrix.md

@@ -1,22 +1,22 @@
-# RGB Matrix Lighting
+# RGB Matrix Lighting :id=rgb-matrix-lighting
 
 This feature allows you to use RGB LED matrices driven by external drivers. It hooks into the RGBLIGHT system so you can use the same keycodes as RGBLIGHT to control it.
 
 If you want to use single color LED's you should use the [LED Matrix Subsystem](feature_led_matrix.md) instead.
 
-## Driver configuration
+## Driver configuration :id=driver-configuration
 ---
-### IS31FL3731
+### IS31FL3731 :id=is31fl3731
 
 There is basic support for addressable RGB matrix lighting with the I2C IS31FL3731 RGB controller. To enable it, add this to your `rules.mk`:
 
-```C
+```makefile
 RGB_MATRIX_ENABLE = IS31FL3731
 ```
 
 Configure the hardware via your `config.h`:
 
-```C
+```c
 // This is a 7-bit address, that gets left-shifted and bit 0
 // set to 0 for write, 1 for read (as per I2C protocol)
 // The address will vary depending on your wiring:
@@ -39,7 +39,7 @@ Currently only 2 drivers are supported, but it would be trivial to support all 4
 
 Define these arrays listing all the LEDs in your `<keyboard>.c`:
 
-```C
+```c
 const is31_led g_is31_leds[DRIVER_LED_TOTAL] = {
 /* Refer to IS31 manual for these locations
  *   driver
@@ -55,19 +55,19 @@ const is31_led g_is31_leds[DRIVER_LED_TOTAL] = {
 Where `Cx_y` is the location of the LED in the matrix defined by [the datasheet](http://www.issi.com/WW/pdf/31FL3731.pdf) and the header file `drivers/issi/is31fl3731.h`. The `driver` is the index of the driver you defined in your `config.h` (`0` or `1` right now).
 
 ---
-###  IS31FL3733/IS31FL3737
+### IS31FL3733/IS31FL3737 :id=is31fl3733is31fl3737
 
 !> For the IS31FL3737, replace all instances of `IS31FL3733` below with `IS31FL3737`.
 
 There is basic support for addressable RGB matrix lighting with the I2C IS31FL3733 RGB controller. To enable it, add this to your `rules.mk`:
 
-```C
+```makefile
 RGB_MATRIX_ENABLE = IS31FL3733
 ```
 
 Configure the hardware via your `config.h`:
 
-```C
+```c
 // This is a 7-bit address, that gets left-shifted and bit 0
 // set to 0 for write, 1 for read (as per I2C protocol)
 // The address will vary depending on your wiring:
@@ -90,7 +90,7 @@ Currently only a single drivers is supported, but it would be trivial to support
 
 Define these arrays listing all the LEDs in your `<keyboard>.c`:
 
-```C
+```c
 const is31_led g_is31_leds[DRIVER_LED_TOTAL] = {
 /* Refer to IS31 manual for these locations
  *   driver
@@ -107,17 +107,17 @@ Where `X_Y` is the location of the LED in the matrix defined by [the datasheet](
 
 ---
 
-### WS2812
+### WS2812 :id=ws2812
 
 There is basic support for addressable RGB matrix lighting with a WS2811/WS2812{a,b,c} addressable LED strand. To enable it, add this to your `rules.mk`:
 
-```C
+```makefile
 RGB_MATRIX_ENABLE = WS2812
 ```
 
 Configure the hardware via your `config.h`:
 
-```C
+```c
 // The pin connected to the data pin of the LEDs
 #define RGB_DI_PIN D7
 // The number of LEDs connected
@@ -128,7 +128,7 @@ Configure the hardware via your `config.h`:
 
 From this point forward the configuration is the same for all the drivers. The `led_config_t` struct provides a key electrical matrix to led index lookup table, what the physical position of each LED is on the board, and what type of key or usage the LED if the LED represents. Here is a brief example:
 
-```C
+```c
 const led_config_t g_led_config = { {
   // Key Matrix to LED Index
   {   5, NO_LED, NO_LED,   0 },
@@ -146,7 +146,7 @@ const led_config_t g_led_config = { {
 
 The first part, `// Key Matrix to LED Index`, tells the system what key this LED represents by using the key's electrical matrix row & col. The second part, `// LED Index to Physical Position` represents the LED's physical `{ x, y }` position on the keyboard. The default expected range of values for `{ x, y }` is the inclusive range `{ 0..224, 0..64 }`. This default expected range is due to effects that calculate the center of the keyboard for their animations. The easiest way to calculate these positions is imagine your keyboard is a grid, and the top left of the keyboard represents `{ x, y }` coordinate `{ 0, 0 }` and the bottom right of your keyboard represents `{ 224, 64 }`. Using this as a basis, you can use the following formula to calculate the physical position:
 
-```C
+```c
 x = 224 / (NUMBER_OF_COLS - 1) * COL_POSITION
 y =  64 / (NUMBER_OF_ROWS - 1) * ROW_POSITION
 ```
@@ -157,7 +157,7 @@ As mentioned earlier, the center of the keyboard by default is expected to be `{
 
 `// LED Index to Flag` is a bitmask, whether or not a certain LEDs is of a certain type. It is recommended that LEDs are set to only 1 type.
 
-## Flags
+## Flags :id=flags
 
 |Define                              |Description                                |
 |------------------------------------|-------------------------------------------|
@@ -169,7 +169,7 @@ As mentioned earlier, the center of the keyboard by default is expected to be `{
 |`#define LED_FLAG_UNDERGLOW 0x02`   |If the LED is for underglow.               |
 |`#define LED_FLAG_KEYLIGHT  0x04`   |If the LED is for key backlight.           |
 
-## Keycodes
+## Keycodes :id=keycodes
 
 All RGB keycodes are currently shared with the RGBLIGHT system:
 
@@ -189,11 +189,11 @@ All RGB keycodes are currently shared with the RGBLIGHT system:
 
 * `RGB_MODE_*` keycodes will generally work, but are not currently mapped to the correct effects for the RGB Matrix system
 
-## RGB Matrix Effects
+## RGB Matrix Effects :id=rgb-matrix-effects
 
 All effects have been configured to support current configuration values (Hue, Saturation, Value, & Speed) unless otherwise noted below. These are the effects that are currently available:
 
-```C
+```c
 enum rgb_matrix_effects {
     RGB_MATRIX_NONE = 0,
     RGB_MATRIX_SOLID_COLOR = 1,     // Static single hue, no speed support
@@ -285,7 +285,7 @@ You can disable a single effect by defining `DISABLE_[EFFECT_NAME]` in your `con
 |`#define DISABLE_RGB_MATRIX_SOLID_MULTISPLASH`         |Disables `RGB_MATRIX_SOLID_MULTISPLASH`        |
 
 
-## Custom RGB Matrix Effects
+## Custom RGB Matrix Effects :id=custom-rgb-matrix-effects
 
 By setting `RGB_MATRIX_CUSTOM_USER` (and/or `RGB_MATRIX_CUSTOM_KB`) in `rules.mk`, new effects can be defined directly from userspace, without having to edit any QMK core files.
 
@@ -294,7 +294,7 @@ To declare new effects, create a new `rgb_matrix_user/kb.inc` that looks somethi
 `rgb_matrix_user.inc` should go in the root of the keymap directory.
 `rgb_matrix_kb.inc` should go in the root of the keyboard directory.
 
-```C
+```c
 // !!! DO NOT ADD #pragma once !!! //
 
 // Step 1.
@@ -341,7 +341,7 @@ static bool my_cool_effect2(effect_params_t* params) {
 For inspiration and examples, check out the built-in effects under `quantum/rgb_matrix_animation/`
 
 
-## Colors
+## Colors :id=colors
 
 These are shorthands to popular colors. The `RGB` ones can be passed to the `setrgb` functions, while the `HSV` ones to the `sethsv` functions.
 
@@ -369,9 +369,9 @@ These are shorthands to popular colors. The `RGB` ones can be passed to the `set
 These are defined in [`rgblight_list.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/rgblight_list.h). Feel free to add to this list!
 
 
-## Additional `config.h` Options
+## Additional `config.h` Options :id=additional-configh-options
 
-```C
+```c
 #define RGB_MATRIX_KEYPRESSES // reacts to keypresses
 #define RGB_MATRIX_KEYRELEASES // reacts to keyreleases (instead of keypresses)
 #define RGB_DISABLE_AFTER_TIMEOUT 0 // number of ticks to wait until disabling effects
@@ -386,28 +386,102 @@ These are defined in [`rgblight_list.h`](https://github.com/qmk/qmk_firmware/blo
 #define RGB_MATRIX_STARTUP_SPD 127 // Sets the default animation speed, if none has been set
 ```
 
-## EEPROM storage
+## EEPROM storage :id=eeprom-storage
 
 The EEPROM for it is currently shared with the RGBLIGHT system (it's generally assumed only one RGB would be used at a time), but could be configured to use its own 32bit address with:
 
-```C
+```c
 #define EECONFIG_RGB_MATRIX (uint32_t *)28
 ```
 
 Where `28` is an unused index from `eeconfig.h`.
 
-## Suspended state
+## Functions :id=functions
 
-To use the suspend feature, add this to your `<keyboard>.c`:
+### Direct Operation :id=direct-operation
+|Function                                    |Description  |
+|--------------------------------------------|-------------|
+|`rgb_matrix_set_color_all(r, g, b)`         |Set all of the LEDs to the given RGB value, where `r`/`g`/`b` are between 0 and 255 (not written to EEPROM) |
+|`rgb_matrix_set_color(index, r, g, b)`      |Set a single LED to the given RGB value, where `r`/`g`/`b` are between 0 and 255, and `index` is between 0 and `DRIVER_LED_TOTAL` (not written to EEPROM) |
 
-```C
-void suspend_power_down_kb(void)
-{
+### Disable/Enable Effects :id=disable-enable-effects
+|Function                                    |Description  |
+|--------------------------------------------|-------------|
+|`rgb_matrix_toggle()`                       |Toggle effect range LEDs between on and off |
+|`rgb_matrix_toggle_noeeprom()`              |Toggle effect range LEDs between on and off (not written to EEPROM) |
+|`rgb_matrix_enable()`                       |Turn effect range LEDs on, based on their previous state |
+|`rgb_matrix_enable_noeeprom()`              |Turn effect range LEDs on, based on their previous state (not written to EEPROM) |
+|`rgb_matrix_disable()`                      |Turn effect range LEDs off |
+|`rgb_matrix_disable_noeeprom()`             |Turn effect range LEDs off (not written to EEPROM) |
+
+### Change Effect Mode :id=change-effect-mode
+|Function                                    |Description  |
+|--------------------------------------------|-------------|
+|`rgb_matrix_mode(mode)`                     |Set the mode, if RGB animations are enabled |
+|`rgb_matrix_mode_noeeprom(mode)`            |Set the mode, if RGB animations are enabled (not written to EEPROM) |
+|`rgb_matrix_step()`                         |Change the mode to the next RGB animation in the list of enabled RGB animations |
+|`rgb_matrix_step_reverse()`                 |Change the mode to the previous RGB animation in the list of enabled RGB animations |
+|`rgb_matrix_increase_speed()`               |Increases the speed of the animations |
+|`rgb_matrix_decrease_speed()`               |Decreases the speed of the animations |
+
+### Change Color :id=change-color
+|Function                                    |Description  |
+|--------------------------------------------|-------------|
+|`rgb_matrix_increase_hue()`                 |Increase the hue for effect range LEDs. This wraps around at maximum hue |
+|`rgb_matrix_decrease_hue()`                 |Decrease the hue for effect range LEDs. This wraps around at minimum hue |
+|`rgb_matrix_increase_sat()`                 |Increase the saturation for effect range LEDs. This wraps around at maximum saturation |
+|`rgb_matrix_decrease_sat()`                 |Decrease the saturation for effect range LEDs. This wraps around at minimum saturation |
+|`rgb_matrix_increase_val()`                 |Increase the value for effect range LEDs. This wraps around at maximum value |
+|`rgb_matrix_decrease_val()`                 |Decrease the value for effect range LEDs. This wraps around at minimum value |
+|`rgb_matrix_sethsv(h, s, v)`                |Set LEDs to the given HSV value where `h`/`s`/`v` are between 0 and 255 |
+|`rgb_matrix_sethsv_noeeprom(h, s, v)`       |Set LEDs to the given HSV value where `h`/`s`/`v` are between 0 and 255 (not written to EEPROM) |
+
+### Query Current Status :id=query-current-status
+|Function                         |Description                |
+|---------------------------------|---------------------------|
+|`rgb_matrix_is_enabled()`        |Gets current on/off status |
+|`rgb_matrix_get_mode()`          |Gets current mode          |
+|`rgb_matrix_get_hue()`           |Gets current hue           |
+|`rgb_matrix_get_sat()`           |Gets current sat           |
+|`rgb_matrix_get_val()`           |Gets current val           |
+|`rgb_matrix_get_hsv()`           |Gets hue, sat, and val and returns a [`HSV` structure](https://github.com/qmk/qmk_firmware/blob/7ba6456c0b2e041bb9f97dbed265c5b8b4b12192/quantum/color.h#L56-L61)|
+|`rgb_matrix_get_speed()`         |Gets current speed         |
+|`rgb_matrix_get_suspend_state()` |Gets current suspend state |
+
+## Callbacks :id=callbacks
+
+### Indicators :id=indicators
+
+If you want to set custom indicators, such as an LED for Caps Lock, or layer indication, you can use the `rgb_matrix_indicators_kb` or `rgb_matrix_indicators_user` function for that: 
+```c
+void rgb_matrix_indicators_kb(void) {
+    rgb_matrix_set_color(index, red, green, blue);
+}
+```
+
+### Suspended state :id=suspended-state
+To use the suspend feature, make sure that `#define RGB_DISABLE_WHEN_USB_SUSPENDED true` is added to the `config.h` file. 
+
+Additionally add this to your `<keyboard>.c`:
+
+```c
+void suspend_power_down_kb(void) {
+    rgb_matrix_set_suspend_state(true);
+    suspend_power_down_user();
+}
+
+void suspend_wakeup_init_kb(void) {
+    rgb_matrix_set_suspend_state(false);
+    suspend_wakeup_init_user();
+}
+```
+or add this to your `keymap.c`:
+```c
+void suspend_power_down_user(void) {
     rgb_matrix_set_suspend_state(true);
 }
 
-void suspend_wakeup_init_kb(void)
-{
+void suspend_wakeup_init_user(void) {
     rgb_matrix_set_suspend_state(false);
 }
 ```

docs/feature_rgblight.md

@@ -94,6 +94,7 @@ if `RGBLIGHT_EFFECT_xxxx` or `RGBLIGHT_ANIMATIONS` is defined, you also have a n
 |`RGBLIGHT_MODE_STATIC_GRADIENT`| 0,1,..,9        |Static gradient                        |
 |`RGBLIGHT_MODE_RGB_TEST`     | *None*            |RGB Test                               |
 |`RGBLIGHT_MODE_ALTERNATING`  | *None*            |Alternating                            |
+|`RGBLIGHT_MODE_TWINKLE`      | 0,1,2,3,4,5       |Twinkle                                |
 
 Check out [this video](https://youtube.com/watch?v=VKrpPAHlisY) for a demonstration.
 
@@ -103,8 +104,8 @@ Note: For versions older than 0.6.117, The mode numbers were written directly. I
 
 Use these defines to add or remove animations from the firmware. When you are running low on flash space, it can be helpful to disable animations you are not using.
 
-|Define                              |Default      |Description                                                                          |
-|------------------------------------|-------------|-------------------------------------------------------------------------------------|
+|Define                              |Default      |Description                                                              |
+|------------------------------------|-------------|-------------------------------------------------------------------------|
 |`RGBLIGHT_ANIMATIONS`               |*Not defined*|Enable all additional animation modes.                                   |
 |`RGBLIGHT_EFFECT_ALTERNATING`       |*Not defined*|Enable alternating animation mode.                                       |
 |`RGBLIGHT_EFFECT_BREATHING`         |*Not defined*|Enable breathing animation mode.                                         |
@@ -115,6 +116,7 @@ Use these defines to add or remove animations from the firmware. When you are ru
 |`RGBLIGHT_EFFECT_RGB_TEST`          |*Not defined*|Enable RGB test animation mode.                                          |
 |`RGBLIGHT_EFFECT_SNAKE`             |*Not defined*|Enable snake animation mode.                                             |
 |`RGBLIGHT_EFFECT_STATIC_GRADIENT`   |*Not defined*|Enable static gradient mode.                                             |
+|`RGBLIGHT_EFFECT_TWINKLE`           |*Not defined*|Enable twinkle animation mode.                                           |
 
 ### Effect and Animation Settings
 
@@ -131,6 +133,8 @@ The following options are used to tweak the various animations:
 |`RGBLIGHT_EFFECT_KNIGHT_OFFSET`     |`0`          |The number of LEDs to start the "Knight" animation from the start of the strip by    |
 |`RGBLIGHT_RAINBOW_SWIRL_RANGE`      |`255`        |Range adjustment for the rainbow swirl effect to get different swirls                |
 |`RGBLIGHT_EFFECT_SNAKE_LENGTH`      |`4`          |The number of LEDs to light up for the "Snake" animation                             |
+|`RGBLIGHT_EFFECT_TWINKLE_LIFE`      |`75`         |Adjusts how quickly each LED brightens and dims when twinkling (in animation steps)  |
+|`RGBLIGHT_EFFECT_TWINKLE_PROBABILITY`|`1/127`     |Adjusts how likely each LED is to twinkle (on each animation step)                   |
 
 ### Example Usage to Reduce Memory Footprint
   1. Remove `RGBLIGHT_ANIMATIONS` from `config.h`.
@@ -168,10 +172,112 @@ const uint8_t RGBLED_SNAKE_INTERVALS[] PROGMEM = {100, 50, 20};
 // How long (in milliseconds) to wait between animation steps for each of the "Knight" animations
 const uint8_t RGBLED_KNIGHT_INTERVALS[] PROGMEM = {127, 63, 31};
 
+// How long (in milliseconds) to wait between animation steps for each of the "Twinkle" animations
+const uint8_t RGBLED_TWINKLE_INTERVALS[] PROGMEM = {50, 25, 10};
+
 // These control which hues are selected for each of the "Static gradient" modes
 const uint8_t RGBLED_GRADIENT_RANGES[] PROGMEM = {255, 170, 127, 85, 64};
 ```
 
+## Lighting Layers
+
+By including `#define RGBLIGHT_LAYERS` in your `config.h` file you can enable lighting layers. These make
+it easy to use your underglow LEDs as status indicators to show which keyboard layer is currently active, or the state of caps lock, all without disrupting any animations. [Here's a video](https://youtu.be/uLGE1epbmdY) showing an example of what you can do.
+
+### Defining Lighting Layers :id=defining-lighting-layers
+
+By default, 8 layers are possible. This can be expanded to as many as 32 by overriding the definition of `RGBLIGHT_MAX_LAYERS` in `config.h` (e.g. `#define RGBLIGHT_MAX_LAYERS 32`). Please note, if you use a split keyboard, you will need to flash both sides of the split after changing this. Also, increasing the maximum will increase the firmware size, and will slow sync on split keyboards.
+
+To define a layer, we modify `keymap.c` to list out LED ranges and the colors we want to overlay on them using an array of `rgblight_segment_t` using the `RGBLIGHT_LAYER_SEGMENTS` macro. We can define multiple layers and enable/disable them independently:
+
+```c
+// Light LEDs 6 to 9 and 12 to 15 red when caps lock is active. Hard to ignore!
+const rgblight_segment_t PROGMEM my_capslock_layer[] = RGBLIGHT_LAYER_SEGMENTS(
+    {6, 4, HSV_RED},       // Light 4 LEDs, starting with LED 6
+    {12, 4, HSV_RED}       // Light 4 LEDs, starting with LED 12
+);
+// Light LEDs 9 & 10 in cyan when keyboard layer 1 is active
+const rgblight_segment_t PROGMEM my_layer1_layer[] = RGBLIGHT_LAYER_SEGMENTS(
+    {9, 2, HSV_CYAN}
+);
+// Light LEDs 11 & 12 in purple when keyboard layer 2 is active
+const rgblight_segment_t PROGMEM my_layer2_layer[] = RGBLIGHT_LAYER_SEGMENTS(
+    {11, 2, HSV_PURPLE}
+);
+// etc..
+```
+
+We combine these layers into an array using the `RGBLIGHT_LAYERS_LIST` macro, and assign it to the `rgblight_layers` variable during keyboard setup. Note that you can only define up to 8 lighting layers. Any extra layers will be ignored. Since the different lighting layers overlap, the order matters in the array, with later layers taking precedence:
+
+```c
+// Now define the array of layers. Later layers take precedence
+const rgblight_segment_t* const PROGMEM my_rgb_layers[] = RGBLIGHT_LAYERS_LIST(
+    my_capslock_layer,
+    my_layer1_layer,    // Overrides caps lock layer
+    my_layer2_layer     // Overrides other layers
+);
+
+void keyboard_post_init_user(void) {
+    // Enable the LED layers
+    rgblight_layers = my_rgb_layers;
+}
+```
+Note: For split keyboards with two controllers, both sides need to be flashed when updating the contents of rgblight_layers.
+
+### Enabling and disabling lighting layers :id=enabling-lighting-layers
+
+Everything above just configured the definition of each lighting layer.
+We can now enable and disable the lighting layers whenever the state of the keyboard changes:
+
+```c
+layer_state_t layer_state_set_user(layer_state_t state) {
+    // Both layers will light up if both kb layers are active
+    rgblight_set_layer_state(1, layer_state_cmp(state, 1));
+    rgblight_set_layer_state(2, layer_state_cmp(state, 2));
+    return state;
+}
+
+bool led_update_user(led_t led_state) {
+    rgblight_set_layer_state(0, led_state.caps_lock);
+    return true;
+}
+```
+
+### Lighting layer blink :id=lighting-layer-blink
+
+By including `#define RGBLIGHT_LAYER_BLINK` in your `config.h` file you can turn a lighting
+layer on for a specified duration. Once the specified number of milliseconds has elapsed
+the layer will be turned off. This is useful, e.g., if you want to acknowledge some
+action (e.g. toggling some setting):
+
+```c
+const rgblight_segment_t PROGMEM _yes_layer[] = RGBLIGHT_LAYER_SEGMENTS( {9, 6, HSV_GREEN} );
+const rgblight_segment_t PROGMEM _no_layer[] = RGBLIGHT_LAYER_SEGMENTS( {9, 6, HSV_RED} );
+
+const rgblight_segment_t* const PROGMEM _rgb_layers[] =
+    RGBLIGHT_LAYERS_LIST( _yes_layer, _no_layer );
+
+void keyboard_post_init_user(void) {
+    rgblight_layers = _rgb_layers;
+}
+
+// Note we user post_process_record_user because we want the state
+// after the flag has been flipped...
+void post_process_record_user(uint16_t keycode, keyrecord_t *record) {
+    switch (keycode) {
+        case DEBUG:
+            rgblight_blink_layer(debug_enable ? 0 : 1, 500);
+            break;
+
+        case NK_TOGG:
+        case NK_ON:
+        case NK_OFF:
+            rgblight_blink_layer(keymap_config.nkro ? 0 : 1, 500);
+            break;
+    }
+}
+```
+
 ## Functions
 
 If you need to change your RGB lighting in code, for example in a macro to change the color whenever you switch layers, QMK provides a set of functions to assist you. See [`rgblight.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/rgblight.h) for the full list, but the most commonly used functions include:
@@ -263,13 +369,21 @@ rgblight_sethsv(HSV_GREEN, 2); // led 2
 |`rgblight_sethsv(h, s, v)`                  |Set effect range LEDs to the given HSV value where `h`/`s`/`v` are between 0 and 255 |
 |`rgblight_sethsv_noeeprom(h, s, v)`         |Set effect range LEDs to the given HSV value where `h`/`s`/`v` are between 0 and 255 (not written to EEPROM) |
 
+#### layer functions
+|Function                                    |Description  |
+|--------------------------------------------|-------------|
+|`rgblight_get_layer_state(i)`               |Returns `true` if lighting layer `i` is enabled |
+|`rgblight_set_layer_state(i, is_on)`        |Enable or disable lighting layer `i` based on value of `bool is_on` |
+
 #### query
-|Function               |Description      |
-|-----------------------|-----------------|
-|`rgblight_get_mode()`  |Get current mode |
-|`rgblight_get_hue()`   |Get current hue  |
-|`rgblight_get_sat()`   |Get current sat  |
-|`rgblight_get_val()`   |Get current val  |
+|Function               |Description                |
+|-----------------------|---------------------------|
+|`rgblight_is_enabled()`|Gets current on/off status |
+|`rgblight_get_mode()`  |Gets current mode          |
+|`rgblight_get_hue()`   |Gets current hue           |
+|`rgblight_get_sat()`   |Gets current sat           |
+|`rgblight_get_val()`   |Gets current val           |
+|`rgblight_get_speed()` |Gets current speed         |
 
 ## Colors
 

docs/feature_split_keyboard.md

@@ -8,9 +8,20 @@ QMK Firmware has a generic implementation that is usable by any board, as well a
 
 For this, we will mostly be talking about the generic implementation used by the Let's Split and other keyboards. 
 
-!> ARM is not yet supported for Split Keyboards.  Progress is being made, but we are not quite there, yet. 
+!> ARM is not yet fully supported for Split Keyboards and has many limitations. Progress is being made, but we have not yet reached 100% feature parity.
 
 
+## Compatibility Overview
+
+| Transport                    | AVR                | ARM                |
+|------------------------------|--------------------|--------------------|
+| ['serial'](serial_driver.md) | :heavy_check_mark: | :white_check_mark: <sup>1</sup> |
+| I2C                          | :heavy_check_mark: |                    |
+
+Notes:
+
+1. Both hardware and software limitations are detailed within the [driver documentation](serial_driver.md).
+
 ## Hardware Configuration
 
 This assumes that you're using two Pro Micro-compatible controllers, and are using TRRS jacks to connect to two halves. 
@@ -198,10 +209,15 @@ This option changes the startup behavior to detect an active USB connection when
 ?> This setting will stop the ability to demo using battery packs.
 
 ```c
-#define SPLIT_USB_TIMEOUT 2500
+#define SPLIT_USB_TIMEOUT 2000
 ```
 This sets the maximum timeout when detecting master/slave when using `SPLIT_USB_DETECT`.
 
+```c
+#define SPLIT_USB_TIMEOUT_POLL 10
+```
+This sets the poll frequency when detecting master/slave when using `SPLIT_USB_DETECT`
+
 ## Additional Resources
 
 Nicinabox has a [very nice and detailed guide](https://github.com/nicinabox/lets-split-guide) for the Let's Split keyboard, that covers most everything you need to know, including troubleshooting information. 

docs/feature_stenography.md

@@ -1,16 +1,16 @@
-# Stenography in QMK
+# Stenography in QMK :id=stenography-in-qmk
 
 [Stenography](https://en.wikipedia.org/wiki/Stenotype) is a method of writing most often used by court reports, closed-captioning, and real-time transcription for the deaf. In stenography words are chorded syllable by syllable with a mixture of spelling, phonetic, and shortcut (briefs) strokes. Professional stenographers can reach 200-300 WPM without any of the strain usually found in standard typing and with far fewer errors (>99.9% accuracy).
 
 The [Open Steno Project](http://www.openstenoproject.org/) has built an open-source program called Plover that provides real-time translation of steno strokes into words and commands. It has an established dictionary and supports
 
-## Plover with QWERTY Keyboard
+## Plover with QWERTY Keyboard :id=plover-with-qwerty-keyboard
 
 Plover can work with any standard QWERTY keyboard, although it is more efficient if the keyboard supports NKRO (n-key rollover) to allow Plover to see all the pressed keys at once. An example keymap for Plover can be found in `planck/keymaps/default`. Switching to the `PLOVER` layer adjusts the position of the keyboard to support the number bar.
 
 To use Plover with QMK just enable NKRO and optionally adjust your layout if you have anything other than a standard layout. You may also want to purchase some steno-friendly keycaps to make it easier to hit multiple keys.
 
-## Plover with Steno Protocol
+## Plover with Steno Protocol :id=plover-with-steno-protocol
 
 Plover also understands the language of several steno machines. QMK can speak a couple of these languages, TX Bolt and GeminiPR. An example layout can be found in `planck/keymaps/steno`.
 
@@ -20,26 +20,26 @@ In this mode Plover expects to speak with a steno machine over a serial port so
 
 > Note: Due to hardware limitations you may not be able to run both a virtual serial port and mouse emulation at the same time.
 
-### TX Bolt
+### TX Bolt :id=tx-bolt
 
 TX Bolt communicates the status of 24 keys over a very simple protocol in variable-sized (1-5 byte) packets.
 
-### GeminiPR
+### GeminiPR :id=geminipr
 
 GeminiPR encodes 42 keys into a 6-byte packet. While TX Bolt contains everything that is necessary for standard stenography, GeminiPR opens up many more options, including supporting non-English theories.
 
-## Configuring QMK for Steno
+## Configuring QMK for Steno :id=configuring-qmk-for-steno
 
 Firstly, enable steno in your keymap's Makefile. You may also need disable mousekeys, extra keys, or another USB endpoint to prevent conflicts. The builtin USB stack for some processors only supports a certain number of USB endpoints and the virtual serial port needed for steno fills 3 of them.
 
-```Makefile
+```makefile
 STENO_ENABLE = yes
 MOUSEKEY_ENABLE = no
 ```
 
 In your keymap create a new layer for Plover. You will need to include `keymap_steno.h`. See `planck/keymaps/steno/keymap.c` for an example. Remember to create a key to switch to the layer as well as a key for exiting the layer. If you would like to switch modes on the fly you can use the keycodes `QK_STENO_BOLT` and `QK_STENO_GEMINI`. If you only want to use one of the protocols you may set it up in your initialization function:
 
-```C
+```c
 void matrix_init_user() {
   steno_set_mode(STENO_MODE_GEMINI); // or STENO_MODE_BOLT
 }
@@ -49,37 +49,37 @@ Once you have your keyboard flashed launch Plover. Click the 'Configure...' butt
 
 On the display tab click 'Open stroke display'. With Plover disabled you should be able to hit keys on your keyboard and see them show up in the stroke display window. Use this to make sure you have set up your keymap correctly. You are now ready to steno!
 
-## Learning Stenography
+## Learning Stenography :id=learning-stenography
 
-* [Learn Plover!](https://sites.google.com/site/ploverdoc/)
+* [Learn Plover!](https://sites.google.com/site/learnplover/)
 * [QWERTY Steno](http://qwertysteno.com/Home/)
 * [Steno Jig](https://joshuagrams.github.io/steno-jig/)
 * More resources at the Plover [Learning Stenography](https://github.com/openstenoproject/plover/wiki/Learning-Stenography) wiki
 
-## Interfacing with the code
+## Interfacing with the code :id=interfacing-with-the-code
 
 The steno code has three interceptible hooks. If you define these functions, they will be called at certain points in processing; if they return true, processing continues, otherwise it's assumed you handled things.
 
-```C
+```c
 bool send_steno_chord_user(steno_mode_t mode, uint8_t chord[6]);
 ```
 
 This function is called when a chord is about to be sent. Mode will be one of `STENO_MODE_BOLT` or `STENO_MODE_GEMINI`. This represents the actual chord that would be sent via whichever protocol. You can modify the chord provided to alter what gets sent. Remember to return true if you want the regular sending process to happen.
 
-```C
+```c
 bool process_steno_user(uint16_t keycode, keyrecord_t *record) { return true; }
 ```
 
 This function is called when a keypress has come in, before it is processed. The keycode should be one of `QK_STENO_BOLT`, `QK_STENO_GEMINI`, or one of the `STN_*` key values.
 
-```C
+```c
 bool postprocess_steno_user(uint16_t keycode, keyrecord_t *record, steno_mode_t mode, uint8_t chord[6], int8_t pressed);
 ```
 
 This function is called after a key has been processed, but before any decision about whether or not to send a chord. If `IS_PRESSED(record->event)` is false, and `pressed` is 0 or 1, the chord will be sent shortly, but has not yet been sent. This is where to put hooks for things like, say, live displays of steno chords or keys.
 
 
-## Keycode Reference
+## Keycode Reference :id=keycode-reference
 
 As defined in `keymap_steno.h`.
 

docs/feature_swap_hands.md

@@ -28,3 +28,4 @@ Note that the array indices are reversed same as the matrix and the values are o
 |`SH_MOFF`  |Momentarily turns off swap.                                              |
 |`SH_TG`    |Toggles swap on and off with every key press.                            |
 |`SH_TT`    |Toggles with a tap; momentary when held.                                 |
+|`SH_OS`    |One shot swap hands: toggles while pressed or until next key press.      |

docs/feature_tap_dance.md

@@ -335,7 +335,7 @@ If you want to implement this in your userspace, then you may want to check out
 
 > In this configuration "hold" takes place **after** tap dance timeout (see `ACTION_TAP_DANCE_FN_ADVANCED_TIME`). To achieve instant hold, remove `state->interrupted` checks in conditions. As a result you may use comfortable longer tapping periods to have more time for taps and not to wait too long for holds (try starting with doubled `TAPPING_TERM`).
 
-### Example 5: Using tap dance for advanced mod-tap and layer-tap keys
+### Example 5: Using tap dance for advanced mod-tap and layer-tap keys :id=example-5-using-tap-dance-for-advanced-mod-tap-and-layer-tap-keys
 
 Tap dance can be used to emulate `MT()` and `LT()` behavior when the tapped code is not a basic keycode. This is useful to send tapped keycodes that normally require `Shift`, such as parentheses or curly braces—or other modified keycodes, such as `Control + X`.
 

docs/feature_unicode.md

@@ -90,13 +90,15 @@ Unicode input in QMK works by inputting a sequence of characters to the OS, sort
 
 The following input modes are available:
 
-* **`UC_OSX`**: macOS built-in Unicode hex input. Supports code points up to `0xFFFF` (`0x10FFFF` with Unicode Map).
+* **`UC_MAC`**: macOS built-in Unicode hex input. Supports code points up to `0xFFFF` (`0x10FFFF` with Unicode Map).
 
   To enable, go to _System Preferences > Keyboard > Input Sources_, add _Unicode Hex Input_ to the list (it's under _Other_), then activate it from the input dropdown in the Menu Bar.
-  By default, this mode uses the left Option key (`KC_LALT`) for Unicode input, but this can be changed by defining [`UNICODE_KEY_OSX`](#input-key-configuration) with another keycode.
+  By default, this mode uses the left Option key (`KC_LALT`) for Unicode input, but this can be changed by defining [`UNICODE_KEY_MAC`](#input-key-configuration) with another keycode.
 
   !> Using the _Unicode Hex Input_ input source may disable some Option based shortcuts, such as Option + Left Arrow and Option + Right Arrow.
 
+  !> `UC_OSX` is a deprecated alias of `UC_MAC` that will be removed in a future version of QMK.
+
 * **`UC_LNX`**: Linux built-in IBus Unicode input. Supports code points up to `0x10FFFF` (all possible code points).
 
   Enabled by default and works almost anywhere on IBus-enabled distros. Without IBus, this mode works under GTK apps, but rarely anywhere else.
@@ -124,7 +126,7 @@ You can switch the input mode at any time by using one of the following keycodes
 |----------------------|---------|------------|--------------------------------------------------------------|
 |`UNICODE_MODE_FORWARD`|`UC_MOD` |Next in list|[Cycle](#input-mode-cycling) through selected modes           |
 |`UNICODE_MODE_REVERSE`|`UC_RMOD`|Prev in list|[Cycle](#input-mode-cycling) through selected modes in reverse|
-|`UNICODE_MODE_OSX`    |`UC_M_OS`|`UC_OSX`    |Switch to macOS input                                         |
+|`UNICODE_MODE_MAC`    |`UC_M_MA`|`UC_MAC`    |Switch to macOS input                                         |
 |`UNICODE_MODE_LNX`    |`UC_M_LN`|`UC_LNX`    |Switch to Linux input                                         |
 |`UNICODE_MODE_WIN`    |`UC_M_WI`|`UC_WIN`    |Switch to Windows input                                       |
 |`UNICODE_MODE_BSD`    |`UC_M_BS`|`UC_BSD`    |Switch to BSD input (not implemented)                         |
@@ -145,9 +147,9 @@ If you have the [Audio feature](feature_audio.md) enabled on the board, you can
 For instance, you can add these definitions to your `config.h` file:
 
 ```c
-#define UNICODE_SONG_OSX  COIN_SOUND
+#define UNICODE_SONG_MAC  AUDIO_ON_SOUND
 #define UNICODE_SONG_LNX  UNICODE_LINUX
-#define UNICODE_SONG_BSD  MARIO_GAMEOVER
+#define UNICODE_SONG_BSD  TERMINAL_SOUND
 #define UNICODE_SONG_WIN  UNICODE_WINDOWS
 #define UNICODE_SONG_WINC UNICODE_WINDOWS
 ```
@@ -171,7 +173,7 @@ You can customize the keys used to trigger Unicode input for macOS, Linux and Wi
 
 |Define            |Type      |Default           |Example                                    |
 |------------------|----------|------------------|-------------------------------------------|
-|`UNICODE_KEY_OSX` |`uint8_t` |`KC_LALT`         |`#define UNICODE_KEY_OSX  KC_RALT`         |
+|`UNICODE_KEY_MAC` |`uint8_t` |`KC_LALT`         |`#define UNICODE_KEY_MAC  KC_RALT`         |
 |`UNICODE_KEY_LNX` |`uint16_t`|`LCTL(LSFT(KC_U))`|`#define UNICODE_KEY_LNX  LCTL(LSFT(KC_E))`|
 |`UNICODE_KEY_WINC`|`uint8_t` |`KC_RALT`         |`#define UNICODE_KEY_WINC KC_RGUI`         |
 
@@ -180,7 +182,7 @@ You can customize the keys used to trigger Unicode input for macOS, Linux and Wi
 You can choose which input modes are available for cycling through. By default, this is disabled. If you want to enable it, limiting it to just the modes you use makes sense. Note that the values in the list are comma-delimited.
 
 ```c
-#define UNICODE_SELECTED_MODES UC_OSX, UC_LNX, UC_WIN, UC_WINC
+#define UNICODE_SELECTED_MODES UC_MAC, UC_LNX, UC_WIN, UC_WINC
 ```
 
 You can cycle through the selected modes by using the `UC_MOD`/`UC_RMOD` keycodes, or by calling `cycle_unicode_input_mode(offset)` in your code (`offset` is how many modes to move forward by, so +1 corresponds to `UC_MOD`).
@@ -193,12 +195,23 @@ By default, when the keyboard boots, it will initialize the input mode to the la
 
 !> Using `UNICODE_SELECTED_MODES` means you don't have to initially set the input mode in `matrix_init_user()` (or a similar function); the Unicode system will do that for you on startup. This has the added benefit of avoiding unnecessary writes to EEPROM.
 
-## `send_unicode_hex_string`
+## `send_unicode_string()`
 
-To type multiple characters for things like (ノಠ痊ಠ)ノ彡┻━┻, you can use `send_unicode_hex_string()` much like `SEND_STRING()` except you would use hex values separate by spaces.
-For example, the table flip seen above would be `send_unicode_hex_string("0028 30CE 0CA0 75CA 0CA0 0029 30CE 5F61 253B 2501 253B")`
+This function is much like `send_string()` but allows you to input UTF-8 characters directly, and supports all code points (provided the selected input method also supports it). Make sure your `keymap.c` is formatted in UTF-8 encoding.
 
-There are many ways to get a hex code, but an easy one is [this site](https://r12a.github.io/app-conversion/). Just make sure to convert to hexadecimal, and that is your string.
+```c
+send_unicode_string("(ノಠ痊ಠ)ノ彡┻━┻");
+```
+
+## `send_unicode_hex_string()`
+
+Similar to `send_unicode_string()`, but the characters are represented by their code point values in ASCII, separated by spaces. For example, the table flip above would be achieved with:
+
+```c
+send_unicode_hex_string("0028 30CE 0CA0 75CA 0CA0 0029 30CE 5F61 253B 2501 253B");
+```
+
+An easy way to convert your Unicode string to this format is by using [this site](https://r12a.github.io/app-conversion/), and taking the result in the "Hex/UTF-32" section.
 
 ## Additional Language Support
 
@@ -228,6 +241,6 @@ AutoHotkey inserts the Text right of `Send, ` when this combination is pressed.
 
 If you enable the US International layout on the system, it will use punctuation to accent the characters.
 
-For instance, typing "`a" will result in à.
+For instance, typing "\`a" will result in à.
 
 You can find details on how to enable this [here](https://support.microsoft.com/en-us/help/17424/windows-change-keyboard-layout).

docs/feature_userspace.md

@@ -97,13 +97,25 @@ You'd want to replace the year, name, email and github username with your info.
 
 Additionally, this is a good place to document your code, if you wish to share it with others. 
 
-# Examples
+## Build All Keyboards That Support a Specific Keymap
+
+Want to check all your keymaps build in a single command? You can run:
+
+    make all:<name>
+
+For example,
+
+    make all:jack
+
+This is ideal for when you want ensure everything compiles successfully when preparing a [_Pull request_](https://github.com/qmk/qmk_firmware/pulls).
+
+## Examples
 
 For a brief example, checkout [`/users/_example/`](https://github.com/qmk/qmk_firmware/tree/master/users/drashna).  
 For a more complicated example, checkout [`/users/drashna/`](https://github.com/qmk/qmk_firmware/tree/master/users/drashna)'s userspace.
 
 
-## Customized Functions
+### Customized Functions
 
 QMK has a bunch of [functions](custom_quantum_functions.md) that have [`_quantum`, `_kb`, and `_user` versions](custom_quantum_functions.md#a-word-on-core-vs-keyboards-vs-keymap) that you can use.  You will pretty much always want to use the user version of these functions.  But the problem is that if you use them in your userspace, then you don't have a version that you can use in your keymap. 
 
@@ -130,7 +142,7 @@ The `_keymap` part here doesn't matter, it just needs to be something other than
 
 You can see a list of this and other common functions in [`template.c`](https://github.com/qmk/qmk_firmware/blob/master/users/drashna/template.c) in [`users/drashna`](https://github.com/qmk/qmk_firmware/tree/master/users/drashna).
 
-## Custom Features
+### Custom Features
 
 Since the Userspace feature can support a staggering number of boards, you may have boards that you want to enable certain functionality for, but not for others. And you can actually create "features" that you can enable or disable in your own userspace.  
 
@@ -166,7 +178,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
 ```
 
 
-## Consolidated Macros
+### Consolidated Macros
 
 If you wanted to consolidate macros and other functions into your userspace for all of your keymaps, you can do that.  This builds upon the [Customized Functions](#customized-functions) example above. This lets you maintain a bunch of macros that are shared between the different keyboards, and allow for keyboard specific macros, too. 
 

docs/feature_wpm.md

@@ -0,0 +1,25 @@
+# Word Per Minute (WPM) Calculcation
+
+The WPM feature uses time between keystrokes to compute a rolling average words
+per minute rate and makes this available for various uses.
+
+Enable the WPM system by adding this to your `rules.mk`:
+
+    WPM_ENABLE = yes
+
+For split keyboards using soft serial, the computed WPM
+score will be available on the master AND slave half.
+
+## Public Functions
+
+`uint8_t get_current_wpm(void);`
+This function returns the current WPM as an unsigned integer.
+
+
+## Customized keys for WPM calc
+
+By default, the WPM score only includes letters, numbers, space and some
+punctuation.  If you want to change the set of characters considered as part of
+the WPM calculation, you can implement `wpm_keycode_user(uint16_t keycode)`
+and return true for any characters you would like included in the calculation,
+or false to not count that particular keycode.

docs/features.md

@@ -1,42 +0,0 @@
-# QMK Features
-
-QMK has a staggering number of features for building your keyboard. It can take some time to understand all of them and determine which one will achieve your goal.
-
-
-* [Advanced Keycodes](feature_advanced_keycodes.md) - Change layers, dual-action keys, and more. Go beyond typing simple characters.
-* [Audio](feature_audio.md) - Connect a speaker to your keyboard for audio feedback, midi support, and music mode.
-* [Auto Shift](feature_auto_shift.md) - Tap for the normal key, hold slightly longer for its shifted state.
-* [Backlight](feature_backlight.md) - LED lighting support for your keyboard.
-* [Bluetooth](feature_bluetooth.md) - BlueTooth support for your keyboard.
-* [Bootmagic](feature_bootmagic.md) - Adjust the behavior of your keyboard using hotkeys.
-* [Combos](feature_combo.md) - Custom actions for multiple key holds.
-* [Command](feature_command.md) - Runtime version of bootmagic (Formerly known as "Magic").
-* [Debounce API](feature_debounce_type.md) - Customization of debouncing algorithms, and the ability to add more/custom debouncing. 
-* [DIP Switch](feature_dip_switch.md) - Toggle switches for customizing board function.
-* [Dynamic Macros](feature_dynamic_macros.md) - Record and playback macros from the keyboard itself.
-* [Encoders](feature_encoders.md) - Rotary encoders! 
-* [Grave Escape](feature_grave_esc.md) - Lets you use a single key for Esc and Grave. 
-* [Haptic Feedback](feature_haptic_feedback.md) - Add haptic feedback drivers to your board.
-* [HD44780 LCD Display](feature_hd44780.md) - Support for LCD character displays using the HD44780 standard.
-* [Key Lock](feature_key_lock.md) - Lock a key in the "down" state.
-* [Layouts](feature_layouts.md) - Use one keymap with any keyboard that supports your layout.
-* [Leader Key](feature_leader_key.md) - Tap the leader key followed by a sequence to trigger custom behavior.
-* [LED Matrix](feature_led_matrix.md) - LED Matrix single color lights for per key lighting (Single Color, not RGB).
-* [Macros](feature_macros.md) - Send multiple key presses when pressing only one physical key.
-* [Mouse keys](feature_mouse_keys.md) - Control your mouse pointer from your keyboard.
-* [OLED Driver](feature_oled_driver.md) - Add OLED screens to your keyboard.
-* [One Shot Keys](feature_advanced_keycodes.md#one-shot-keys) - Sticky Keys, lets you hit a key rather than holding it.
-* [Pointing Device](feature_pointing_device.md) - Framework for connecting your custom pointing device to your keyboard.
-* [PS2 Mouse](feature_ps2_mouse.md) - Driver for connecting a PS/2 mouse directly to your keyboard.
-* [RGB Light](feature_rgblight.md) - RGB lighting for your keyboard.
-* [RGB Matrix](feature_rgb_matrix.md) - RGB Matrix lights for per key lighting.
-* [Space Cadet](feature_space_cadet.md) - Use your left/right shift keys to type parenthesis and brackets.
-* [Split Keyboard](feature_split_keyboard.md) 
-* [Stenography](feature_stenography.md) - Put your keyboard into Plover mode for stenography use.
-* [Swap Hands](feature_swap_hands.md) - Mirror your keyboard for one handed usage.
-* [Tap Dance](feature_tap_dance.md) - Make a single key do as many things as you want.
-* [Terminal](feature_terminal.md) - CLI interface to the internals of your keyboard.
-* [Thermal Printer](feature_thermal_printer.md) - Connect a thermal printer to your keyboard to be able to toggle on a printed log of everything you type.
-* [Unicode](feature_unicode.md) - Unicode input support.
-* [Userspace](feature_userspace.md) - Share code between different keymaps and keyboards.
-* [Velocikey](feature_velocikey.md) - Allows changes in RGB animation speed based on WPM/Typing speed.

docs/flashing.md

@@ -1,8 +1,8 @@
 # Flashing Instructions and Bootloader Information
 
-There are quite a few different types of bootloaders that keyboards use, and just about all of the use a different flashing method. Luckily, projects like the [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) aim to be compatible with all the different types without having to think about it much, but this article will describe the different types of bootloaders, and available methods for flashing them.
+There are quite a few different types of bootloaders that keyboards use, and just about all of them use a different flashing method. Luckily, projects like the [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) aim to be compatible with all the different types without having to think about it much, but this article will describe the different types of bootloaders, and available methods for flashing them.
 
-If you have a bootloader selected with the `BOOTLOADER` variable in your `rules.mk`, QMK will automatically calculate if your .hex file is the right size to be flashed to the device, and output the total size in bytes (along with the max). To run this process manually, compile with the target `check-size`, eg `make planck/rev4:default:check-size`.
+If you have a bootloader selected with the `BOOTLOADER` variable in your `rules.mk`, QMK will automatically calculate if your .hex file is the right size to be flashed to the device, and output the total size in bytes (along with the max).
 
 ## DFU
 
@@ -26,7 +26,6 @@ Compatible flashers:
 
 * [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (recommended GUI)
 * [dfu-programmer](https://github.com/dfu-programmer/dfu-programmer) / `:dfu` in QMK (recommended command line)
-* [Atmel's Flip](http://www.microchip.com/developmenttools/productdetails.aspx?partno=flip) (not recommended)
 
 Flashing sequence:
 
@@ -100,7 +99,7 @@ or
     make <keyboard>:<keymap>:avrdude
 
 
-#### Caterina commands
+### Caterina commands
 
 There are a number of DFU commands that you can use to flash firmware to a DFU device:
 
@@ -113,7 +112,7 @@ There are a number of DFU commands that you can use to flash firmware to a DFU d
 
 ## Halfkay
 
-Halfkay is a super-slim protocol developed by PJRC that uses HID, and come on all Teensys (namely the 2.0).
+Halfkay is a super-slim protocol developed by PJRC that uses HID, and comes on all Teensys (namely the 2.0).
 
 To ensure compatibility with the Halfkay bootloader, make sure this block is present your `rules.mk`:
 

docs/fr-fr/_summary.md

@@ -81,7 +81,7 @@
   * [Macros](fr-fr/feature_macros.md)
   * [Boutons de souris](fr-fr/feature_mouse_keys.md)
   * [Pilotes / Drivers OLED](fr-fr/feature_oled_driver.md)
-  * [Touche one-shot](fr-fr/feature_advanced_keycodes.md#one-shot-keys)
+  * [Touche one-shot](fr-fr/one_shot_keys.md)
   * [Périphériques de pointage](fr-fr/feature_pointing_device.md)
   * [Souris PS/2](fr-fr/feature_ps2_mouse.md)
   * [Éclairage RGB](fr-fr/feature_rgblight.md)
@@ -101,7 +101,8 @@
   * [Guide des claviers soudés à la main](fr-fr/hand_wire.md)
   * [Guide de flash de l’ISP](fr-fr/isp_flashing_guide.md)
   * [Guide du débogage ARM](fr-fr/arm_debugging.md)
-  * [Drivers i2c](fr-fr/i2c_driver.md)
+  * [Drivers I2C](fr-fr/i2c_driver.md)
+  * [Drivers SPI](fr-fr/spi_driver.md)
   * [Contrôles des GPIO](fr-fr/internals_gpio_control.md)
   * [Conversion en Proton C](fr-fr/proton_c_conversion.md)
 
@@ -112,7 +113,7 @@
 * Autres sujets
   * [Utiliser Eclipse avec QMK](fr-fr/other_eclipse.md)
   * [Utiliser VSCode avec QMK](fr-fr/other_vscode.md)
-  * [Support](fr-fr/support.md)
+  * [Support](fr-fr/getting_started_getting_help.md)
   * [Comment ajouter des traductions](fr-fr/translating.md)
 
 * À l’intérieur de QMK (En cours de documentation)

docs/fr-fr/faq_debug.md

@@ -155,11 +155,3 @@ Pour le moment, l'origine du problème n'est pas comprise, mais certaines option
 
 https://github.com/tmk/tmk_keyboard/issues/266
 https://geekhack.org/index.php?topic=41989.msg1967778#msg1967778
-
-## FLIP ne marche pas
-
-### `AtLibUsbDfu.dll` Not Found
-
-Supprimez le pilote actuel et réinstallez celui donné par FLIP dans le gestionnaire de périphériques.
-
-http://imgur.com/a/bnwzy

docs/fr-fr/flashing.md

@@ -26,7 +26,6 @@ Méthodes de flash compatibles :
 
 * [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (interface graphique recommandé)
 * [dfu-programmer](https://github.com/dfu-programmer/dfu-programmer) / `:dfu` avec QMK (outil en ligne de commande recommandé)
-* [Atmel's Flip](http://www.microchip.com/developmenttools/productdetails.aspx?partno=flip) (non recommandé)
 
 Ordre des actions :
 

docs/fr-fr/newbs_building_firmware_configurator.md

@@ -4,7 +4,7 @@ Le [Configurateur de QMK](https://config.qmk.fm) est une interface graphique en
 
 ?> **S'il vous plaît, suivez les étapes suivantes dans l'ordre.**
 
-Regardez le [Tutoriel vidéo](https://youtu.be/tx54jkRC9ZY)
+Regardez le [Tutoriel vidéo](https://youtu.be/tx54jkRC9ZY)https://www.youtube.com/watch?v=-imgglzDMdY)
 
 Le configurateur de QMK fonctionne mieux avec Chrome et Firefox.
 

docs/getting_started_build_tools.md

@@ -1,141 +0,0 @@
-# Installing Build Tools
-
-This page describes setting up the build environment for QMK. These instructions cover AVR processors (such as the atmega32u4).
-
-<!-- FIXME: We should have ARM instructions somewhere. -->
-
-**Note:** If this is your first time here, check out the [Complete Newbs Guide](newbs.md) page.
-
-Before continuing, double check that your submodules (third-party libraries) are up to date by running `make git-submodule`.
-
-## Linux
-
-To ensure you are always up to date, you can just run `sudo util/qmk_install.sh`. That should always install all the dependencies needed. **This will run `apt-get upgrade`.**
-
-You can also install things manually, but this documentation might not be always up to date with all requirements.
-
-The current requirements are the following, but not all might be needed depending on what you do. Also note that some systems might not have all the dependencies available as packages, or they might be named differently.
-
-```
-build-essential
-gcc
-unzip
-wget
-zip
-gcc-avr
-binutils-avr
-avr-libc
-dfu-programmer
-dfu-util
-gcc-arm-none-eabi
-binutils-arm-none-eabi
-libnewlib-arm-none-eabi
-git
-```
-
-Install the dependencies with your favorite package manager.
-
-Debian / Ubuntu example:
-
-    sudo apt-get update
-    sudo apt-get install gcc unzip wget zip gcc-avr binutils-avr avr-libc dfu-programmer dfu-util gcc-arm-none-eabi binutils-arm-none-eabi libnewlib-arm-none-eabi
-
-Fedora / Red Hat example:
-
-    sudo dnf install gcc unzip wget zip dfu-util dfu-programmer avr-gcc avr-libc binutils-avr32-linux-gnu arm-none-eabi-gcc-cs arm-none-eabi-binutils-cs arm-none-eabi-newlib
-
-Arch / Manjaro example:
-
-    pacman -S base-devel gcc unzip wget zip avr-gcc avr-binutils avr-libc dfu-util arm-none-eabi-gcc arm-none-eabi-binutils arm-none-eabi-newlib git dfu-programmer dfu-util
-
-## Nix
-
-If you're on [NixOS](https://nixos.org/), or have Nix installed on Linux or macOS, run `nix-shell` from the repository root to get a build environment.
-
-By default, this will download compilers for both AVR and ARM. If you don't need both, disable the `avr` or `arm` arguments, e.g.:
-
-    nix-shell --arg arm false
-
-## macOS
-If you're using [Homebrew](http://brew.sh/), you can use the following commands:
-
-    brew tap osx-cross/avr
-    brew tap osx-cross/arm
-    brew update
-    brew install avr-gcc@8
-    brew link --force avr-gcc@8
-    brew install dfu-programmer
-    brew install dfu-util
-    brew install arm-gcc-bin@8
-    brew link --force arm-gcc-bin@8
-    brew install avrdude
-
-This is the recommended method. If you don't have homebrew, [install it!](http://brew.sh/) It's very much worth it for anyone who works in the command line. Note that the `make` and `make install` portion during the homebrew installation of `avr-gcc@8` can take over 20 minutes and exhibit high CPU usage.
-
-## Windows with msys2 (recommended)
-
-The best environment to use, for Windows Vista through any later version (tested on 7 and 10), is [msys2](http://www.msys2.org).
-
-* Install msys2 by downloading it and following the instructions here: http://www.msys2.org
-* Open the ``MSYS2 MingGW 64-bit`` shortcut
-* Navigate to your QMK repository. For example, if it's in the root of your c drive:
- * `$ cd /c/qmk_firmware`
-* Run `util/qmk_install.sh` and follow the prompts
-
-## Windows 10 (deprecated)
-These are the old instructions for Windows 10. We recommend you use [MSYS2 as outlined above](#windows-with-msys2-recommended).
-
-### Creators Update
-If you have Windows 10 with Creators Update or later, you can build and flash the firmware directly. Before the Creators Update, only building was possible. If you don't have it yet or if are unsure, follow [these instructions](https://support.microsoft.com/en-us/instantanswers/d4efb316-79f0-1aa1-9ef3-dcada78f3fa0/get-the-windows-10-creators-update).
-
-### Windows Subsystem for Linux
-In addition to the Creators Update, you need Windows 10 Subystem for Linux, so install it following [these instructions](http://www.howtogeek.com/249966/how-to-install-and-use-the-linux-bash-shell-on-windows-10/). If you already have the Windows 10 Subsystem for Linux from the Anniversary update it's recommended that you [upgrade](https://betanews.com/2017/04/14/upgrade-windows-subsystem-for-linux/) it to 16.04LTS, because some keyboards don't compile with the toolchains included in 14.04LTS. Note that you need to know what your are doing if you chose the `sudo do-release-upgrade` method.
-
-### Git
-If you already have cloned the repository on your Windows file system you can ignore this section.
-
-You will need to clone the repository to your Windows file system using the normal Git for Windows and **not** the WSL Git. So if you haven't installed Git before, [download](https://git-scm.com/download/win) and install it. Then [set it up](https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup), it's important that you setup the e-mail and user name, especially if you are planning to contribute.
-
-Once Git is installed, open the Git Bash command and change the directory to where you want to clone QMK; note that you have to use forward slashes, and that your c drive is accessed like this `/c/path/to/where/you/want/to/go`. Then run `git clone --recurse-submodules https://github.com/qmk/qmk_firmware`, this will create a new folder `qmk_firmware` as a subfolder of the current one.
-
-### Toolchain Setup
-The Toolchain setup is done through the Windows Subsystem for Linux, and the process is fully automated. If you want to do everything manually, there are no other instructions than the scripts themselves, but you can always open issues and ask for more information.
-
-1. Open "Bash On Ubuntu On Windows" from the start menu.
-2. Go to the directory where you cloned `qmk_firmware`. Note that the paths start with `/mnt/` in the WSL, so you have to write for example `cd /mnt/c/path/to/qmk_firmware`.
-3. Run `util/wsl_install.sh` and follow the on-screen instructions.
-4. Close the Bash command window, and re-open it.
-5. You are ready to compile and flash the firmware!
-
-### Some Important Things to Keep in Mind
-* You can run `util/wsl_install.sh` again to get all the newest updates.
-* Your QMK repository need to be on a Windows file system path, since WSL can't run executables outside it.
-* The WSL Git is **not** compatible with the Windows Git, so use the Windows Git Bash or a windows Git GUI for all Git operations
-* You can edit files either inside WSL or normally using Windows, but note that if you edit makefiles or shell scripts, make sure you are using an editor that saves the files with Unix line endings. Otherwise the compilation might not work.
-
-## Docker
-
-If this is a bit complex for you, Docker might be the turnkey solution you need. After installing [Docker CE](https://docs.docker.com/install/#supported-platforms), run the following command from the `qmk_firmware` directory to build a keyboard/keymap:
-```bash
-util/docker_build.sh keyboard:keymap
-# For example: util/docker_build.sh ergodox_ez:steno
-```
-This will compile the desired keyboard/keymap and leave the resulting `.hex` or `.bin` file in the QMK directory for you to flash. If `:keymap` is omitted, all keymaps are used. Note that the parameter format is the same as when building with `make`.
-
-You can also start the script without any parameters, in which case it will ask you to input the build parameters one by one, which you may find easier to use:
-```bash
-util/docker_build.sh
-# Reads parameters as input (leave blank for all keyboards/keymaps)
-```
-
-There is also support for building _and_ flashing the keyboard straight from Docker by specifying the `target` as well:
-```bash
-util/docker_build.sh keyboard:keymap:target
-# For example: util/docker_build.sh planck/rev6:default:flash
-```
-If you're on Linux, this should work out of the box. On Windows and macOS, it requires [Docker Machine](http://gw.tnode.com/docker/docker-machine-with-usb-support-on-windows-macos/) to be running. This is tedious to set up, so it's not recommended; use [QMK Toolbox](https://github.com/qmk/qmk_toolbox) instead.
-
-!> Docker for Windows requires [Hyper-V](https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v) to be enabled. This means that it cannot work on versions of Windows which don't have Hyper-V, such as Windows 7, Windows 8 and **Windows 10 Home**.
-
-## Vagrant
-If you have any problems building the firmware, you can try using a tool called Vagrant. It will set up a virtual computer with a known configuration that's ready-to-go for firmware building. OLKB does NOT host the files for this virtual computer. Details on how to set up Vagrant are in the [vagrant guide](getting_started_vagrant.md).

docs/getting_started_docker.md

@@ -0,0 +1,47 @@
+# Docker Quick Start
+
+This project includes a Docker workflow that will allow you to build a new firmware for your keyboard very easily without major changes to your primary operating system. This also ensures that when you clone the project and perform a build, you have the exact same environment as anyone else and the QMK build infrastructure. This makes it much easier for people to help you troubleshoot any issues you encounter.
+
+## Requirements
+
+The main prerequisite is a working `docker` install.
+* [Docker CE](https://docs.docker.com/install/#supported-platforms)
+
+## Usage
+
+Acquire a local copy of the QMK's repository (including submodules):
+
+```bash
+git clone --recurse-submodules https://github.com/qmk/qmk_firmware.git
+cd qmk_firmware
+```
+
+Run the following command to build a keymap:
+```bash
+util/docker_build.sh <keyboard>:<keymap>
+# For example: util/docker_build.sh planck/rev6:default
+```
+
+This will compile the desired keyboard/keymap and leave the resulting `.hex` or `.bin` file in the QMK directory for you to flash. If `:keymap` is omitted, all keymaps are used. Note that the parameter format is the same as when building with `make`.
+
+There is also support for building _and_ flashing the keyboard straight from Docker by specifying the `target` as well:
+
+```bash
+util/docker_build.sh keyboard:keymap:target
+# For example: util/docker_build.sh planck/rev6:default:flash
+```
+
+You can also start the script without any parameters, in which case it will ask you to input the build parameters one by one, which you may find easier to use:
+
+```bash
+util/docker_build.sh
+# Reads parameters as input (leave blank for all keyboards/keymaps)
+```
+
+## FAQ
+
+### Why can't I flash on Windows/macOS
+
+On Windows and macOS, it requires [Docker Machine](http://gw.tnode.com/docker/docker-machine-with-usb-support-on-windows-macos/) to be running. This is tedious to set up, so it's not recommended; use [QMK Toolbox](https://github.com/qmk/qmk_toolbox) instead.
+
+!> Docker for Windows requires [Hyper-V](https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v) to be enabled. This means that it cannot work on versions of Windows which don't have Hyper-V, such as Windows 7, Windows 8 and **Windows 10 Home**.

docs/getting_started_getting_help.md

@@ -1,15 +0,0 @@
-# Getting Help
-
-There are a lot of resources for getting help with QMK.
-
-## Realtime Chat
-
-You can find QMK developers and users on our main [Discord server](https://discord.gg/Uq7gcHh). There are specific channels in the server for chatting about the firmware, Toolbox, hardware, and configurator.
-
-## OLKB Subreddit
-
-The official QMK forum is [/r/olkb](https://reddit.com/r/olkb) on [reddit.com](https://reddit.com).
-
-## Github Issues
-
-You can open an [issue on GitHub](https://github.com/qmk/qmk_firmware/issues). This is especially handy when your issue will require long-term discussion or debugging.

docs/getting_started_vagrant.md

@@ -20,7 +20,6 @@ The "easy" way to flash the firmware is using a tool from your host OS:
 
 * [QMK Toolbox](https://github.com/qmk/qmk_toolbox) (recommended)
 * [Teensy Loader](https://www.pjrc.com/teensy/loader.html)
-* [Atmel FLIP](http://www.atmel.com/tools/flip.aspx)
 
 If you want to program via the command line you can uncomment the ['modifyvm'] lines in the Vagrantfile to enable the USB passthrough into Linux and then program using the command line tools like dfu-util/dfu-programmer or you can install the Teensy CLI version.
 

docs/hand_wire.md

@@ -1,114 +1,5 @@
 # Hand-Wiring Guide
 
-## Preamble: How a Keyboard Matrix Works (and why we need diodes)
-
-The collapsible section below covers why keyboards are wired the way they are, as outlined in this guide.  It isn't required reading to make your own hand wired keyboard, but provides background information.
-
-<details>
-
-<summary>Click for details</summary>
-
-Without a matrix circuit each switch would require its own wire directly to the controller.
-
-Simply put, when the circuit is arranged in rows and columns, if a key is pressed, a column wire makes contact with a row wire and completes a circuit. The keyboard controller detects this closed circuit and registers it as a key press.
-
-The microcontroller will be setup up via the firmware to send a logical 1 to the columns, one at a time, and read from the rows, all at once - this process is called matrix scanning. The matrix is a bunch of open switches that, by default, don't allow any current to pass through - the firmware will read this as no keys being pressed. As soon as you press one key down, the logical 1 that was coming from the column the keyswitch is attached to gets passed through the switch and to the corresponding row - check out the following 2x2 example:
-
-        Column 0 being scanned     Column 1 being scanned
-                  x                                   x
-                 col0     col1              col0     col1
-                  |        |                 |        |
-        row0 ---(key0)---(key1)    row0 ---(key0)---(key1)
-                  |        |                 |        |
-        row1 ---(key2)---(key3)    row1 ---(key2)---(key3)
-
-The `x` represents that the column/row associated has a value of 1, or is HIGH. Here, we see that no keys are being pressed, so no rows get an `x`. For one keyswitch, keep in mind that one side of the contacts is connected to its row, and the other, its column.
-
-When we press `key0`, `col0` gets connected to `row0`, so the values that the firmware receives for that row is `0b01` (the `0b` here means that this is a bit value, meaning all of the following digits are bits - 0 or 1 - and represent the keys in that column). We'll use this notation to show when a keyswitch has been pressed, to show that the column and row are being connected:
-
-        Column 0 being scanned     Column 1 being scanned
-                  x                                   x
-                 col0     col1              col0     col1
-                  |        |                 |        |
-      x row0 ---(-+-0)---(key1)    row0 ---(-+-0)---(key1)
-                  |        |                 |        |
-        row1 ---(key2)---(key3)    row1 ---(key2)---(key3)
-
-We can now see that `row0` has an `x`, so has the value of 1. As a whole, the data the firmware receives when `key0` is pressed is
-
-    col0: 0b01
-    col1: 0b00
-            │└row0
-            └row1
-
-A problem arises when you start pressing more than one key at a time. Looking at our matrix again, it should become pretty obvious:
-
-        Column 0 being scanned     Column 1 being scanned
-                  x                                   x
-                 col0     col1              col0     col1
-                  |        |                 |        |
-      x row0 ---(-+-0)---(-+-1)  x row0 ---(-+-0)---(-+-1)
-                  |        |                 |        |
-      x row1 ---(key2)---(-+-3)  x row1 ---(key2)---(-+-3)
-
-      Remember that this ^ is still connected to row1
-
-The data we get from that is:
-
-    col0: 0b11
-    col1: 0b11
-            │└row0
-            └row1
-
-Which isn't accurate, since we only have 3 keys pressed down, not all 4. This behavior is called ghosting, and only happens in odd scenarios like this, but can be much more common on a bigger keyboard. The way we can get around this is by placing a diode after the keyswitch, but before it connects to its row. A diode only allows current to pass through one way, which will protect our other columns/rows from being activated in the previous example. We'll represent a dioded matrix like this;
-
-        Column 0 being scanned     Column 1 being scanned
-                    x                                   x
-                  col0      col1              col0     col1
-                    │        │                 |        │
-                 (key0)   (key1)            (key0)   (key1)
-                  ! │      ! │               ! |      ! │
-        row0 ─────┴────────┘ │     row0 ─────┴────────┘ │
-                    │        │                 |        │
-                 (key2)   (key3)            (key2)   (key3)
-                  !        !                 !        !
-        row1 ─────┴────────┘       row1 ─────┴────────┘
-
-In practical applications, the black line of the diode will be placed facing the row, and away from the keyswitch - the `!` in this case is the diode, where the gap represents the black line. A good way to remember this is to think of this symbol: `>|`
-
-Now when we press the three keys, invoking what would be a ghosting scenario:
-
-        Column 0 being scanned     Column 1 being scanned
-                    x                                   x
-                  col0      col1              col0     col1
-                    │        │                 │        │
-                 (┌─┤0)   (┌─┤1)            (┌─┤0)   (┌─┤1)
-                  ! │      ! │               ! │      ! │
-      x row0 ─────┴────────┘ │   x row0 ─────┴────────┘ │
-                    │        │                 │        │
-                 (key2)   (┌─┘3)            (key2)   (┌─┘3)
-                  !        !                 !        !
-        row1 ─────┴────────┘     x row1 ─────┴────────┘
-
-Things act as they should! Which will get us the following data:
-
-    col0: 0b01
-    col1: 0b11
-            │└row0
-            └row1
-
-The firmware can then use this correct data to detect what it should do, and eventually, what signals it needs to send to the OS.
-
-Further reading:
-- [Wikipedia article](https://en.wikipedia.org/wiki/Keyboard_matrix_circuit)
-- [Deskthority article](https://deskthority.net/wiki/Keyboard_matrix)
-- [Keyboard Matrix Help by Dave Dribin (2000)](https://www.dribin.org/dave/keyboard/one_html/)
-- [How Key Matrices Works by PCBheaven](http://pcbheaven.com/wikipages/How_Key_Matrices_Works/) (animated examples)
-- [How keyboards work - QMK documentation](how_keyboards_work.md)
-
-</details>
-
-
 ## Parts list
 
 You will need: (where *x* is the number of keys on your planned keyboard)
@@ -141,29 +32,29 @@ Start by installing the switches and stabilisers in the plate. Depending on the
 
 If you are following a pre-existing handwire guide (e.g. for the keyboards in the [handwire firmware section](https://github.com/qmk/qmk_firmware/tree/master/keyboards/handwired) you can skip this step, just ensure you wire the matrix as described.
 
-What you want to achieve is one leg from each switch being attached to the corresponding switches next to it (rows) and the other leg being attached to the switches above and below it (columns) and a diode to one of the legs, mosy commonly this will be the leg attached to the rows, and the diode will face away from it (Column to Row) i.e. with the wire furthest from the black line on the diode connected to the switch (as current will only travel in one direction through a diode)
+What you want to achieve is one leg from each switch being attached to the corresponding switches next to it (rows) and the other leg being attached to the switches above and below it (columns) and a diode to one of the legs, mosy commonly this will be the leg attached to the rows, and the diode will face away from it (Column to Row) i.e. with the wire furthest from the black line on the diode connected to the switch (as current will only travel in one direction through a diode).
 
 It is fairly simple to plan for an ortholinear keyboard (like a Planck).
 
-![Example planck matrix](https://i.imgur.com/FRShcLD.png)
+![Example Planck matrix](https://i.imgur.com/FRShcLD.png)
 Image from [RoastPotatoes' "How to hand wire a Planck"](https://blog.roastpotatoes.co/guide/2015/11/04/how-to-handwire-a-planck/)
 
 But the larger and more complicated your keyboard, the more complex the matrix.  [Keyboard Firmware Builder](https://kbfirmware.com/) can help you plan your matrix layout (shown here with a basic fullsize ISO keyboard imported from [Keyboard Layout Editor](http://www.keyboard-layout-editor.com).
 
 ![Example ISO matrix](https://i.imgur.com/UlJ4ZDP.png)
 
- Bear in mind that the number of rows plus the number of columns can not exceed the number of I/O pins on your controller.  So the fullsize matrix shown above would be possible on a Proton C or Teensy++, but not on a regular Teensy or Pro Micro
+Bear in mind that the number of rows plus the number of columns can not exceed the number of I/O pins on your controller.  So the fullsize matrix shown above would be possible on a Proton C or Teensy++, but not on a regular Teensy or Pro Micro.
 
-#### Common Microcontroller Boards
+### Common Microcontroller Boards
 
 | Board         | Controller    | # I/O  | Pinout |
 | :------------ |:-------------:| ------:| ------ |
-| Pro Micro*     | ATmega32u4    |     20 | [link](https://learn.sparkfun.com/tutorials/pro-micro--fio-v3-hookup-guide/hardware-overview-pro-micro#Teensy++_2.0)       |
+| Pro Micro*    | ATmega32u4    |     20 | [link](https://learn.sparkfun.com/tutorials/pro-micro--fio-v3-hookup-guide/hardware-overview-pro-micro#Teensy++_2.0)       |
 | Teensy 2.0    | ATmega32u4    |     25 | [link](https://www.pjrc.com/teensy/pinout.html)       |
 | [QMK Proton C](https://qmk.fm/proton-c/)      | STM32F303xC   |     36 | [link 1](https://i.imgur.com/RhtrAlc.png), [2](https://deskthority.net/wiki/QMK_Proton_C)       |
 | Teensy++ 2.0  | AT90USB1286   |     46 | [link](https://www.pjrc.com/teensy/pinout.html#Teensy_2.0)       |
 
-*Elite C is essentially the same as a pro micro with a USB-C instead of Micro-USB
+*Elite C is essentially the same as a Pro Micro with a USB-C instead of Micro-USB
 
 There are also a number of boards designed specifically for handwiring that mount directly to a small number of switches and offer pinouts for the rest.  Though these are generally more expensive and may be more difficult to get hold of.
 
@@ -204,7 +95,7 @@ If you are planning a split keyboard (e.g. Dactyl) each half will require a cont
 
 There are a lot of soldering guides and tips available elsewhere but here are some of the most useful and relevant for hand wiring:
 
-To ensure a strong solder joint you want a good amount of contact between the solder and the 2 peices of metal you are connecting, a good way of doing this (though not required) is looping around pins or twisting wires together before applying solder.
+To ensure a strong solder joint you want a good amount of contact between the solder and the two pieces of metal you are connecting. A good way of doing this (though not required) is looping around pins or twisting wires together before applying solder.
 
 <img src="https://i.imgur.com/eHJjmnU.jpg" alt="Looped around rod" width="200"/> <img src="https://i.imgur.com/8nbxmmr.jpg?1" alt="Looped diode leg" width="200"/>
 
@@ -220,24 +111,11 @@ When you come to apply the solder, hold the soldering iron against the two surfa
 
 Don't hold the iron on the solder/joint longer than necessary. Heat will be conducted through the surfaces and can damage components (melt switch housings etc.).  Also, solder contains flux, which aids in ["wetting"](https://en.m.wikipedia.org/wiki/Wetting).  The longer heat is applied to the solder the more flux will evaporate meaning you may end up with a bad solder joint with peaks which, apart from looking bad, may also increase the risk of electrical shorts.
 
-The following collapsible section describes in detail how to solder rows using the bent diode technique and columns using short lengths of wire.
+#### Soldering the Diodes
 
-<details>
+Starting at the top-left switch, place the diode (with tweezers if you have them) on the switch so that the diode itself is vertically aligned, and the black line is facing toward you. The input lead of the diode should be touching the left contact on the switch, and the bent, output end should be facing to the right and resting on the switch there, like this:
 
-<summary>Click for details</summary>
-
-## Soldering the Diodes
-
-Starting at the top-left switch, place the diode (with tweezers if you have them) on the switch so that the diode itself is vertically aligned, and the black line is facing toward you. The straight end of the diode should be touching the left contact on the switch, and the bent end should be facing to the right and resting on the switch there, like this:
-
-```
-     │o
-    ┌┴┐         o
-    │ │    O
-    ├─┤
-    └┬┘
-     └─────────────
-```
+![soldering-diodes-01.png](https://raw.githubusercontent.com/noroadsleft/qmk_images/master/docs/hand_wire/soldering-diodes-01.png)
 
 Letting the diode rest, grab your solder, and touch both it and the soldering iron to the left contact at the same time - the rosin in the solder should make it easy for the solder to flow over both the diode and the keyswitch contact. The diode may move a little, and if it does, carefully position it back it place by grabbing the bent end of the diode - the other end will become hot very quickly. If you find that it's moving too much, using needle-nose pliers of some sort may help to keep the diode still when soldering.
 
@@ -247,20 +125,13 @@ After soldering things in place, it may be helpful to blow on the joint to push
 
 When the first diode is complete, the next one will need to be soldered to both the keyswitch, and the previous diode at the new elbow. That will look something like this:
 
-```
-     │o               │o
-    ┌┴┐         o    ┌┴┐         o
-    │ │    O         │ │    O
-    ├─┤              ├─┤
-    └┬┘              └┬┘
-     └────────────────┴─────────────
-```
+![soldering-diodes-02.png](https://raw.githubusercontent.com/noroadsleft/qmk_images/master/docs/hand_wire/soldering-diodes-02.png)
 
 After completing a row, use the wire cutters to trim the excess wire from the tops of the diodes, and from the right side on the final switch. This process will need to completed for each row you have.
 
 When all of the diodes are completely soldered, it's a good idea to quickly inspect each one to ensure that your solder joints are solid and sturdy - repairing things after this is possible, but more difficult.
 
-## Soldering the Columns
+#### Soldering the Columns
 
 You'll have some options in the next process - it's a good idea to insulate the column wires (since the diodes aren't), but if you're careful enough, you can use exposed wires for the columns - it's not recommended, though. If you're using single-cored wire, stripping the plastic off of the whole wire and feeding it back on is probably the best option, but can be difficult depending on the size and materials. You'll want to leave parts of the wire exposed where you're going to be solder it onto the keyswitch.
 
@@ -270,9 +141,7 @@ Before beginning to solder, it helps to have your wire pre-bent (if using single
 
 If you're not using any insulation, you can try to keep the column wires elevated, and solder them near the tips of the keyswitch contacts - if the wires are sturdy enough, they won't short out to the row wiring an diodes.
 
-</details>
-
-# Wiring up the controller
+## Wiring up the controller
 
 Now that the matrix itself is complete, it's time to connect what you've done to the microcontroller board.
 
@@ -280,15 +149,16 @@ Place the microcontroller where you want it to be located, give thought to mount
 
 Find the pinout/documentation for your microcontroller board ([links here](#common-microcontroller-boards)) and make a note of all the digital I/O pins on it (note that on some controllers, like the teensy, analogue I/O can double as digital) as these are the pins you want to connect your wires to.
 
-<details>
+----
 
-<summary>Specific instructions for the Teensy 2.0</summary>
+### Specific instructions for the Teensy 2.0
 
- There are some pins on the Teensy that are special, like D6 (the LED on the chip), or some of the UART, SPI, I2C, or PWM channels, but only avoid those if you're planning something in addition to a keyboard. If you're unsure about wanting to add something later, you should have enough pins in total to avoid a couple.
+There are some pins on the Teensy that are special, like D6 (the LED on the chip), or some of the UART, SPI, I2C, or PWM channels, but only avoid those if you're planning something in addition to a keyboard. If you're unsure about wanting to add something later, you should have enough pins in total to avoid a couple.
 
 The pins you'll absolutely have to avoid, as with any controller, are: GND, VCC, AREF, and RST - all the others are usable and accessible in the firmware.
 
-</details>
+----
+
 
 Cut wires to the length of the distance from the a point on each column/row to the controller.  You can solder anywhere along the row, as long as it's after the diode - soldering before the diode (on the keyswitch side) will cause that row not to work.
 
@@ -301,150 +171,32 @@ As you solder the wires to the controller make a note of which row/column is goi
 As you move along, be sure that the controller is staying in place - recutting and soldering the wires is a pain!
 
 
-
-# Getting Some Basic Firmware Set Up
+## Getting Some Basic Firmware Set Up
 
 From here, you should have a working keyboard once you program a firmware.
 
 Simple firmware can be created easily using the [Keyboard Firmware Builder](https://kbfirmware.com/) website.  Recreate your layout using [Keyboard Layout Editor](http://www.keyboard-layout-editor.com), import it and recreate the matrix (if not already done as part of [planning the matrix](#planning-the-matrix).
 
-Go through the rest of the tabs, assigning keys until you get to the last one where you can compile and download your firmware.  The .hex file can be flashed straight onto your keyboard, and the .zip of source files can be modified for advanced functionality and compiled locally using the method described in the collapsable section below, or using the more comprehensive [getting started guide.](newbs_getting_started)
+Go through the rest of the tabs, assigning keys until you get to the last one where you can compile and download your firmware.  The .hex file can be flashed straight onto your keyboard, and the .zip of source files can be modified for advanced functionality and compiled locally using the method described in [Building Your First Firmware](newbs_building_firmware?id=build-your-firmware).
 
+The source given by Keyboard Firmware Builder is QMK, but is based on a version of QMK from early 2017. To compile the code from your .zip file in a modern version of QMK Firmware, you'll need to open the .zip and follow these instructions:
 
-<details>
-
-<summary>Creating and compiling your firmware locally (command line method)</summary>
-
-To start out, download [the firmware](https://github.com/qmk/qmk_firmware/) - We'll be doing a lot from the Terminal/command prompt, so get that open, along with a decent text editor like [Sublime Text](http://www.sublimetext.com/) (paid) or [Visual Studio Code](https://code.visualstudio.com) (free).
-
-The first thing we're going to do is create a new keyboard. In your terminal, run this command, which will ask you some questions and generate a basic keyboard project:
-
-```
-./util/new_keyboard.sh
-```
-
-You'll want to navigate to the `keyboards/<project_name>/` folder by typing, like the print-out from the script specifies:
-
-```
-cd keyboards/<project_name>
-```
-
-### `config.h`
-
-The first thing you're going to want to modify is the `config.h` file. Find `MATRIX_ROWS` and `MATRIX_COLS` and change their definitions to match the dimensions of your keyboard's matrix.
-
-Farther down are `MATRIX_ROW_PINS` and `MATRIX_COL_PINS`. Change their definitions to match how you wired up your matrix (looking from the top of the keyboard, the rows run top-to-bottom and the columns run left-to-right). Likewise, change the definition of `UNUSED_PINS` to match the pins you did not use (this will save power).
-
-### `<project_name>.h`
-
-The next file you'll want to look at is `<project_name>.h`. You're going to want to rewrite the `LAYOUT` definition - the format and syntax here is extremely important, so pay attention to how things are setup. The first half of the definition are considered the arguments - this is the format that you'll be following in your keymap later on, so you'll want to have as many k*xy* variables here as you do keys. The second half is the part that the firmware actually looks at, and will contain gaps depending on how you wired your matrix.
-
-We'll dive into how this will work with the following example. Say we have a keyboard like this:
-
-```
-    ┌───┬───┬───┐
-    │   │   │   │
-    ├───┴─┬─┴───┤
-    │     │     │
-    └─────┴─────┘
-```
-
-This can be described by saying the top row is 3 1u keys, and the bottom row is 2 1.5u keys. The difference between the two rows is important, because the bottom row has an unused column spot (3 v 2). Let's say that this is how we wired the columns:
-
-```
-    ┌───┬───┬───┐
-    │ ┋ │ ┋ │ ┋ │
-    ├─┋─┴─┬─┴─┋─┤
-    │ ┋   │   ┋ │
-    └─────┴─────┘
-```
-
-The middle column is unused on the bottom row in this example. Our `LAYOUT` definition would look like this:
-
-```
-    #define LAYOUT( \
-        k00, k01, k02, \
-          k10,  k11,   \
-    ) \
-    { \
-        { k00, k01,   k02 }, \
-        { k10, KC_NO, k11 }, \
+1. Extract the `kb` folder to `qmk_firmware/keyboards/handwired/`.
+2. Open the extracted `kb` folder, then proceed to the `keymaps/default/` folder, and open `keymap.c`.
+3. Locate and delete the `action_get_macro` code block:
+   ```
+    const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt) {
+        ...
+        return MACRO_NONE;
     }
-```
-
-Notice how the top half is spaced to resemble our physical layout - this helps us understand which keys are associated with which columns. The bottom half uses the keycode `KC_NO` where there is no keyswitch wired in. It's easiest to keep the bottom half aligned in a grid to help us make sense of how the firmware actually sees the wiring.
-
-Let's say that instead, we wired our keyboard like this (a fair thing to do):
-
-```
-    ┌───┬───┬───┐
-    │ ┋ │  ┋│ ┋ │
-    ├─┋─┴─┬┋┴───┤
-    │ ┋   │┋    │
-    └─────┴─────┘
-```
-
-This would require our `LAYOUT` definition to look like this:
-
-```
-    #define LAYOUT( \
-        k00, k01, k02, \
-          k10,  k11,   \
-    ) \
-    { \
-        { k00, k01, k02   }, \
-        { k10, k11, KC_NO }, \
-    }
-```
-
-Notice how the `k11` and `KC_NO` switched places to represent the wiring, and the unused final column on the bottom row. Sometimes it'll make more sense to put a keyswitch on a particular column, but in the end, it won't matter, as long as all of them are accounted for. You can use this process to write out the `LAYOUT` for your entire keyboard - be sure to remember that your keyboard is actually backwards when looking at the underside of it.
-
-### `keymaps/<variant>/default.c`
-
-This is the actual keymap for your keyboard, and the main place you'll make changes as you perfect your layout. `default.c` is the file that gets pull by default when typing `make`, but you can make other files as well, and specify them by typing `make handwired/<keyboard>:<variant>`, which will pull `keymaps/<variant>/keymap.c`.
-
-The basis of a keymap is its layers - by default, layer 0 is active. You can activate other layers, the highest of which will be referenced first. Let's start with our base layer.
-
-Using our previous example, let's say we want to create the following layout:
-
-```
-    ┌───┬───┬───┐
-    │ A │ 1 │ H │
-    ├───┴─┬─┴───┤
-    │ TAB │ SPC │
-    └─────┴─────┘
-```
-
-This can be accomplished by using the following `keymaps` definition:
-
-```
-const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
-    [0] = LAYOUT( /* Base */
-      KC_A,  KC_1,  KC_H, \
-        KC_TAB,  KC_SPC   \
-    ),
-};
-```
-
-Note that the layout of the keycodes is similar to the physical layout of our keyboard - this make it much easier to see what's going on. A lot of the keycodes should be fairly obvious, but for a full list of them, check out [Keycodes](keycodes.md) - there are also a lot of aliases to condense your keymap file.
-
-It's also important to use the `LAYOUT` function we defined earlier - this is what allows the firmware to associate our intended readable keymap with the actual wiring.
-
-## Compiling Your Firmware
-
-After you've written out your entire keymap, you're ready to get the firmware compiled and onto your Teensy. Before compiling, you'll need to get your [development environment set-up](getting_started_build_tools.md) - you can skip the dfu-programmer instructions, but you'll need to download and install the [Teensy Loader](https://www.pjrc.com/teensy/loader.html) to get the firmware on your Teensy.
-
-Once everything is installed, running `make` in the terminal should get you some output, and eventually a `<project_name>.hex` file in that folder. If you're having trouble with this step, see the end of the guide for the trouble-shooting section.
-
-Once you have your `<project_name>.hex` file, open up the Teensy loader application, and click the file icon. From here, navigate to your `QMK/keyboards/<project_name>/` folder, and select the `<project_name>.hex` file. Plug in your keyboard and press the button on the Teensy - you should see the LED on the device turn off once you do. The Teensy Loader app will change a little, and the buttons should be clickable - click the download button (down arrow), and then the reset button (right arrow), and your keyboard should be ready to go!
-
-</details>
+   ```
+4. Save and close `keymap.c`.
 
 ## Flashing the Firmware
 
-Install [QMK toolbox](https://github.com/qmk/qmk_toolbox).
+Install [QMK Toolbox](https://github.com/qmk/qmk_toolbox).
 
-![QMK Toolbox](https://i.imgur.com/86Cz30H.png)
+![QMK Toolbox](https://raw.githubusercontent.com/noroadsleft/qmk_images/master/docs/hand_wire/qmk_toolbox.png "QMK Toolbox 0.0.16 on Windows 8.1")
 
 Under "Local File" navigate to your newly created .hex file.  Under "Microcontroller", select the corresponding one for your controller board (common ones available [here](#common-microcontroller-boards)).
 
@@ -453,20 +205,20 @@ Plug in your keyboard and press the reset button (or short the Reset and Ground
 
 ## Testing Your Firmware
 
-Use a website such as [keyboard tester](https://www.keyboardtester.com/tester.html)/[keyboard checker](http://keyboardchecker.com/) or just open a text editor and try typing - you should get the characters that you put into your keymap. Test each key, and make a note of the ones that aren't working. Here's a quick trouble-shooting guide for non-working keys:
+Use a website such as [QMK Configurator's Keyboard Tester](https://config.qmk.fm/#/test), [Keyboard Tester](https://www.keyboardtester.com/tester.html), or [Keyboard Checker](http://keyboardchecker.com/) or just open a text editor and try typing - you should get the characters that you put into your keymap. Test each key, and make a note of the ones that aren't working. Here's a quick trouble-shooting guide for non-working keys:
 
-0. Flip the keyboard back over and short the keyswitch's contacts with a piece wire - this will eliminate the possibility of the keyswitch being bad and needing to be replaced.
-1. Check the solder points on the keyswitch - these need to be plump and whole. If you touch it with a moderate amount of force and it comes apart, it's not strong enough.
-2. Check the solder joints on the diode - if the diode is loose, part of your row may register, while the other may not.
-3. Check the solder joints on the columns - if your column wiring is loose, part or all of the column may not work.
-4. Check the solder joints on both sides of the wires going to/from the Teensy - the wires need to be fully soldered and connect to both sides.
-5. Check the `<project_name>.h` file for errors and incorrectly placed `KC_NO`s - if you're unsure where they should be, instead duplicate a k*xy* variable.
-6. Check to make sure you actually compiled the firmware and flashed the Teensy correctly. Unless you got error messages in the terminal, or a pop-up during flashing, you probably did everything correctly.
-7. Use a multimeter to check that the switch is actually closing when actuated (completing the circuit when pressed down).
+1. Flip the keyboard back over and short the keyswitch's contacts with a piece wire - this will eliminate the possibility of the keyswitch being bad and needing to be replaced.
+2. Check the solder points on the keyswitch - these need to be plump and whole. If you touch it with a moderate amount of force and it comes apart, it's not strong enough.
+3. Check the solder joints on the diode - if the diode is loose, part of your row may register, while the other may not.
+4. Check the solder joints on the columns - if your column wiring is loose, part or all of the column may not work.
+5. Check the solder joints on both sides of the wires going to/from the Teensy - the wires need to be fully soldered and connect to both sides.
+6. Check the `<project_name>.h` file for errors and incorrectly placed `KC_NO`s - if you're unsure where they should be, instead duplicate a k*xy* variable.
+7. Check to make sure you actually compiled the firmware and flashed the Teensy correctly. Unless you got error messages in the terminal, or a pop-up during flashing, you probably did everything correctly.
+8. Use a multimeter to check that the switch is actually closing when actuated (completing the circuit when pressed down).
 
 If you've done all of these things, keep in mind that sometimes you might have had multiple things affecting the keyswitch, so it doesn't hurt to test the keyswitch by shorting it out at the end.
 
-# Finishing up
+## Finishing up
 
 Once you have confirmed that the keyboard is working, if you have used a seperate (non handwire specific) controller you will want to secure it in place.  This can be done in many different ways e.g. hot glue, double sided sticky tape, 3D printed caddy, electrical tape.
 
@@ -474,7 +226,7 @@ If you found this fullfilling you could experiment by adding additional features
 
 There are a lot of possibilities inside the firmware - explore [docs.qmk.fm](http://docs.qmk.fm) for a full feature list, and dive into the different keyboards to see how people use all of them. You can always stop by [the OLKB subreddit](http://reddit.com/r/olkb) or [QMK Discord](https://discord.gg/Uq7gcHh) for help!
 
-# Links to other guides:
+## Links to Other Guides
 
 - [matt3o's step by step guide (BrownFox build)](https://deskthority.net/viewtopic.php?f=7&t=6050) also his [website](https://matt3o.com/hand-wiring-a-custom-keyboard/) and [video guide](https://www.youtube.com/watch?v=LVzpsjFWPP4)
 - [Cribbit's "Modern hand wiring guide - stronger, cleaner, easier"](https://geekhack.org/index.php?topic=87689.0) 
@@ -483,4 +235,10 @@ There are a lot of possibilities inside the firmware - explore [docs.qmk.fm](htt
 - [Masterzen's "Handwired keyboard build log"](http://www.masterzen.fr/2018/12/16/handwired-keyboard-build-log-part-1/)
 
 
+# Legacy Content
 
+This page used to include more content. We have moved a section that used to be part of this page its own page. Everything below this point is simply a redirect so that people following old links on the web find what they're looking for.
+
+## Preamble: How a Keyboard Matrix Works (and why we need diodes) :id=preamble-how-a-keyboard-matrix-works-and-why-we-need-diodes
+
+* [How a Keyboard Matrix Works](how_a_matrix_works.md)

docs/hardware.md

@@ -1,8 +0,0 @@
-# Hardware
-
-QMK runs on a variety of hardware. If your processor can be targeted by [LUFA](http://www.fourwalledcubicle.com/LUFA.php) or [ChibiOS](http://www.chibios.com) you can probably get QMK running on it. This section explores getting QMK running on, and communicating with, hardware of all kinds.
-
-* [Keyboard Guidelines](hardware_keyboard_guidelines.md)
-* [AVR Processors](hardware_avr.md)
-* ARM Processors (TBD)
-* [Drivers](hardware_drivers.md)

docs/hardware_drivers.md

@@ -33,3 +33,7 @@ Support for up to 2 drivers. Each driver impliments 2 charlieplex matrices to in
 ## IS31FL3733
 
 Support for up to a single driver with room for expansion. Each driver can control 192 individual LEDs or 64 RGB LEDs. For more information on how to setup the driver see the [RGB Matrix](feature_rgb_matrix.md) page.
+
+## 24xx series external I2C EEPROM
+
+Support for an external I2C-based EEPROM instead of using the on-chip EEPROM. For more information on how to setup the driver see the [EEPROM Driver](eeprom_driver.md) page.

docs/hardware_keyboard_guidelines.md

@@ -61,10 +61,76 @@ This file is used by the [QMK API](https://github.com/qmk/qmk_api). It contains
 
 All projects need to have a `config.h` file that sets things like the matrix size, product name, USB VID/PID, description and other settings. In general, use this file to set essential information and defaults for your keyboard that will always work.
 
+The `config.h` files can also be placed in sub-folders, and the order in which they are read is as follows:
+
+* `keyboards/top_folder/config.h`
+  * `keyboards/top_folder/sub_1/config.h`
+    * `keyboards/top_folder/sub_1/sub_2/config.h`
+      * `keyboards/top_folder/sub_1/sub_2/sub_3/config.h`
+        * `keyboards/top_folder/sub_1/sub_2/sub_3/sub_4/config.h`
+          * `users/a_user_folder/config.h`
+          * `keyboards/top_folder/keymaps/a_keymap/config.h`
+        * `keyboards/top_folder/sub_1/sub_2/sub_3/sub_4/post_config.h`
+      * `keyboards/top_folder/sub_1/sub_2/sub_3/post_config.h`
+    * `keyboards/top_folder/sub_1/sub_2/post_config.h`
+  * `keyboards/top_folder/sub_1/post_config.h`
+* `keyboards/top_folder/post_config.h`
+
+The `post_config.h` file can be used for additional post-processing, depending on what is specified in the `config.h` file. For example, if you define the `IOS_DEVICE_ENABLE` macro in your keymap-level `config.h` file as follows, you can configure more detailed settings accordingly in the `post_config.h` file:
+
+* `keyboards/top_folder/keymaps/a_keymap/config.h`
+  ```c
+  #define IOS_DEVICE_ENABLE
+  ```
+* `keyboards/top_folder/post_config.h`
+  ```c
+  #ifndef IOS_DEVICE_ENABLE
+    // USB_MAX_POWER_CONSUMPTION value for this keyboard
+    #define USB_MAX_POWER_CONSUMPTION 400
+  #else
+    // fix iPhone and iPad power adapter issue
+    // iOS device need lessthan 100
+    #define USB_MAX_POWER_CONSUMPTION 100
+  #endif
+  
+  #ifdef RGBLIGHT_ENABLE
+    #ifndef IOS_DEVICE_ENABLE
+      #define RGBLIGHT_LIMIT_VAL 200
+      #define RGBLIGHT_VAL_STEP 17
+    #else
+      #define RGBLIGHT_LIMIT_VAL 35
+      #define RGBLIGHT_VAL_STEP 4
+    #endif
+    #ifndef RGBLIGHT_HUE_STEP
+      #define RGBLIGHT_HUE_STEP 10
+    #endif
+    #ifndef RGBLIGHT_SAT_STEP
+      #define RGBLIGHT_SAT_STEP 17
+    #endif
+  #endif
+  ```
+
+?> If you define options using `post_config.h` as in the above example, you should not define the same options in the keyboard- or user-level `config.h`.
+
 ### `rules.mk`
 
 The presence of this file means that the folder is a keyboard target and can be used in `make` commands. This is where you setup the build environment for your keyboard and configure the default set of features.
 
+The `rules.mk` file can also be placed in a sub-folder, and its reading order is as follows:
+
+* `keyboards/top_folder/rules.mk`
+  * `keyboards/top_folder/sub_1/rules.mk`
+    * `keyboards/top_folder/sub_1/sub_2/rules.mk`
+      * `keyboards/top_folder/sub_1/sub_2/sub_3/rules.mk`
+        * `keyboards/top_folder/sub_1/sub_2/sub_3/sub_4/rules.mk`
+          * `keyboards/top_folder/keymaps/a_keymap/rules.mk`
+          * `users/a_user_folder/rules.mk`
+* `common_features.mk`
+
+Many of the settings written in the `rules.mk` file are interpreted by `common_features.mk`, which sets the necessary source files and compiler options.
+
+?> See `build_keyboard.mk` and `common_features.mk` for more details.
+
 ### `<keyboard_name.c>`
 
 This is where you will write custom code for your keyboard. Typically you will write code to initialize and interface with the hardware in your keyboard. If your keyboard consists of only a key matrix with no LEDs, speakers, or other auxiliary hardware this file can be blank.

docs/he-il/_summary.md

@@ -93,7 +93,7 @@
   * [Macros](he-il/feature_macros.md)
   * [Mouse Keys](he-il/feature_mouse_keys.md)
   * [OLED Driver](he-il/feature_oled_driver.md)
-  * [One Shot Keys](he-il/feature_advanced_keycodes.md#one-shot-keys)
+  * [One Shot Keys](he-il/one_shot_keys.md)
   * [Pointing Device](he-il/feature_pointing_device.md)
   * [PS/2 Mouse](he-il/feature_ps2_mouse.md)
   * [RGB Lighting](he-il/feature_rgblight.md)
@@ -114,6 +114,7 @@
   * [מדריך לצריבת ISP](he-il/isp_flashing_guide.md)
   * [מדריך לדיבאגינג ARM](he-il/arm_debugging.md)
   * [מנהל התקן I2C](he-il/i2c_driver.md)
+  * [מנהל התקן SPI](he-il/spi_driver.md)
   * [בקרת GPIO](he-il/internals_gpio_control.md)
   * [המרת Proton C](he-il/proton_c_conversion.md)
 
@@ -124,7 +125,7 @@
 * נושאים נוספים
   * [שימוש ב - Eclipse עם QMK](he-il/other_eclipse.md)
   * [שימוש ב - VSCode עם QMK](he-il/other_vscode.md)
-  * [תמיכה](he-il/support.md)
+  * [תמיכה](he-il/getting_started_getting_help.md)
   * [כיצד להוסיף תרגום](he-il/translating.md)
 
 * QMK מבפנים (בתהליך)

docs/he-il/becoming_a_qmk_collaborator.md

@@ -1,11 +0,0 @@
-<div dir="rtl" markdown="1">
-# איך להפוך לשותף של QMK
-
-שותף של QMK הוא יצרן מקלדות או מעצב שמעוניין בלעזור ל-QMK לגדול ולתמוך במקלד(ו)ת שלהם, ולעודד את המשתמשים והצרכנים להוסיף יכולות, רעיונות ומיפויים. אנחנו תמיד מחפשים עוד מקלדות ומשתפי פעולה, אבל אנחנו מבקשים שיעמדו בדרישות הבאות:
-
-* **קיום לוח PCB למכירה.** לצערינו, יש יותר מידי הסתבכויות ובעיות עם מקלדות המחווטות ידנית.
-* **תחזוק המקלדת ב-QMK.** זה אולי רק ידרוש הגדרה בסיסית כדי לגרום למקלדת לעבוד, אבל זה גם יכול לכלול התאמה של שינויים בקוד הליבה של QMK שיכול לשבור קוד ייחודי שלכם.
-* **אישור ומיזוג Pull Requests של מיפויי מקלדת עבור המקלדת** אנחנו רוצים לעודד משתמשים לתרום את מיפויי המקלדת שלהם לאחרים כדי לעזור לאחרים להתחיל ליצור את שלהם.
-
-אם אתם עומדים בדרישות הללו, שלחו לנו מייל לכתובת  hello@qmk.fm עם מבוא וקישורים עבור המקלדת שלכם.
-</div>

docs/how_a_matrix_works.md

@@ -0,0 +1,99 @@
+# How a Keyboard Matrix Works
+
+Keyboard switch matrices are arranged in rows and columns. Without a matrix circuit, each switch would require its own wire directly to the controller.
+
+When the circuit is arranged in rows and columns, if a key is pressed, a column wire makes contact with a row wire and completes a circuit. The keyboard controller detects this closed circuit and registers it as a key press.
+
+The microcontroller will be set up via the firmware to send a logical 1 to the columns, one at a time, and read from the rows, all at once - this process is called matrix scanning. The matrix is a bunch of open switches that, by default, don't allow any current to pass through - the firmware will read this as no keys being pressed. As soon as you press one key down, the logical 1 that was coming from the column the keyswitch is attached to gets passed through the switch and to the corresponding row - check out the following 2x2 example:
+
+        Column 0 being scanned     Column 1 being scanned
+                  x                                   x
+                 col0     col1              col0     col1
+                  |        |                 |        |
+        row0 ---(key0)---(key1)    row0 ---(key0)---(key1)
+                  |        |                 |        |
+        row1 ---(key2)---(key3)    row1 ---(key2)---(key3)
+
+The `x` represents that the column/row associated has a value of 1, or is HIGH. Here, we see that no keys are being pressed, so no rows get an `x`. For one keyswitch, keep in mind that one side of the contacts is connected to its row, and the other, its column.
+
+When we press `key0`, `col0` gets connected to `row0`, so the values that the firmware receives for that row is `0b01` (the `0b` here means that this is a bit value, meaning all of the following digits are bits - 0 or 1 - and represent the keys in that column). We'll use this notation to show when a keyswitch has been pressed, to show that the column and row are being connected:
+
+        Column 0 being scanned     Column 1 being scanned
+                  x                                   x
+                 col0     col1              col0     col1
+                  |        |                 |        |
+      x row0 ---(-+-0)---(key1)    row0 ---(-+-0)---(key1)
+                  |        |                 |        |
+        row1 ---(key2)---(key3)    row1 ---(key2)---(key3)
+
+We can now see that `row0` has an `x`, so has the value of 1. As a whole, the data the firmware receives when `key0` is pressed is:
+
+    col0: 0b01
+    col1: 0b00
+            │└row0
+            └row1
+
+A problem arises when you start pressing more than one key at a time. Looking at our matrix again, it should become pretty obvious:
+
+        Column 0 being scanned     Column 1 being scanned
+                  x                                   x
+                 col0     col1              col0     col1
+                  |        |                 |        |
+      x row0 ---(-+-0)---(-+-1)  x row0 ---(-+-0)---(-+-1)
+                  |        |                 |        |
+      x row1 ---(key2)---(-+-3)  x row1 ---(key2)---(-+-3)
+
+      Remember that this ^ is still connected to row1
+
+The data we get from that is:
+
+    col0: 0b11
+    col1: 0b11
+            │└row0
+            └row1
+
+Which isn't accurate, since we only have 3 keys pressed down, not all 4. This behavior is called ghosting, and only happens in odd scenarios like this, but can be much more common on a bigger keyboard. The way we can get around this is by placing a diode after the keyswitch, but before it connects to its row. A diode only allows current to pass through one way, which will protect our other columns/rows from being activated in the previous example. We'll represent a dioded matrix like this;
+
+        Column 0 being scanned     Column 1 being scanned
+                    x                                   x
+                  col0      col1              col0     col1
+                    │        │                 |        │
+                 (key0)   (key1)            (key0)   (key1)
+                  ! │      ! │               ! |      ! │
+        row0 ─────┴────────┘ │     row0 ─────┴────────┘ │
+                    │        │                 |        │
+                 (key2)   (key3)            (key2)   (key3)
+                  !        !                 !        !
+        row1 ─────┴────────┘       row1 ─────┴────────┘
+
+In practical applications, the black line of the diode will be placed facing the row, and away from the keyswitch - the `!` in this case is the diode, where the gap represents the black line. A good way to remember this is to think of this symbol: `>|`
+
+Now when we press the three keys, invoking what would be a ghosting scenario:
+
+        Column 0 being scanned     Column 1 being scanned
+                    x                                   x
+                  col0      col1              col0     col1
+                    │        │                 │        │
+                 (┌─┤0)   (┌─┤1)            (┌─┤0)   (┌─┤1)
+                  ! │      ! │               ! │      ! │
+      x row0 ─────┴────────┘ │   x row0 ─────┴────────┘ │
+                    │        │                 │        │
+                 (key2)   (┌─┘3)            (key2)   (┌─┘3)
+                  !        !                 !        !
+        row1 ─────┴────────┘     x row1 ─────┴────────┘
+
+Things act as they should! Which will get us the following data:
+
+    col0: 0b01
+    col1: 0b11
+            │└row0
+            └row1
+
+The firmware can then use this correct data to detect what it should do, and eventually, what signals it needs to send to the OS.
+
+Further reading:
+- [Wikipedia article](https://en.wikipedia.org/wiki/Keyboard_matrix_circuit)
+- [Deskthority article](https://deskthority.net/wiki/Keyboard_matrix)
+- [Keyboard Matrix Help by Dave Dribin (2000)](https://www.dribin.org/dave/keyboard/one_html/)
+- [How Key Matrices Works by PCBheaven](http://pcbheaven.com/wikipages/How_Key_Matrices_Works/) (animated examples)
+- [How keyboards work - QMK documentation](how_keyboards_work.md)

docs/i2c_driver.md

@@ -1,33 +1,46 @@
-# I2C Master Driver
+# I2C Master Driver :id=i2c-master-driver
 
 The I2C Master drivers used in QMK have a set of common functions to allow portability between MCUs.
 
-## Available functions
+## An important note on I2C Addresses :id=note-on-i2c-addresses
+
+All of the addresses expected by this driver should be pushed to the upper 7 bits of the address byte.  Setting
+the lower bit (indicating read/write) will be done by the respective functions.  Almost all I2C addresses listed 
+on datasheets and the internet will be represented as 7 bits occupying the lower 7 bits and will need to be
+shifted to the left (more significant) by one bit.  This is easy to do via the bitwise shift operator `<< 1`.
+
+You can either do this on each call to the functions below, or once in your definition of the address.  For example if your device has an address of `0x18`:
+
+`#define MY_I2C_ADDRESS (0x18 << 1)`
+
+See https://www.robot-electronics.co.uk/i2c-tutorial for more information about I2C addressing and other technical details.
+
+## Available functions :id=available-functions
 
 |Function                                                                                                          |Description                                                                                                                                                                  |
 |------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 |`void i2c_init(void);`                                                                                            |Initializes the I2C driver. This function should be called once before any transaction is initiated.                                                                         |
-|`uint8_t i2c_start(uint8_t address, uint16_t timeout);`                                                                             |Starts an I2C transaction. Address is the 7-bit slave address without the direction bit.                                                                                     |
-|`uint8_t i2c_transmit(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout);`                        |Transmit data over I2C. Address is the 7-bit slave address without the direction. Returns status of transaction.                                                             |
-|`uint8_t i2c_receive(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout);`                         |Receive data over I2C. Address is the 7-bit slave address without the direction. Saves number of bytes specified by `length` in `data` array. Returns status of transaction. |
-|`uint8_t i2c_writeReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);`       |Same as the `i2c_transmit` function but `regaddr` sets where in the slave the data will be written.                                                                          |
-|`uint8_t i2c_readReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);`        |Same as the `i2c_receive` function but `regaddr` sets from where in the slave the data will be read.                                                                         |
-|`uint8_t i2c_stop(void);`                                                                                         |Ends an I2C transaction.                                                                                                                                                     |
+|`i2c_status_t i2c_start(uint8_t address, uint16_t timeout);`                                                                             |Starts an I2C transaction. Address is the 7-bit slave address without the direction bit.                                                                                     |
+|`i2c_status_t i2c_transmit(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout);`                        |Transmit data over I2C. Address is the 7-bit slave address without the direction. Returns status of transaction.                                                             |
+|`i2c_status_t i2c_receive(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout);`                         |Receive data over I2C. Address is the 7-bit slave address without the direction. Saves number of bytes specified by `length` in `data` array. Returns status of transaction. |
+|`i2c_status_t i2c_writeReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);`       |Same as the `i2c_transmit` function but `regaddr` sets where in the slave the data will be written.                                                                          |
+|`i2c_status_t i2c_readReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);`        |Same as the `i2c_receive` function but `regaddr` sets from where in the slave the data will be read.                                                                         |
+|`i2c_status_t i2c_stop(void);`                                                                                         |Ends an I2C transaction.                                                                                                                                                     |
 
-### Function Return
+### Function Return :id=function-return
 
 All the above functions, except `void i2c_init(void);` return the following truth table:
 
-|Return Value   |Description                                        |
-|---------------|---------------------------------------------------|
-|0              |Operation executed successfully.                   |
-|-1             |Operation failed.                                  |
-|-2             |Operation timed out.                               |
+|Return Constant     |Value|Description                     |
+|--------------------|-----|--------------------------------|
+|`I2C_STATUS_SUCCESS`|0    |Operation executed successfully.|
+|`I2C_STATUS_ERROR`  |-1   |Operation failed.               |
+|`I2C_STATUS_TIMEOUT`|-2   |Operation timed out.            |
 
 
-## AVR
+## AVR :id=avr
 
-### Configuration
+### Configuration :id=avr-configuration
 
 The following defines can be used to configure the I2C master driver.
 
@@ -37,12 +50,12 @@ The following defines can be used to configure the I2C master driver.
 
 AVRs usually have set GPIO which turn into I2C pins, therefore no further configuration is required.
 
-## ARM
+## ARM :id=arm
 
 For ARM the Chibios I2C HAL driver is under the hood.
 This section assumes an STM32 MCU.
 
-### Configuration
+### Configuration :id=arm-configuration
 
 The configuration for ARM MCUs can be quite complex as often there are multiple I2C drivers which can be assigned to a variety of ports.
 
@@ -77,7 +90,7 @@ The ChibiOS I2C driver configuration depends on STM32 MCU:
     STM32F1xx, STM32F2xx, STM32F4xx, STM32L0xx and STM32L1xx use I2Cv1;
     STM32F0xx, STM32F3xx, STM32F7xx and STM32L4xx use I2Cv2;
 
-#### I2Cv1
+#### I2Cv1 :id=i2cv1
 STM32 MCUs allow for different clock and duty parameters when configuring I2Cv1. These can be modified using the following parameters, using <https://www.playembedded.org/blog/stm32-i2c-chibios/#I2Cv1_configuration_structure> as a reference:
 
 | Variable           | Default          |
@@ -86,7 +99,7 @@ STM32 MCUs allow for different clock and duty parameters when configuring I2Cv1.
 | `I2C1_CLOCK_SPEED` | `100000`         |
 | `I2C1_DUTY_CYCLE`  | `STD_DUTY_CYCLE` |
 
-#### I2Cv2
+#### I2Cv2 :id=i2cv2
 STM32 MCUs allow for different timing parameters when configuring I2Cv2. These can be modified using the following parameters, using <https://www.st.com/en/embedded-software/stsw-stm32126.html> as a reference:
 
 | Variable              | Default |
@@ -104,10 +117,10 @@ STM32 MCUs allow for different "alternate function" modes when configuring GPIO
 | `I2C1_SCL_PAL_MODE` | `4`     |
 | `I2C1_SDA_PAL_MODE` | `4`     |
 
-#### Other
+#### Other :id=other
 You can also overload the `void i2c_init(void)` function, which has a weak attribute. If you do this the configuration variables above will not be used. Please consult the datasheet of your MCU for the available GPIO configurations. The following is an example initialization function:
 
-```C
+```c
 void i2c_init(void)
 {
   setPinInput(B6); // Try releasing special pins for a short time

docs/index.html

@@ -13,19 +13,39 @@
   <meta property="og:image" content="https://i.imgur.com/svjvIrw.jpg">
   <meta property="og:url" content="https://docs.qmk.fm">
   <meta name="twitter:card" content="summary_large_image">
-  <link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/vue.css" title="light">
-  <link rel="stylesheet" href="qmk.css" title="dark" disabled>
-  <link rel="stylesheet" href="sidebar.css" />
+  <link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/buble.css" title="light">
+  <link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/dark.css" media="(prefers-color-scheme: dark)">
+  <link rel="stylesheet" href="//unpkg.com/docsify-toc@1.0.0/dist/toc.css">
+  <link rel="stylesheet" href="qmk_custom_light.css">
+  <link rel="stylesheet" href="qmk_custom_dark.css" media="(prefers-color-scheme: dark)">
 </head>
 <body>
   <div id="app"></div>
   <script>
     window.$docsify = {
       alias: {
+        // Translation aliases
         '/en/(.*)': '/$1',
         '/en-us/(.*)': '/$1',
         '/en-gb/(.*)': '/$1',
         '/.*/_langs.md': '/_langs.md',
+
+        // Moved pages
+        '/adding_a_keyboard_to_qmk': '/hardware_keyboard_guidelines',
+        '/build_environment_setup': '/newbs_getting_started',
+        '/cli_dev_configuration': '/cli_configuration',
+        '/dynamic_macros': '/feature_dynamic_macros',
+        '/feature_common_shortcuts': '/feature_advanced_keycodes',
+        '/glossary': '/reference_glossary',
+        '/key_lock': '/feature_key_lock',
+        '/make_instructions': '/getting_started_make_guide',
+        '/porting_your_keyboard_to_qmk': '/hardware_avr',
+        '/space_cadet_shift': '/feature_space_cadet_shift',
+        '/getting_started_getting_help': '/support',
+        '/tap_dance': '/feature_tap_dance',
+        '/unicode': '/feature_unicode',
+        '/python_development': '/cli_development',
+        '/getting_started_build_tools':'/newbs_getting_started',
       },
       basePath: '/',
       name: 'QMK Firmware',
@@ -45,6 +65,7 @@
       loadNavbar: '_langs.md',
       mergeNavbar: true,
       auto2top: true,
+      autoHeader: true,
       fallbackLanguages: [
         'de',
         'es',
@@ -74,6 +95,36 @@
         },
         depth: 6
       },
+      markdown: {
+        smartypants: true,
+        smartLists: true,
+      },
+      copyCode: {
+        buttonText: {
+          '/zh-cn/': '点击复制',
+          '/ru/'   : 'Скопировать в буфер обмена',
+          '/de-de/': 'Klicken Sie zum Kopieren',
+          '/es/'   : 'Haga clic para copiar',
+          '/'      : 'Copy to clipboard'
+        },
+        errorText: {
+          '/zh-cn/': '错误',
+          '/ru/'   : 'ошибка',
+          '/'      : 'Error'
+        },
+        successText: {
+          '/zh-cn/': '复制',
+          '/ru/'   : 'Скопировано',
+          '/de-de/': 'Kopiert',
+          '/es/'   : 'Copiado',
+          '/'      : 'Copied'
+        }
+      },
+      toc: {
+        scope: '.markdown-section',
+        headings: 'h1, h2',
+        title: 'Table of Contents',
+      },
       plugins: [
         function (hook, vm) {
           hook.beforeEach(function (html) {
@@ -96,13 +147,16 @@
   <script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
   <script src="//unpkg.com/docsify/lib/plugins/search.min.js"></script>
   <script src="//unpkg.com/docsify/lib/plugins/emoji.min.js"></script>
+  <script src="//unpkg.com/docsify-copy-code@2"></script>
+  <script src="//unpkg.com/docsify-toc@1.0.0/dist/toc.js"></script>
   <script src="//unpkg.com/prismjs/components/prism-bash.min.js"></script>
   <script src="//unpkg.com/prismjs/components/prism-c.min.js"></script>
   <script src="//unpkg.com/prismjs/components/prism-cpp.min.js"></script>
   <script src="//unpkg.com/prismjs/components/prism-json.min.js"></script>
   <script src="//unpkg.com/prismjs/components/prism-makefile.min.js"></script>
   <script>
-    // Register the offline cache worker
+    // Register the cache worker for offline viewing mode
+    // https://docsify.now.sh/pwa
     if (typeof navigator.serviceWorker !== 'undefined') {
       navigator.serviceWorker.register('sw.js')
     }

docs/internals_gpio_control.md

@@ -1,22 +1,23 @@
-# GPIO Control
+# GPIO Control :id=gpio-control
 
 QMK has a GPIO control abstraction layer which is microcontroller agnostic. This is done to allow easy access to pin control across different platforms.
 
-## Functions
+## Functions :id=functions
 
 The following functions can provide basic control of GPIOs and are found in `quantum/quantum.h`.
 
-|Function              |Description                                                       | Old AVR Examples                               | Old ChibiOS/ARM Examples                        |
-|----------------------|------------------------------------------------------------------|------------------------------------------------|-------------------------------------------------|
-|`setPinInput(pin)`    |Set pin as input with high impedance (High-Z)                     | `DDRB &= ~(1<<2)`                              | `palSetLineMode(pin, PAL_MODE_INPUT)`           |
-|`setPinInputHigh(pin)`|Set pin as input with builtin pull-up resistor                    | `DDRB &= ~(1<<2); PORTB \|= (1<<2)`             | `palSetLineMode(pin, PAL_MODE_INPUT_PULLUP)`    |
-|`setPinInputLow(pin)` |Set pin as input with builtin pull-down resistor                  | N/A (Not supported on AVR)                     | `palSetLineMode(pin, PAL_MODE_INPUT_PULLDOWN)`  |
-|`setPinOutput(pin)`   |Set pin as output                                                 | `DDRB \|= (1<<2)`                               | `palSetLineMode(pin, PAL_MODE_OUTPUT_PUSHPULL)` |
-|`writePinHigh(pin)`   |Set pin level as high, assuming it is an output                   | `PORTB \|= (1<<2)`                              | `palSetLine(pin)`                               |
-|`writePinLow(pin)`    |Set pin level as low, assuming it is an output                    | `PORTB &= ~(1<<2)`                             | `palClearLine(pin)`                             |
-|`writePin(pin, level)`|Set pin level, assuming it is an output                           | `(level) ? PORTB \|= (1<<2) : PORTB &= ~(1<<2)` | `(level) ? palSetLine(pin) : palClearLine(pin)` |
-|`readPin(pin)`        |Returns the level of the pin                                      | `_SFR_IO8(pin >> 4) & _BV(pin & 0xF)`          | `palReadLine(pin)`                              |
+|Function                |Description                                       | Old AVR Examples                                | Old ChibiOS/ARM Examples                        |
+|------------------------|--------------------------------------------------|-------------------------------------------------|-------------------------------------------------|
+| `setPinInput(pin)`     | Set pin as input with high impedance (High-Z)    | `DDRB &= ~(1<<2)`                               | `palSetLineMode(pin, PAL_MODE_INPUT)`           |
+| `setPinInputHigh(pin)` | Set pin as input with builtin pull-up resistor   | `DDRB &= ~(1<<2); PORTB \|= (1<<2)`             | `palSetLineMode(pin, PAL_MODE_INPUT_PULLUP)`    |
+| `setPinInputLow(pin)`  | Set pin as input with builtin pull-down resistor | N/A (Not supported on AVR)                      | `palSetLineMode(pin, PAL_MODE_INPUT_PULLDOWN)`  |
+| `setPinOutput(pin)`    | Set pin as output                                | `DDRB \|= (1<<2)`                               | `palSetLineMode(pin, PAL_MODE_OUTPUT_PUSHPULL)` |
+| `writePinHigh(pin)`    | Set pin level as high, assuming it is an output  | `PORTB \|= (1<<2)`                              | `palSetLine(pin)`                               |
+| `writePinLow(pin)`     | Set pin level as low, assuming it is an output   | `PORTB &= ~(1<<2)`                              | `palClearLine(pin)`                             |
+| `writePin(pin, level)` | Set pin level, assuming it is an output          | `(level) ? PORTB \|= (1<<2) : PORTB &= ~(1<<2)` | `(level) ? palSetLine(pin) : palClearLine(pin)` |
+| `readPin(pin)`         | Returns the level of the pin                     | `_SFR_IO8(pin >> 4) & _BV(pin & 0xF)`           | `palReadLine(pin)`                              |
+| `togglePin(pin)`       | Invert pin level, assuming it is an output       | `PORTB ^= (1<<2)`                               | `palToggleLine(pin)`                            |
 
-## Advanced Settings
+## Advanced Settings :id=advanced-settings
 
 Each microcontroller can have multiple advanced settings regarding its GPIO. This abstraction layer does not limit the use of architecture-specific functions. Advanced users should consult the datasheet of their desired device and include any needed libraries. For AVR, the standard avr/io.h library is used; for STM32, the ChibiOS [PAL library](http://chibios.sourceforge.net/docs3/hal/group___p_a_l.html) is used.

docs/isp_flashing_guide.md

@@ -1,6 +1,14 @@
 # ISP Flashing Guide
 
-If you're having trouble flashing/erasing your board, and running into cryptic error messages like any of the following:
+ISP flashing (also known as ICSP flashing) is the process of programming a microcontroller directly.  This allows you to replace the bootloader, or change the "fuses" on the controller, which control a number of hardware- and software-related functions, such as the speed of the controller, how it boots, and other options.  
+
+The main use of ISP flashing for QMK is flashing or replacing the bootloader on your AVR-based controller (Pro Micros, or V-USB chips).  
+
+?> This is only for programming AVR based boards, such as the Pro Micro or other ATmega controllers.  It is not for Arm controllers, such as the Proton C. 
+
+## Dealing with Corrupted Bootloaders
+
+If you're having trouble flashing/erasing your board, and running into cryptic error messages like any of the following for a DFU based controller:
 
     libusb: warning [darwin_transfer_status] transfer error: timed out
     dfu.c:844: -ETIMEDOUT: Transfer timed out, NAK 0xffffffc4 (-60)
@@ -19,16 +27,60 @@ If you're having trouble flashing/erasing your board, and running into cryptic e
     Memory write error, use debug for more info.
     commands.c:360: Error writing memory data. (err -4)
 
-You're likely going to need to ISP flash your board/device to get it working again. Luckily, this process is pretty straight-forward, provided you have any extra programmable keyboard, Pro Micro, or Teensy 2.0/Teensy 2.0++. There are also dedicated ISP flashers available for this, but most cost >$15, and it's assumed that if you are googling this error, this is the first you've heard about ISP flashing, and don't have one readily available (whereas you might have some other AVR board). __We'll be using a Teensy 2.0 or Pro Micro with Windows 10 in this guide__ - if you are comfortable doing this on another system, please consider editing this guide and contributing those instructions!   
+Or, if you see this sort of message for a Pro Micro based controller:
+
+    avrdude: butterfly_recv(): programmer is not responding
+    avrdude: butterfly_recv(): programmer is not responding
+    avrdude: verification error, first mismatch at byte 0x002a
+            0x2b != 0x75
+    avrdude: verification error; content mismatch
+    avrdude: verification error; content mismatch
+
+
+You're likely going to need to ISP flash your board/device to get it working again. 
+
+## Hardware Needed
+
+You'll need one of the following to actually perform the ISP flashing (followed by the protocol they use):
+
+* [SparkFun PocketAVR](https://www.sparkfun.com/products/9825) - (USB Tiny)
+* [USBtinyISP AVR Programmer Kit](https://www.adafruit.com/product/46) - (USB Tiny)
+* [Teensy 2.0](https://www.pjrc.com/store/teensy.html) - (avrisp)
+* [Pro Micro](https://www.sparkfun.com/products/12640)  - (avrisp)
+* [Bus Pirate](https://www.adafruit.com/product/237) - (buspirate)
+
+There are other devices that can be used to ISP flash, but these are the main ones.  Also, all product links are to the official versions. You can source them elsewhere. 
+
+You'll also need something to wire your "ISP Programmer" to the device that you're programming.  Some PCBs may have ISP headers that you can use directly, but this often isn't the case, so you'll likely need to solder to the controller itself or to different switches or other components. 
+
+### The ISP Firmware 
+
+The Teensy and Pro Micro controllers will need you to flash the ISP firmware to the controllers before you can use them as an ISP programmer.  The rest of the hardware should come preprogrammed.  So, for these controllers, download the correct hex file, and flash it first. 
+
+* Teensy 2.0: [`util/teensy_2.0_ISP_B0.hex`](https://github.com/qmk/qmk_firmware/blob/master/util/teensy_2.0_ISP_B0.hex) (`B0`)
+* Pro Micro: [`util/pro_micro_ISP_B6_10.hex`](https://github.com/qmk/qmk_firmware/blob/master/util/pro_micro_ISP_B6_10.hex) (`10/B6`)
+
+Once you've flashed your controller, you won't need this hex file anymore. 
 
 ## Software Needed
 
-* [Teensy Loader](https://www.pjrc.com/teensy/loader.html) (if using a Teensy)
-* QMK Toolbox (flash as usual - be sure to select the correct MCU) or `avrdude` via [WinAVR](http://www.ladyada.net/learn/avr/setup-win.html) (for Teensy & Pro Micro)
+The QMK Toolbox can be used for most (all) of this.  
+
+However, you can grab the [Teensy Loader](https://www.pjrc.com/teensy/loader.html) to flash your Teensy 2.0 board, if you are using that. Or you can use `avrdude` (installed as part of `qmk_install.sh`), or [AVRDUDESS](https://blog.zakkemble.net/avrdudess-a-gui-for-avrdude/) (for Windows) to flash the Pro Micro, and the ISP flashing. 
+
 
 ## Wiring
 
-This is pretty straight-forward - we'll be connecting like-things to like-things in the following manner:
+This is pretty straight-forward - we'll be connecting like-things to like-things in the following manner.
+
+### SparkFun Pocket AVR
+
+    PocketAVR RST  <-> Keyboard RESET
+    PocketAVR SCLK <-> Keyboard B1 (SCLK)
+    PocketAVR MOSI <-> Keyboard B2 (MOSI)
+    PocketAVR MISO <-> Keyboard B3 (MISO)
+    PocketAVR VCC  <-> Keyboard VCC
+    PocketAVR GND  <-> Keyboard GND
 
 ### Teensy 2.0
 
@@ -39,6 +91,8 @@ This is pretty straight-forward - we'll be connecting like-things to like-things
     Teensy VCC <-> Keyboard VCC
     Teensy GND <-> Keyboard GND
     
+!> Note that the B0 pin on the Teensy is wired to the RESET/RST pin on the keyboard's controller.  ***DO NOT*** wire the RESET pin on the Teensy to the RESET on the keyboard. 
+
 ### Pro Micro
 
     Pro Micro 10 (B6)  <-> Keyboard RESET
@@ -48,45 +102,67 @@ This is pretty straight-forward - we'll be connecting like-things to like-things
     Pro Micro VCC      <-> Keyboard VCC
     Pro Micro GND      <-> Keyboard GND
 
-## The ISP Firmware (now pre-compiled)
+!> Note that the 10/B6 pin on the Pro Micro is wired to the RESET/RST pin on the keyboard's controller.  ***DO NOT*** wire the RESET pin on the Pro Micro to the RESET on the keyboard. 
 
-The only difference between the .hex files below is which pin is connected to RESET. You can use them on other boards as well, as long as you're aware of the pins being used. If for some reason neither of these pins are available, [create an issue](https://github.com/qmk/qmk_firmware/issues/new), and we can generate one for you!
 
-* Teensy 2.0: [`util/teensy_2.0_ISP_B0.hex`](https://github.com/qmk/qmk_firmware/blob/master/util/teensy_2.0_ISP_B0.hex) (`B0`)
-* Pro Micro: [`util/pro_micro_ISP_B6_10.hex`](https://github.com/qmk/qmk_firmware/blob/master/util/pro_micro_ISP_B6_10.hex) (`B6/10`)
+## Flashing Your Keyboard 
 
-**Flash your Teenys/Pro Micro with one of these and continue - you won't need the file after flashing your ISP device.**
+After you have your ISP programmer set up, and wired to your keyboard, it's time to flash your keyboard.  
 
-## Just the Bootloader File
+### The Bootloader File
 
-If you just want to get things back to normal, you can flash only a bootloader from [`util/` folder](https://github.com/qmk/qmk_firmware/tree/master/util), and use your normal process to flash the firmware afterwards. Be sure to flash the correct bootloader for your chip:
+The simplest and quickest way to get things back to normal is to flash only a bootloader to the keyboard. Once this is done, you can connect the keyboard normally and flash the keyboard like you normally would. 
 
-* [`atmega32u4`](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_atmega32u4_1_0_0.hex) - Most keyboards, Planck Rev 1-5, Preonic Rev 1-2
-* [`at90usb1286`](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_at90usb128x_1_0_1.hex) - Planck Light Rev 1
-* [`atmega32a`](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_atmega32a_1_0_0.hex) - jj40
+You can find the stock bootloaders in the [`util/` folder](https://github.com/qmk/qmk_firmware/tree/master/util). Be sure to flash the correct bootloader for your chip:
 
-If you're not sure what your board uses, look in the `rules.mk` file for the keyboard in QMK. The `MCU =` line will have the value you need. It may differ between different versions of the board.
+* **Atmel DFU**
+  * [ATmega16U4](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_atmega16u4_1.0.1.hex)
+  * [ATmega32U4](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_atmega32u4_1.0.0.hex)
+  * [AT90USB64](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_at90usb64_1.0.0.hex)
+  * [AT90USB128](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_at90usb128_1.0.1.hex)
+* **Caterina**
+  * [Pro Micro (5V/16MHz)](https://github.com/sparkfun/Arduino_Boards/blob/master/sparkfun/avr/bootloaders/caterina/Caterina-promicro16.hex)
+  * [Pro Micro (3.3V/8MHz)](https://github.com/sparkfun/Arduino_Boards/blob/master/sparkfun/avr/bootloaders/caterina/Caterina-promicro8.hex)
+* **BootloadHID (PS2AVRGB)**
+  * [ATmega32A](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_ps2avrgb_bootloadhid_1.0.1.hex)
 
-### Advanced/Production Techniques
+If you're not sure what your board uses, look in the `rules.mk` file for the keyboard in QMK. The `MCU` and `BOOTLOADER` lines will have the value you need. It may differ between different versions of the board.
 
-If you'd like to flash both the bootloader **and** the regular firmware at the same time, you need to combine the files. 
+### Production Techniques
+
+If you'd like to flash both the bootloader **and** the regular firmware at the same time, there are two options to do so.  Manually, or with the `:production` target when compiling. 
+
+To do this manually: 
 
 1. Open the original firmware .hex file in a text editor
 2. Remove the last line (which should be `:00000001FF` - this is an EOF message)
 3. Copy the entire bootloader's contents onto a new line (with no empty lines between) and paste it at the end of the original file
 4. Save it as a new file by naming it `<keyboard>_<keymap>_production.hex`
 
-It's possible to use other bootloaders here in the same way, but __you need a bootloader__, otherwise you'll have to use ISP again to write new firmware to your keyboard.
+?> It's possible to use other bootloaders here in the same way, but __you need a bootloader__, otherwise you'll have to use ISP again to write new firmware to your keyboard.
+
+To do this the easy way, you can flash the board using the `:production` target when compiling.  This compiles the firmware, then compiles the QMK DFU bootloader, and then creates a combined image.  Once this is done, you'll see three files: 
+* `<keyboard>_<keymap>.hex`
+* `<keyboard>_<keymap>_bootloader.hex`
+* `<keyboard>_<keymap>_production.hex`
+
+The QMK DFU bootloader has only really been tested on `atmega32u4` controllers (such as the AVR based Planck boards, and the Pro Micro), and hasn't been tested on other controllers.  However, it will definitely not work on V-USB controllers, such as the `atmega32a` or `atmega328p`.
+
+You can flash either the bootloader or the production firmware file. The production firmware file will take a lot longer to flash, since it's flashing a lot more data. 
+
+?> Note: You should stay with the same bootloader. If you're using DFU already, switching to QMK DFU is fine. But flashing QMK DFU onto a Pro Micro, for instance, has additional steps needed.
 
 ## Flashing Your Bootloader/Production File
 
-Make sure your keyboard is unplugged from any device, and plug in your Teensy.
+Make sure your keyboard is unplugged from any device, and plug in your ISP Programmer.
+
+If you want to change bootloader types, You'll need to use the command line. 
 
 ### QMK Toolbox
 
-1. `AVRISP device connected` will show up in yellow
+1. `AVRISP device connected` or `USB Tiny device connected` will show up in yellow
 2. Select the correct bootloader/production .hex file with the `Open` dialog (spaces can't be in the path)
-3. Be sure the correct `Microcontroller` option is selected
+3. Be sure the correct `Microcontroller` option for the keyboard you're flashing (not the ISP programmer) is selected
 4. Hit `Flash`
 5. Wait, as nothing will output for a while, especially with production files
 
@@ -94,7 +170,7 @@ If the verification and fuse checks are ok, you're done! Your board may restart
 
 ### Command Line
 
-Open `cmd` and navigate to your where your modified .hex file is. We'll pretend this file is called `main.hex`, and that your Teensy 2.0 is on the `COM3` port - if you're unsure, you can open your Device Manager, and look for `Ports > USB Serial Device`. Use that COM port here. You can confirm it's the right port with:
+Open a terminal (`cmd` on Windows, for instance) and navigate to your where your modified .hex file is. We'll pretend this file is called `main.hex`, and that your Teensy 2.0 is on the `COM3` port - if you're unsure, you can open your Device Manager, and look for `Ports > USB Serial Device`. Use that COM port here. You can confirm it's the right port with:
 
     avrdude -c avrisp -P COM3 -p atmega32u4
 
@@ -129,4 +205,47 @@ You should see a couple of progress bars, then you should see:
 
 Which means everything should be ok! Your board may restart automatically, otherwise, unplug your Teensy and plug in your keyboard - you can leave your Teensy wired to your keyboard while testing things, but it's recommended that you desolder it/remove the wiring once you're sure everything works.
 
+If you're using a SparkFun PocketAVR Programmer, or another USB Tiny based ISP programmer, you will want to use something like this: 
+
+    avrdude -c usbtiny -P usb -p atmega32u4
+
+#### Advanced: Changing Fuses
+
+If you're switching bootloaders, such as flashing QMK DFU on a Pro Micro, you will need to change the fuses, in additional to flashing the bootloader hex file.  This is because `caterina` (the Pro Micro bootloader) and `dfu` handle the startup routines differently, and that behavior is controlled by the fuses.  
+
+!> This is one area that it is very important to be careful, as changing fuses is one of the ways that you can permanently brick your controller.  
+
+For this, we are assuming the 5V 16MHz versions of the `atmega32u4` (such as the 5V Pro Micro).
+
+For DFU on the `atmega32u4`, these are the fuse settings that you want: 
+
+| Fuse     | Setting          |
+|----------|------------------|
+| Low      | `0x5E`           |
+| High     | `0xD9` or `0x99` |
+| Extended | `0xC3`           |
+
+The High fuse can be 0xD9 or 0x99. The difference is that 0xD9 disables JTAG, which QMK Firmware disables via software as well, while 0x99 doesn't disable JTAG. 
+
+To set this add `-U lfuse:w:0x5E:m -U hfuse:w:0xD9:m -U efuse:w:0xC3:m` to your command.  So the final command should look something like: 
+
+    avrdude -c avrisp -P COM3 -p atmega32u4 -U flash:w:main.hex:i -U lfuse:w:0x5E:m -U hfuse:w:0xD9:m -U efuse:w:0xC3:m
+
+For Caterina on the `atmega32u4`, these are the fuse settings that you want: 
+
+| Fuse     | Setting|
+|----------|--------|
+| Low      | `0xFF` |
+| High     | `0xD9` |
+| Extended | `0xC3` |
+
+To set this add `-U lfuse:w:0xFF:m -U hfuse:w:0xD8:m -U efuse:w:0xC3:m` to your command.  So the final command should look something like: 
+
+    avrdude -c avrisp -P COM3 -p atmega32u4 -U flash:w:main.hex:i -U lfuse:w:0xFF:m -U hfuse:w:0xD8:m -U efuse:w:0xC3:m
+
+
+If you are using a different controller or want different configuration, you can use [this AVR Fuse Calculator](http://www.engbedded.com/fusecalc/) to find a better value for you.
+
+## Help 
+
 If you have any questions/problems, feel free to [open an issue](https://github.com/qmk/qmk_firmware/issues/new)!

docs/ja/README.md

@@ -1,8 +1,8 @@
 # Quantum Mechanical Keyboard Firmware
 
 <!---
-  original document: eae21eed7:docs/README.md
-  git diff eae21eed7 HEAD -- docs/README.md | cat
+  original document: 0.8.58:docs/README.md
+  git diff 0.8.58 HEAD -- docs/README.md | cat
 -->
 
 [![現在のバージョン](https://img.shields.io/github/tag/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/tags)
@@ -12,26 +12,37 @@
 [![GitHub 貢献者](https://img.shields.io/github/contributors/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/pulse/monthly)
 [![GitHub フォーク](https://img.shields.io/github/forks/qmk/qmk_firmware.svg?style=social&label=Fork)](https://github.com/qmk/qmk_firmware/)
 
-## QMK ファームウェアとは何か？
+## QMK ファームウェアとは何でしょうか？
 
-QMK (*Quantum Mechanical Keyboard*)は QMK ファームウェア、QMK ツールボックス、qmk.fm およびそれらのドキュメントを保守するオープンソースコミュニティです。QMK ファームウェアは[tmk\_keyboard](http://github.com/tmk/tmk_keyboard) を元にしたキーボードファームウェアで、Atmel AVR コントローラ、より具体的には [OLKB 製品](http://olkb.com)、[ErgoDox EZ](http://www.ergodox-ez.com) キーボードおよび [Clueboard 製品](http://clueboard.co/) のための幾つかの便利な機能を持ちます。また、ChibiOS を使って ARM チップに移植されています。これを使ってあなたの作った手配線のキーボードあるいはカスタムキーボード PCB で作ったキーボードを動かすことができます。
+QMK (*Quantum Mechanical Keyboard*)は、コンピュータ入力デバイスの開発を中心としたオープンソースコミュニティです。コミュニティには、キーボード、マウス、MIDI デバイスなど、全ての種類の入力デバイスが含まれます。協力者の中心グループは、[QMK ファームウェア](https://github.com/qmk/qmk_firmware)、[QMK Configurator](https://config.qmk.fm)、[QMK ツールボックス](https://github.com/qmk/qmk_toolbox)、[qmk.fm](https://qmk.fm)、そして、このドキュメントを、あなたのようなコミュニティメンバーの助けを借りて保守しています。
 
-## 入手方法
+## 始めましょう
 
-QMK のキーマップ、キーボード、機能に貢献をする予定がある場合、最も簡単なのは、[Github を介してリポジトリをフォークし](https://github.com/qmk/qmk_firmware#fork-destination-box)、リポジトリをあなたの開発環境にクローンして変更を加え、それらをプッシュし、[プルリクエスト](https://github.com/qmk/qmk_firmware/pulls)を開くことです。
+QMK は初めてですか？始めるには2つの方法があります:
 
-それ以外の場合は、`git clone https://github.com/qmk/qmk_firmware` を介して直接クローンすることができます。zip または tar ファイルをダウンロードしないでください。コンパイルするためのサブモジュールをダウンロードするために git リポジトリが必要です。
+* 基本: [QMK Configurator](https://config.qmk.fm)
+    * ドロップダウンからあなたのキーボードを選択し、キーボードをプログラムします。
+    * 見ることができる [紹介ビデオ](https://www.youtube.com/watch?v=-imgglzDMdY) があります。
+    * 読むことができる概要 [ドキュメント](ja/newbs_building_firmware_configurator.md) があります。
+* 発展: [ソースを使用します](ja/newbs.md)
+    * より強力ですが、使うのはより困難です。
 
-## コンパイル方法
+## 自分用にアレンジします
 
-コンパイルをする前に、AVR または ARM 開発のための[環境をインストール](ja/getting_started_build_tools.md)する必要があります。それが完了したら、`make` コマンドを使用して、以下の表記でキーボードとキーマップをビルドします。
+QMK には、探求すべき多くの[機能](ja/features.md)と、深く知るためのリファレンスドキュメントがたくさんあります。ほとんどの機能は[キーマップ](ja/keymap.md)を変更し、[キーコード](ja/keycodes.md)を変更することで活用されます。
 
-    make planck/rev4:default
+## 手助けが必要ですか？
 
-これは、`planck` の `rev4` リビジョンを `default` キーマップでビルドします。全てのキーボードにリビジョン(サブプロジェクトまたはフォルダとも呼ばれます)があるわけではありません。その場合は省略されます:
+[サポートページ](ja/support.md) をチェックして、QMK の使い方について手助けを得る方法を確認してください。
 
-    make preonic:default
+## 貢献する
 
-## カスタマイズ方法
+QMK コミュニティに貢献する方法はたくさんあります。始める最も簡単な方法は、それを使って友人に QMK という単語を広めることです。
 
-QMK には、探求すべき多くの[機能](ja/features.md)と、深堀りするための[リファレンス ドキュメント](http://docs.qmk.fm)がたくさんあります。ほとんどの機能は[キーマップ](ja/keymap.md)を変更し、[キーコード](ja/keycodes.md)を変更することで活用されます。
+* フォーラムやチャットルームで人々を支援します:
+    * [/r/olkb](https://www.reddit.com/r/olkb/)
+    * [Discord サーバ](https://discord.gg/Uq7gcHh)
+* 下にある「Edit This Page」をクリックしてドキュメントに貢献します
+* [ドキュメントをあなたの言語に翻訳します](ja/translating.md)
+* [バグを報告します](https://github.com/qmk/qmk_firmware/issues/new/choose)
+* [プルリクエストを開きます](ja/contributing.md)

docs/ja/_summary.md

@@ -1,124 +1,163 @@
-* [完全な初心者のガイド](ja/newbs.md)
-   * [はじめに](ja/newbs_getting_started.md)
-   * [初めてのファームウェアの構築](ja/newbs_building_firmware.md)
-   * [ファームウェアのフラッシュ](ja/newbs_flashing.md)
-   * [テストとデバッグ](ja/newbs_testing_debugging.md)
-   * [QMK における Git 運用作法](ja/newbs_git_best_practices.md)
-     * [あなたのフォークの master ブランチ](ja/newbs_git_using_your_master_branch.md)
-     * [マージの競合の解決](ja/newbs_git_resolving_merge_conflicts.md)
-     * [同期のとれていない git ブランチの再同期](ja/newbs_git_resynchronize_a_branch.md)
-   * [学習リソース](ja/newbs_learn_more_resources.md)
+* チュートリアル
+  * [入門](ja/newbs.md)
+  * [セットアップ](ja/newbs_getting_started.md)
+  * [初めてのファームウェアの構築](ja/newbs_building_firmware.md)
+  * [ファームウェアのフラッシュ](ja/newbs_flashing.md)
+  * [テストとデバッグ](ja/newbs_testing_debugging.md)
+  * [手助けを得る/サポート](ja/support.md)
+  * [他のリソース](ja/newbs_learn_more_resources.md)
 
-* [QMKの基本](ja/README.md)
-   * [QMKの導入](ja/getting_started_introduction.md)
-   * [QMK CLI](ja/cli.md)
-   * [QMK CLI 設定](ja/cli_configuration.md)
-   * [QMKへの貢献](ja/contributing.md)
-   * [Githubの使い方](ja/getting_started_github.md)
-   * [ヘルプ](ja/getting_started_getting_help.md)
+* FAQ
+  * [一般的な FAQ](ja/faq_general.md)
+  * [QMK のビルド/コンパイル](ja/faq_build.md)
+  * [QMK のデバッグ/トラブルシューティング](ja/faq_debug.md)
+  * [キーマップ FAQ](ja/faq_keymap.md)
+  * [用語](ja/reference_glossary.md)
 
-* [破壊的な変更](ja/breaking_changes.md)
-   * [2019年8月30日](ja/ChangeLog/20190830.md)
+* Configurator
+  * [概要](ja/newbs_building_firmware_configurator.md)
+  * [ステップ・バイ・ステップ](ja/configurator_step_by_step.md)
+  * [トラブルシューティング](ja/configurator_troubleshooting.md)
+  * QMK API
+    * [概要](ja/api_overview.md)
+    * [API ドキュメント](ja/api_docs.md)
+    * [キーボードサポート](ja/reference_configurator_support.md)
 
-* [FAQ](ja/faq.md)
-   * [一般的なFAQ](ja/faq_general.md)
-   * [QMKのビルド/コンパイル](ja/faq_build.md)
-   * [QMKのデバッグ/トラブルシューティング](ja/faq_debug.md)
-   * [キーマップ](ja/faq_keymap.md)
-   * [Zadigを使ったドライバのインストール](ja/driver_installation_zadig.md)
+* CLI
+    * [概要](ja/cli.md)
+    * [設定](ja/cli_configuration.md)
+    * [コマンド](ja/cli_commands.md)
 
-* 詳細なガイド
-   * [ビルドツールのインストール](ja/getting_started_build_tools.md)
-   * [Vagrantのガイド](ja/getting_started_vagrant.md)
-   * [ビルド/コンパイルの説明](ja/getting_started_make_guide.md)
-   * [ファームウェアのフラッシュ](ja/flashing.md)
-   * [機能のカスタマイズ](ja/custom_quantum_functions.md)
-   * [キーマップの概要](ja/keymap.md)
+* QMK を使う
+  * ガイド
+    * [機能のカスタマイズ](ja/custom_quantum_functions.md)
+    * [Zadig を使ったドライバのインストール](ja/driver_installation_zadig.md)
+    * [キーマップの概要](ja/keymap.md)
+    * [Vagrant のガイド](ja/getting_started_vagrant.md)
+    * 書き込み
+      * [書き込み](ja/flashing.md)
+      * [ATmega32A の書き込み (ps2avrgb)](ja/flashing_bootloadhid.md)
+    * IDE
+      * [Eclipse で QMK を使用](ja/other_eclipse.md)
+      * [VSCode で QMK を使用](ja/other_vscode.md)
+    * Git のベストプラクティス
+      * [入門](ja/newbs_git_best_practices.md)
+      * [フォーク](ja/newbs_git_using_your_master_branch.md)
+      * [マージの競合の解決](ja/newbs_git_resolving_merge_conflicts.md)
+      * [ブランチの修正](ja/newbs_git_resynchronize_a_branch.md)
+    * キーボードを作る
+      * [Hand Wiring ガイド](ja/hand_wire.md)
+      * [ISP 書き込みガイド](ja/isp_flashing_guide.md)
 
-* [ハードウェア](ja/hardware.md)
-   * [AVR プロセッサ](ja/hardware_avr.md)
-   * [ドライバ](ja/hardware_drivers.md)
+  * 単純なキーコード
+    * [完全なリスト](ja/keycodes.md)
+    * [基本的なキーコード](ja/keycodes_basic.md)
+    * [修飾キー](ja/feature_advanced_keycodes.md)
+    * [Quantum キーコード](ja/quantum_keycodes.md)
 
-* リファレンス
-   * [キーボード ガイドライン](ja/hardware_keyboard_guidelines.md)
-   * [設定オプション](ja/config_options.md)
-   * [キーコード](ja/keycodes.md)
-   * [コーディング規約 - C](ja/coding_conventions_c.md)
-   * [コーディング規約 - Python](ja/coding_conventions_python.md)
-   * [ドキュメント ベストプラクティス](ja/documentation_best_practices.md)
-   * [ドキュメント テンプレート](ja/documentation_templates.md)
-   * [用語](ja/reference_glossary.md)
-   * [ユニットテスト](ja/unit_testing.md)
-   * [便利な関数](ja/ref_functions.md)
-   * [Configurator サポート](ja/reference_configurator_support.md)
-   * [info.json 形式](ja/reference_info_json.md)
-   * [Python CLI 開発](ja/cli_development.md)
+  * 高度なキーコード
+    * [コマンド](ja/feature_command.md)
+    * [動的マクロ](ja/feature_dynamic_macros.md)
+    * [グレイブ エスケープ](ja/feature_grave_esc.md)
+    * [リーダーキー](ja/feature_leader_key.md)
+    * [モッドタップ](ja/mod_tap.md)
+    * [マクロ](ja/feature_macros.md)
+    * [マウスキー](ja/feature_mouse_keys.md)
+    * [Space Cadet Shift](ja/feature_space_cadet.md)
+    * [US ANSI シフトキー](ja/keycodes_us_ansi_shifted.md)
 
-* [機能](ja/features.md)
-   * [基本的なキーコード](ja/keycodes_basic.md)
-   * [US ANSI シフトキー](ja/keycodes_us_ansi_shifted.md)
-   * [Quantum キーコード](ja/quantum_keycodes.md)
-   * [Advanced キーコード](ja/feature_advanced_keycodes.md)
-   * [オーディオ](ja/feature_audio.md)
-   * [自動シフト](ja/feature_auto_shift.md)
-   * [バックライト](ja/feature_backlight.md)
-   * [ブルートゥース](ja/feature_bluetooth.md)
-   * [ブートマジック](ja/feature_bootmagic.md)
-   * [コンボ](ja/feature_combo.md)
-   * [コマンド](ja/feature_command.md)
-   * [Debounce API](ja/feature_debounce_type.md)
-   * [DIP スイッチ](ja/feature_dip_switch.md)
-   * [動的マクロ](ja/feature_dynamic_macros.md)
-   * [エンコーダ](ja/feature_encoders.md)
-   * [グレイブ エスケープ](ja/feature_grave_esc.md)
-   * [触覚フィードバック](ja/feature_haptic_feedback.md)
-   * [HD44780 LCD コントローラ](ja/feature_hd44780.md)
-   * [キーロック](ja/feature_key_lock.md)
-   * [レイアウト](ja/feature_layouts.md)
-   * [リーダー キー](ja/feature_leader_key.md)
-   * [LED マトリクス](ja/feature_led_matrix.md)
-   * [マクロ](ja/feature_macros.md)
-   * [マウスキー](ja/feature_mouse_keys.md)
-   * [OLED ドライバ](ja/feature_oled_driver.md)
-   * [One Shot Keys](ja/feature_advanced_keycodes.md#one-shot-keys)
-   * [ポインティング デバイス](ja/feature_pointing_device.md)
-   * [PS/2 マウス](ja/feature_ps2_mouse.md)
-   * [RGB ライト](ja/feature_rgblight.md)
-   * [RGB マトリクス](ja/feature_rgb_matrix.md)
-   * [Space Cadet](ja/feature_space_cadet.md)
-   * [分割キーボード](ja/feature_split_keyboard.md)
-   * [Stenography](ja/feature_stenography.md)
-   * [Swap Hands](ja/feature_swap_hands.md)
-   * [タップ ダンス](ja/feature_tap_dance.md)
-   * [Terminal](ja/feature_terminal.md)
-   * [感熱式プリンタ](ja/feature_thermal_printer.md)
-   * [ユニコード](ja/feature_unicode.md)
-   * [Userspace](ja/feature_userspace.md)
-   * [Velocikey](ja/feature_velocikey.md)
+  * ソフトウェア機能
+    * [自動シフト](ja/feature_auto_shift.md)
+    * [コンボ](ja/feature_combo.md)
+    * [デバウンス API](ja/feature_debounce_type.md)
+    * [キーロック](ja/feature_key_lock.md)
+    * [レイヤー](ja/feature_layers.md)
+    * [One Shot Keys](ja/one_shot_keys.md)
+    * [ポインティング デバイス](ja/feature_pointing_device.md)
+    * [Swap Hands](ja/feature_swap_hands.md)
+    * [タップダンス](ja/feature_tap_dance.md)
+    * [タップホールド設定](ja/tap_hold.md)
+    * [ターミナル](ja/feature_terminal.md)
+    * [ユニコード](ja/feature_unicode.md)
+    * [ユーザスペース](ja/feature_userspace.md)
+    * [WPM 計算](ja/feature_wpm.md)
 
-* メーカーおよびモッダーのために
-   * [Hand Wiring Guide](ja/hand_wire.md)
-   * [ISP Flashing Guide](ja/isp_flashing_guide.md)
-   * [ARM デバッグ ガイド](ja/arm_debugging.md)
-   * [I2C ドライバ](ja/i2c_driver.md)
-   * [GPIO コントロール](ja/internals_gpio_control.md)
-   * [Proton C 規約](ja/proton_c_conversion.md)
+  * ハードウェア機能
+    * 表示
+      * [HD44780 LCD コントローラ](ja/feature_hd44780.md)
+      * [OLED ドライバ](ja/feature_oled_driver.md)
+    * 電飾
+      * [バックライト](ja/feature_backlight.md)
+      * [LED マトリックス](ja/feature_led_matrix.md)
+      * [RGB ライト](ja/feature_rgblight.md)
+      * [RGB マトリックス](ja/feature_rgb_matrix.md)
+    * [オーディオ](ja/feature_audio.md)
+    * [Bluetooth](ja/feature_bluetooth.md)
+    * [ブートマジック](ja/feature_bootmagic.md)
+    * [カスタムマトリックス](ja/custom_matrix.md)
+    * [DIP スイッチ](ja/feature_dip_switch.md)
+    * [エンコーダ](ja/feature_encoders.md)
+    * [触覚フィードバック](ja/feature_haptic_feedback.md)
+    * [Proton C 規約](ja/proton_c_conversion.md)
+    * [PS/2 マウス](ja/feature_ps2_mouse.md)
+    * [分割キーボード](ja/feature_split_keyboard.md)
+    * [Stenography](ja/feature_stenography.md)
+    * [感熱式プリンタ](ja/feature_thermal_printer.md)
+    * [Velocikey](ja/feature_velocikey.md)
 
-* より深く知るために
-   * [キーボードがどのように動作するか](ja/how_keyboards_work.md)
-   * [QMKの理解](ja/understanding_qmk.md)
+* QMK の開発
+  * 破壊的な変更
+    * [概要](ja/breaking_changes.md)
+    * [プルリクエストにフラグが付けられた](ja/breaking_changes_instructions.md)
+    * 履歴
+      * [2020年2月29日](ja/ChangeLog/20200229.md)
+      * [2019年8月30日](ja/ChangeLog/20190830.md)
 
-* 他の話題
-   * [EclipseでQMKを使用](ja/other_eclipse.md)
-   * [VSCodeでQMKを使用](ja/other_vscode.md)
-   * [サポート](ja/support.md)
-   * [翻訳を追加する方法](ja/translating.md)
+  * C 開発
+    * [ARM デバッグ ガイド](ja/arm_debugging.md)
+    * [AVR プロセッサ](ja/hardware_avr.md)
+    * [コーディング規約](ja/coding_conventions_c.md)
+    * [互換性のあるマイクロコントローラ](ja/compatible_microcontrollers.md)
+    * [ドライバ](ja/hardware_drivers.md)
+      * [ADC ドライバ](ja/adc_driver.md)
+      * [I2C ドライバ](ja/i2c_driver.md)
+      * [SPI ドライバ](ja/spi_driver.md)
+      * [WS2812 ドライバ](ja/ws2812_driver.md)
+      * [EEPROM ドライバ](ja/eeprom_driver.md)
+    * [GPIO コントロール](ja/internals_gpio_control.md)
+    * [キーボード ガイドライン](ja/hardware_keyboard_guidelines.md)
 
-* QMK の内部詳細(作成中)
-   * [定義](ja/internals_defines.md)
-   * [Input Callback Reg](ja/internals_input_callback_reg.md)
-   * [Midi ドライバ](ja/internals_midi_device.md)
-   * [Midi デバイスのセットアップ手順](ja/internals_midi_device_setup_process.md)
-   * [Midi ユーティリティ](ja/internals_midi_util.md)
-   * [Send Functions](ja/internals_send_functions.md)
-   * [Sysex Tools](ja/internals_sysex_tools.md)
+  * Python 開発
+    * [コーディング規約](ja/coding_conventions_python.md)
+    * [QMK CLI 開発](ja/cli_development.md)
+
+  * Configurator 開発
+    * QMK API
+      * [開発環境](ja/api_development_environment.md)
+      * [アーキテクチャの概要](ja/api_development_overview.md)
+
+  * QMK Reference
+    * [QMK への貢献](ja/contributing.md)
+    * [QMK ドキュメントの翻訳](ja/translating.md)
+    * [設定オプション](ja/config_options.md)
+    * [Make ドキュメント](ja/getting_started_make_guide.md)
+    * [ドキュメント ベストプラクティス](ja/documentation_best_practices.md)
+    * [ドキュメント テンプレート](ja/documentation_templates.md)
+    * [コミュニティレイアウト](ja/feature_layouts.md)
+    * [ユニットテスト](ja/unit_testing.md)
+    * [便利な関数](ja/ref_functions.md)
+    * [info.json 形式](ja/reference_info_json.md)
+
+  * より深く知るために
+    * [キーボードがどのように動作するか](ja/how_keyboards_work.md)
+    * [マトリックスがどのように動作するか](ja/how_a_matrix_works.md)
+    * [QMK を理解する](ja/understanding_qmk.md)
+
+  * QMK の内部詳細(作成中)
+    * [定義](ja/internals_defines.md)
+    * [Input Callback Reg](ja/internals_input_callback_reg.md)
+    * [Midi デバイス](ja/internals_midi_device.md)
+    * [Midi デバイスのセットアップ手順](ja/internals_midi_device_setup_process.md)
+    * [Midi ユーティリティ](ja/internals_midi_util.md)
+    * [Send Functions](ja/internals_send_functions.md)
+    * [Sysex Tools](ja/internals_sysex_tools.md)

docs/ja/arm_debugging.md

@@ -1,8 +1,8 @@
 # Eclipse を使った ARM デバッグ
 
 <!---
-  original document: eae21eed7:docs/arm_debugging.md
-  git diff eae21eed7 HEAD -- docs/arm_debugging.md | cat
+  original document: 0.8.58:docs/arm_debugging.md
+  git diff 0.8.58 HEAD -- docs/arm_debugging.md | cat
 -->
 
 このページでは、SWD アダプタとオープンソース/フリーツールを使って ARM MCU をデバッグするためのセットアップ方法について説明します。このガイドでは、GNU MCU Eclipse IDE for C/C++ Developers および OpenOCD を必要な依存関係と一緒にインストールします。
@@ -60,23 +60,23 @@ Java は Eclipse で必要とされるため、[ここ](https://www.oracle.com/t
 
 Eclipse に QMK をビルドしようとするデバイスを教える必要があります。QMK フォルダを右クリック -> Properties -> C/C++ Build -> Settings を選択します。Devices タブを選択し、Devices の下から MCU の適切な種類を選択します。私の例では、STM32F303CC です。
 
-この間に、Build コマンドもセットアップしましょう。C/C++ Build を選択し、Behavior タブを選択します。build コマンドのところで、`all` を必要な make コマンドに置き換えます。例えば、rev6 Planck の default キーマップの場合、これは `planck/rev6:default` になります。Apply and Close を選択します。
+この間に、Build コマンドもセットアップしましょう。C/C++ Build を選択し、Behavior タブを選択します。Build コマンドのところで、`all` を必要な make コマンドに置き換えます。例えば、rev6 Planck の default キーマップの場合、これは `planck/rev6:default` になります。Apply and Close を選択します。
 
 ## ビルド
 
-全て正しくセットアップできていれば、ハンマーボタンを押すとファームウェアがビルドされ、.binファイルが出力されるはずです。
+全て正しくセットアップできていれば、ハンマーボタンを押すとファームウェアがビルドされ、.bin ファイルが出力されるはずです。
 
 ## デバッグ
 
 ### デバッガの接続
 
-ARM MCU は、クロック信号(SWCLK) とデータ信号(SWDIO) で構成される Single Wire Debug (SWD) プロトコルを使います。MCUを 完全に操作するには、この2本のワイヤとグラウンドを接続するだけで十分です。ここでは、キーボードは USB を介して電力が供給されると想定しています。手動でリセットボタンを使えるため、RESET 信号は必要ありません。より高度なセットアップのために printf と scanf をホストに非同期にパイプする SWO 信号を使用できますが、私たちのセットアップでは無視します。
+ARM MCU は、クロック信号(SWCLK) とデータ信号(SWDIO) で構成される Single Wire Debug (SWD) プロトコルを使います。MCU を完全に操作するには、この2本のワイヤとグラウンドを接続するだけで十分です。ここでは、キーボードは USB を介して電力が供給されると想定しています。手動でリセットボタンを使えるため、RESET 信号は必要ありません。より高度なセットアップのために printf と scanf をホストに非同期にパイプする SWO 信号を使用できますが、私たちのセットアップでは無視します。
 
 注意: SWCLK と SWDIO ピンがキーボードのマトリックスで使われていないことを確認してください。もし使われている場合は、一時的に他のピンに切り替えることができます。
 
 ### デバッガの設定
 
-QMK フォルダを右クリックし、Debug As -> Debug Configurations... を選択します。ここで、GDB OpenOCD Debugging をダブルクリックします。Debugger タブを選択し、MCU に必要な設定を入力します。これを見つけるにはいじったりググったりする必要があるかもしれません。STM32F3 用のデフォルトスクリプトは stm32f3discovery.cfg と呼ばれます。OpenOCD に伝えるには、Config options で `-f board/stm32f3discovery.cfg` と入力します。
+QMK フォルダを右クリックし、Debug As -> Debug Configurations... を選択します。ここで、GDB OpenOCD Debugging をダブルクリックします。Debugger タブを選択し、MCU に必要な設定を入力します。これを見つけるにはいじったりググったりする必要があるかもしれません。STM32F3 用のデフォルトスクリプトは `stm32f3discovery.cfg` と呼ばれます。OpenOCD に伝えるには、Config options で `-f board/stm32f3discovery.cfg` と入力します。
 
 注意: 私の場合、この設定スクリプトはリセット操作を無効にするために編集が必要です。スクリプトの場所は、通常はパス `openocd/version/.content/scripts/board` の下の実際の実行可能フィールドの中で見つかります。ここで、私は `reset_config srst_only` を `reset_config none` に編集しました。
 
@@ -86,7 +86,7 @@ Apply and Close を選択します。
 
 キーボードをリセットしてください。
 
-虫アイコンをクリックし、もし全てうまく行けば Debug パースペクティブに移動します。ここでは、main 関数の最初でプログラムカウンタが停止するので、Play ボタンを押します。全てのデバッガのほとんどの機能は ARM MCU で動作しますが、正確な詳細については google があなたのお友達です！
+虫アイコンをクリックし、もし全てうまく行けば Debug パースペクティブに移動します。ここでは、main 関数の最初でプログラムカウンタが停止し、Play ボタンが押されるのを待ちます。全てのデバッガのほとんどの機能は Arm MCU で動作しますが、正確な詳細については Google があなたのお友達です！
 
 
 ハッピーデバッギング！

docs/ja/cli.md

@@ -1,29 +1,19 @@
-# QMK CLI
+# QMK CLI :id=qmk-cli
 
 <!---
-  original document: d598f01cb:docs/cli.md
-  git diff d598f01cb HEAD -- docs/cli.md | cat
+  original document: 0.8.58:docs/cli.md
+  git diff 0.8.58 HEAD -- docs/cli.md | cat
 -->
 
-このページは QMK CLI のセットアップと使用方法について説明します。
-
-# 概要
+## 概要 :id=overview
 
 QMK CLI を使用すると QMK キーボードの構築と作業が簡単になります。QMK ファームウェアの取得とコンパイル、キーマップの作成などのようなタスクを簡素化し合理化するためのコマンドを多く提供します。
 
-* [グローバル CLI](#global-cli)
-* [ローカル CLI](#local-cli)
-* [CLI コマンド](#cli-commands)
+### 必要事項 :id=requirements
 
-# 必要事項
+CLI は Python 3.5 以上を必要とします。我々は必要事項の数を少なくしようとしていますが、[`requirements.txt`](https://github.com/qmk/qmk_firmware/blob/master/requirements.txt) に列挙されているパッケージもインストールする必要があります。これらは QMK CLI をインストールするときに自動的にインストールされます。
 
-CLI は Python 3.5 以上を必要とします。我々は必要事項の数を少なくしようとしていますが、[`requirements.txt`](https://github.com/qmk/qmk_firmware/blob/master/requirements.txt) にリストされているパッケージもインストールする必要があります。
-
-# グローバル CLI :id=global-cli
-
-QMK は、QMK ビルド環境のセットアップ、QMK の操作、および `qmk_firmware` の複数のコピーの操作を容易にできるインストール可能な CLI を提供します。これを定期的にインストールおよび更新することをお勧めします。
-
-## Homebrew を使ったインストール (macOS、いくつかの Linux)
+### Homebrew を使ったインストール (macOS、いくつかの Linux) :id=install-using-homebrew
 
 [Homebrew](https://brew.sh) をインストールしている場合は、タップして QMK をインストールすることができます:
 
@@ -34,7 +24,7 @@ export QMK_HOME='~/qmk_firmware' # オプション、`qmk_firmware` の場所を
 qmk setup  # これは `qmk/qmk_firmware` をクローンし、オプションでビルド環境をセットアップします
 ```
 
-## easy_install あるいは pip を使ってインストール
+### easy_install あるいは pip を使ってインストール :id=install-using-easy_install-or-pip
 
 上のリストにあなたのシステムがない場合は、QMK を手動でインストールすることができます。最初に、python 3.5 (以降)をインストールしていて、pip をインストールしていることを確認してください。次に以下のコマンドを使って QMK をインストールします:
 
@@ -44,7 +34,7 @@ export QMK_HOME='~/qmk_firmware' # オプション、`qmk_firmware` の場所を
 qmk setup  # これは `qmk/qmk_firmware` をクローンし、オプションでビルド環境をセットアップします
 ```
 
-## 他のオペレーティングシステムのためのパッケージ
+### 他のオペレーティングシステムのためのパッケージ :id=packaging-for-other-operating-systems
 
 より多くのオペレーティングシステム用に `qmk` パッケージを作成および保守する人を探しています。OS 用のパッケージを作成する場合は、以下のガイドラインに従ってください:
 
@@ -52,176 +42,3 @@ qmk setup  # これは `qmk/qmk_firmware` をクローンし、オプション
    * 逸脱する場合は、理由をコメントに文章化してください。
 * virtualenv を使ってインストールしてください
 * 環境変数 `QMK_HOME` を設定して、ファームウェアソースを `~/qmk_firmware` 以外のどこかにチェックアウトするようにユーザに指示してください。
-
-# ローカル CLI :id=local-cli
-
-グローバル CLI を使いたくない場合は、`qmk_firmware` に付属のローカル CLI があります。`qmk_firmware/bin/qmk` で見つけることができます。任意のディレクトリから `qmk` コマンドを実行でき、常に `qmk_firmware` のコピー上で動作します。
-
-**例**:
-
-```
-$ ~/qmk_firmware/bin/qmk hello
-Ψ Hello, World!
-```
-
-## ローカル CLI の制限
-
-グローバル CLI と比較して、ローカル CLI には幾つかの制限があります:
-
-* ローカル CLI は `qmk setup` あるいは `qmk clone` をサポートしません。
-* 複数のリポジトリがクローンされている場合でも、ローカル CLI は常に `qmk_firmware` ツリー上で動作します。
-* ローカル CLI は virtualenv で動作しません。そのため依存関係が競合する可能性があります
-
-# CLI コマンド :id=cli-commands
-
-## `qmk cformat`
-
-このコマンドは clang-format を使って C コードを整形します。引数無しで実行して全てのコアコードを整形するか、コマンドラインでファイル名を渡して特定のファイルに対して実行します。
-
-**使用法**:
-
-```
-qmk cformat [file1] [file2] [...] [fileN]
-```
-
-## `qmk compile`
-
-このコマンドにより、任意のディレクトリからファームウェアをコンパイルすることができます。<https://config.qmk.fm> からエクスポートした JSON をコンパイルするか、リポジトリ内でキーマップをコンパイルすることができます。
-
-**Configurator Exports での使い方**:
-
-```
-qmk compile <configuratorExport.json>
-```
-
-**キーマップでの使い方**:
-
-```
-qmk compile -kb <keyboard_name> -km <keymap_name>
-```
-
-## `qmk flash`
-
-このコマンドは `qmk compile` に似ていますが、ブートローダを対象にすることもできます。ブートローダはオプションで、デフォルトでは `:flash` に設定されています。
-違うブートローダを指定するには、`-bl <bootloader>` を使ってください。利用可能なブートローダの詳細については、<https://docs.qmk.fm/#/ja/flashing>
-を見てください。
-
-**Configurator Exports での使い方**:
-
-```
-qmk flash <configuratorExport.json> -bl <bootloader>
-```
-
-**キーマップでの使い方**:
-
-```
-qmk flash -kb <keyboard_name> -km <keymap_name> -bl <bootloader>
-```
-
-**ブートローダのリスト**
-
-```
-qmk flash -b
-```
-
-## `qmk config`
-
-このコマンドにより QMK の挙動を設定することができます。完全な `qmk config` のドキュメントについては、[CLI 設定](ja/cli_configuration.md)を見てください。
-
-**使用法**:
-
-```
-qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN]
-```
-
-## `qmk docs`
-
-このコマンドは、ドキュメントを参照または改善するために使うことができるローカル HTTP サーバを起動します。デフォルトのポートは 8936 です。
-
-**使用法**:
-
-```
-qmk docs [-p PORT]
-```
-
-## `qmk doctor`
-
-このコマンドは環境を調査し、潜在的なビルドあるいは書き込みの問題について警告します。
-
-**使用法**:
-
-```
-qmk doctor
-```
-
-## `qmk json-keymap`
-
-QMK Configurator からエクスポートしたものから keymap.c を生成します。
-
-**使用法**:
-
-```
-qmk json-keymap [-o OUTPUT] filename
-```
-
-## `qmk kle2json`
-
-このコマンドにより、生の KLE データから QMK Configurator の JSON へ変換することができます。絶対パスあるいは現在のディレクトリ内のファイル名のいずれかを受け取ります。デフォルトでは、`info.json` が既に存在している場合は上書きしません。上書きするには、`-f` あるいは `--force` フラグを使ってください。
-
-**使用法**:
-
-```
-qmk kle2json [-f] <filename>
-```
-
-**例**:
-
-```
-$ qmk kle2json kle.txt 
-☒ File info.json already exists, use -f or --force to overwrite.
-```
-
-```
-$ qmk kle2json -f kle.txt -f
-Ψ Wrote out to info.json
-```
-
-## `qmk list-keyboards`
-
-このコマンドは現在 `qmk_firmware` で定義されている全てのキーボードをリスト化します。
-
-**使用法**:
-
-```
-qmk list-keyboards
-```
-
-## `qmk new-keymap`
-
-このコマンドは、キーボードの既存のデフォルトのキーマップに基づいて新しいキーマップを作成します。
-
-**使用法**:
-
-```
-qmk new-keymap [-kb KEYBOARD] [-km KEYMAP]
-```
-
-## `qmk pyformat`
-
-このコマンドは `qmk_firmware` 内の python コードを整形します。
-
-**使用法**:
-
-```
-qmk pyformat
-```
-
-## `qmk pytest`
-
-このコマンドは python のテストスィートを実行します。python コードに変更を加えた場合、これの実行が成功することを確認する必要があります。
-
-**使用法**:
-
-```
-qmk pytest
-```

docs/ja/cli_commands.md

@@ -0,0 +1,258 @@
+# QMK CLI コマンド
+
+<!---
+  original document: 0.8.58:docs/cli.md
+  git diff 0.8.58 HEAD -- docs/cli.md | cat
+-->
+
+# CLI コマンド
+
+## `qmk cformat`
+
+このコマンドは clang-format を使って C コードを整形します。
+
+引数無しで実行すると、変更された全てのコアコードを整形します。デフォルトでは `git diff` で `origin/master` をチェックし、ブランチは `-b <branch_name>` を使って変更できます。
+
+`-a` で全てのコアコードを整形するか、コマンドラインでファイル名を渡して特定のファイルに対して実行します。
+
+**指定したファイルに対する使い方**:
+
+```
+qmk cformat [file1] [file2] [...] [fileN]
+```
+
+**全てのコアファイルに対する使い方**:
+
+```
+qmk cformat -a
+```
+
+**origin/master で変更されたファイルのみに対する使い方**:
+
+```
+qmk cformat
+```
+
+**branch_name で変更されたファイルのみに対する使い方**:
+
+```
+qmk cformat -b branch_name
+```
+
+## `qmk compile`
+
+このコマンドにより、任意のディレクトリからファームウェアをコンパイルすることができます。<https://config.qmk.fm> からエクスポートした JSON をコンパイルするか、リポジトリ内でキーマップをコンパイルするか、現在の作業ディレクトリでキーボードをコンパイルすることができます。
+
+**Configurator Exports での使い方**:
+
+```
+qmk compile <configuratorExport.json>
+```
+
+**キーマップでの使い方**:
+
+```
+qmk compile -kb <keyboard_name> -km <keymap_name>
+```
+
+**キーボードディレクトリでの使い方**:  
+
+default キーマップのあるキーボードディレクトリ、キーボードのキーマップディレクトリ、`--keymap <keymap_name>` で与えられるキーマップディレクトリにいなければなりません。
+```
+qmk compile
+```
+
+**指定したキーマップをサポートする全てのキーボードをビルドする場合の使い方**:
+
+```
+qmk compile -kb all -km <keymap_name>
+```
+
+**例**:
+```
+$ qmk config compile.keymap=default
+$ cd ~/qmk_firmware/keyboards/planck/rev6
+$ qmk compile
+Ψ Compiling keymap with make planck/rev6:default
+...
+```
+あるいはオプションのキーマップ引数を指定して
+
+```
+$ cd ~/qmk_firmware/keyboards/clueboard/66/rev4
+$ qmk compile -km 66_iso
+Ψ Compiling keymap with make clueboard/66/rev4:66_iso
+...
+```
+あるいはキーマップディレクトリで
+
+```
+$ cd ~/qmk_firmware/keyboards/gh60/satan/keymaps/colemak
+$ qmk compile
+Ψ Compiling keymap with make make gh60/satan:colemak
+...
+```
+
+**レイアウトディレクトリでの使い方**:  
+
+`qmk_firmware/layouts/` 以下のキーマップディレクトリにいなければなりません。
+```
+qmk compile -kb <keyboard_name>
+```
+
+**例**:
+```
+$ cd ~/qmk_firmware/layouts/community/60_ansi/mechmerlin-ansi
+$ qmk compile -kb dz60
+Ψ Compiling keymap with make dz60:mechmerlin-ansi
+...
+```
+
+## `qmk flash`
+
+このコマンドは `qmk compile` に似ていますが、ブートローダを対象にすることもできます。ブートローダはオプションで、デフォルトでは `:flash` に設定されています。
+違うブートローダを指定するには、`-bl <bootloader>` を使ってください。利用可能なブートローダの詳細については、[ファームウェアを書き込む](ja/flashing.md)を見てください。
+
+**Configurator Exports での使い方**:
+
+```
+qmk flash <configuratorExport.json> -bl <bootloader>
+```
+
+**キーマップでの使い方**:
+
+```
+qmk flash -kb <keyboard_name> -km <keymap_name> -bl <bootloader>
+```
+
+**ブートローダの列挙**
+
+```
+qmk flash -b
+```
+
+## `qmk config`
+
+このコマンドにより QMK の挙動を設定することができます。完全な `qmk config` のドキュメントについては、[CLI 設定](ja/cli_configuration.md)を見てください。
+
+**使用法**:
+
+```
+qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN]
+```
+
+## `qmk docs`
+
+このコマンドは、ドキュメントを参照または改善するために使うことができるローカル HTTP サーバを起動します。デフォルトのポートは 8936 です。
+
+**使用法**:
+
+```
+qmk docs [-p PORT]
+```
+
+## `qmk doctor`
+
+このコマンドは環境を調査し、潜在的なビルドあるいは書き込みの問題について警告します。必要に応じてそれらの多くを修正できます。
+
+**使用法**:
+
+```
+qmk doctor [-y] [-n]
+```
+
+**例**:
+
+環境に問題がないか確認し、それらを修正するよう促します:
+
+    qmk doctor
+
+環境を確認し、見つかった問題を自動的に修正します:
+
+    qmk doctor -y
+
+環境を確認し、問題のみをレポートします:
+
+    qmk doctor -n
+
+## `qmk json2c`
+
+QMK Configurator からエクスポートしたものから keymap.c を生成します。
+
+**使用法**:
+
+```
+qmk json2c [-o OUTPUT] filename
+```
+
+## `qmk kle2json`
+
+このコマンドにより、生の KLE データから QMK Configurator の JSON へ変換することができます。絶対パスあるいは現在のディレクトリ内のファイル名のいずれかを受け取ります。デフォルトでは、`info.json` が既に存在している場合は上書きしません。上書きするには、`-f` あるいは `--force` フラグを使ってください。
+
+**使用法**:
+
+```
+qmk kle2json [-f] <filename>
+```
+
+**例**:
+
+```
+$ qmk kle2json kle.txt 
+☒ File info.json already exists, use -f or --force to overwrite.
+```
+
+```
+$ qmk kle2json -f kle.txt -f
+Ψ Wrote out to info.json
+```
+
+## `qmk list-keyboards`
+
+このコマンドは現在 `qmk_firmware` で定義されている全てのキーボードを列挙します。
+
+**使用法**:
+
+```
+qmk list-keyboards
+```
+
+## `qmk list-keymaps`
+
+このコマンドは指定されたキーボード(とリビジョン)の全てのキーマップを列挙します。
+
+**使用法**:
+
+```
+qmk list-keymaps -kb planck/ez
+```
+
+## `qmk new-keymap`
+
+このコマンドは、キーボードの既存のデフォルトのキーマップに基づいて新しいキーマップを作成します。
+
+**使用法**:
+
+```
+qmk new-keymap [-kb KEYBOARD] [-km KEYMAP]
+```
+
+## `qmk pyformat`
+
+このコマンドは `qmk_firmware` 内の python コードを整形します。
+
+**使用法**:
+
+```
+qmk pyformat
+```
+
+## `qmk pytest`
+
+このコマンドは python のテストスィートを実行します。python コードに変更を加えた場合、これの実行が成功することを確認する必要があります。
+
+**使用法**:
+
+```
+qmk pytest
+```

docs/ja/config_options.md

@@ -1,8 +1,8 @@
 # QMK の設定
 
 <!---
-  original document: 0f43c2652:docs/config_options.md
-  git diff 0f43c2652 HEAD -- docs/config_options.md | cat
+  original document: 0.8.62:docs/config_options.md
+  git diff 0.8.62 HEAD -- docs/config_options.md | cat
 -->
 
 QMK はほぼ無制限に設定可能です。可能なところはいかなるところでも、やりすぎな程、ユーザーがコードサイズを犠牲にしてでも彼らのキーボードをカスタマイズをすることを許しています。ただし、このレベルの柔軟性により設定が困難になります。
@@ -39,165 +39,173 @@ QMK での全ての利用可能な設定にはデフォルトがあります。
 
 ## ハードウェアオプション
 * `#define VENDOR_ID 0x1234`
-   * VID を定義します。ほとんどの DIY プロジェクトにおいて、任意のものを定義できます
+  * VID を定義します。ほとんどの DIY プロジェクトにおいて、任意のものを定義できます
 * `#define PRODUCT_ID 0x5678`
-   * PID を定義します。ほとんどの DIY プロジェクトでは、任意のものを定義できます
+  * PID を定義します。ほとんどの DIY プロジェクトでは、任意のものを定義できます
 * `#define DEVICE_VER 0`
-   * デバイスのバージョンを定義します (多くの場合リビジョンに使われます)
+  * デバイスのバージョンを定義します (多くの場合リビジョンに使われます)
 * `#define MANUFACTURER Me`
-   * 一般的に、誰もしくはどのブランドがボードを作成したか
+  * 一般的に、誰もしくはどのブランドがボードを作成したか
 * `#define PRODUCT Board`
-   * キーボードの名前
+  * キーボードの名前
 * `#define DESCRIPTION a keyboard`
-   * キーボードの簡単な説明
+  * キーボードの簡単な説明
 * `#define MATRIX_ROWS 5`
-   * キーボードのマトリックスの行の数
+  * キーボードのマトリックスの行の数
 * `#define MATRIX_COLS 15`
-   * キーボードのマトリックスの列の数
+  * キーボードのマトリックスの列の数
 * `#define MATRIX_ROW_PINS { D0, D5, B5, B6 }`
-   * 行のピン、上から下へ
+  * 行のピン、上から下へ
 * `#define MATRIX_COL_PINS { F1, F0, B0, C7, F4, F5, F6, F7, D4, D6, B4, D7 }`
-   * 列のピン、左から右へ
+  * 列のピン、左から右へ
+* `#define MATRIX_IO_DELAY 30`
+  * マトリックスピン状態の変更と値の読み取り間のマイクロ秒単位の遅延
 * `#define UNUSED_PINS { D1, D2, D3, B1, B2, B3 }`
-   * 参考として、キーボードで使われていないピン
+  * 参考として、キーボードで使われていないピン
 * `#define MATRIX_HAS_GHOST`
-   * マトリックスにゴーストがあるか(ありそうにないか)定義します
+  * マトリックスにゴーストがあるか(ありそうにないか)定義します
 * `#define DIODE_DIRECTION COL2ROW`
-   * COL2ROW あるいは ROW2COL - マトリックスがどのように設定されているか。COL2ROW は、スイッチとロウ(行)ラインの間にダイオードが黒い印をロウ(行)ラインに向けて置いてあることを意味します。
+  * COL2ROW あるいは ROW2COL - マトリックスがどのように設定されているか。COL2ROW は、スイッチとロウ(行)ラインの間にダイオードが黒い印をロウ(行)ラインに向けて置いてあることを意味します。
 * `#define DIRECT_PINS { { F1, F0, B0, C7 }, { F4, F5, F6, F7 } }`
-   * ロウ(行)ラインとカラム(列)ラインにマップされているピンを左から右に。各スイッチが個別のピンとグラウンドに接続されているマトリックスを定義します。
+  * ロウ(行)ラインとカラム(列)ラインにマップされているピンを左から右に。各スイッチが個別のピンとグラウンドに接続されているマトリックスを定義します。
 * `#define AUDIO_VOICES`
-   * (循環させるために)代替音声を有効にします
+  * (循環させるために)代替音声を有効にします
 * `#define C4_AUDIO`
-   * ピン C4 のオーディオを有効にします
+  * ピン C4 のオーディオを有効にします
 * `#define C5_AUDIO`
-   * ピン C5 のオーディオを有効にします
+  * ピン C5 のオーディオを有効にします
 * `#define C6_AUDIO`
-   * ピン C6 のオーディオを有効にします
+  * ピン C6 のオーディオを有効にします
 * `#define B5_AUDIO`
-   * ピン B5 のオーディオを有効にします (C[4-6]\_AUDIO の1つとともに B[5-7]\_AUDIO の1つが有効にされている場合、疑似ステレオが有効にされます)
+  * ピン B5 のオーディオを有効にします (C[4-6]\_AUDIO の1つとともに B[5-7]\_AUDIO の1つが有効にされている場合、疑似ステレオが有効にされます)
 * `#define B6_AUDIO`
-   * ピン B6 のオーディオを有効にします (C[4-6]\_AUDIO の1つとともに B[5-7]\_AUDIO の1つが有効にされている場合、疑似ステレオが有効にされます)
+  * ピン B6 のオーディオを有効にします (C[4-6]\_AUDIO の1つとともに B[5-7]\_AUDIO の1つが有効にされている場合、疑似ステレオが有効にされます)
 * `#define B7_AUDIO`
-   * ピン B7 のオーディオを有効にします (C[4-6]\_AUDIO の1つとともに B[5-7]\_AUDIO の1つが有効にされている場合、疑似ステレオが有効にされます)
+  * ピン B7 のオーディオを有効にします (C[4-6]\_AUDIO の1つとともに B[5-7]\_AUDIO の1つが有効にされている場合、疑似ステレオが有効にされます)
 * `#define BACKLIGHT_PIN B7`
-   * バックライトのピン
+  * バックライトのピン
 * `#define BACKLIGHT_LEVELS 3`
-   * バックライトのレベル数 (off を除いて最大15)
+  * バックライトのレベル数 (off を除いて最大31)
 * `#define BACKLIGHT_BREATHING`
-   * バックライトのブレスを有効にします
+  * バックライトのブレスを有効にします
 * `#define BREATHING_PERIOD 6`
-   * 1つのバックライトの "ブレス" の長さの秒数
+  * 1つのバックライトの "ブレス" の長さの秒数
 * `#define DEBOUNCE 5`
-   * ピンの値を読み取る時の遅延 (5がデフォルト)
+  * ピンの値を読み取る時の遅延 (5がデフォルト)
 * `#define LOCKING_SUPPORT_ENABLE`
-   * メカニカルロックのサポート。キーマップで KC_LCAP、 KC_LNUM そして KC_LSCR を使えるようにします
+  * メカニカルロックのサポート。キーマップで KC_LCAP、 KC_LNUM そして KC_LSCR を使えるようにします
 * `#define LOCKING_RESYNC_ENABLE`
-   * キーボードの LED の状態をスイッチの状態と一致させ続けようとします
+  * キーボードの LED の状態をスイッチの状態と一致させ続けようとします
 * `#define IS_COMMAND() (get_mods() == MOD_MASK_SHIFT)`
-   * マジックコマンドの使用を可能にするキーの組み合わせ (デバッグに便利です)
+  * マジックコマンドの使用を可能にするキーの組み合わせ (デバッグに便利です)
 * `#define USB_MAX_POWER_CONSUMPTION 500`
-   * デバイスの USB 経由の最大電力(mA) を設定します (デフォルト: 500)
+  * デバイスの USB 経由の最大電力(mA) を設定します (デフォルト: 500)
 * `#define USB_POLLING_INTERVAL_MS 10`
-   * キーボード、マウス および 共有 (NKRO/メディアキー) インタフェースのための USB ポーリングレートをミリ秒で設定します
+  * キーボード、マウス および 共有 (NKRO/メディアキー) インタフェースのための USB ポーリングレートをミリ秒で設定します
 * `#define F_SCL 100000L`
-   * I2C を使用するキーボードのための I2C クロックレート速度を設定します。デフォルトは `400000L` ですが、`split_common` を使っているキーボードは別でデフォルトは `100000L` です。
+  * I2C を使用するキーボードのための I2C クロックレート速度を設定します。デフォルトは `400000L` ですが、`split_common` を使っているキーボードは別でデフォルトは `100000L` です。
 
 ## 無効にできる機能
 
 これらのオプションを定義すると、関連する機能が無効になり、コードサイズを節約できます。
 
 * `#define NO_DEBUG`
-   * デバッグを無効にします
+  * デバッグを無効にします
 * `#define NO_PRINT`
-   * hid_listen を使った出力やデバッグを無効にします
+  * hid_listen を使った出力やデバッグを無効にします
 * `#define NO_ACTION_LAYER`
-   * レイヤーを無効にします
+  * レイヤーを無効にします
 * `#define NO_ACTION_TAPPING`
-   * タップダンスと他のタップ機能を無効にします
+  * タップダンスと他のタップ機能を無効にします
 * `#define NO_ACTION_ONESHOT`
-   * ワンショットモディファイアを無効にします
+  * ワンショットモディファイアを無効にします
 * `#define NO_ACTION_MACRO`
-   * 古い形式のマクロ処理を無効にします: MACRO() & action_get_macro
+  * 古い形式のマクロ処理を無効にします: MACRO() & action_get_macro
 * `#define NO_ACTION_FUNCTION`
-   * fn_actions 配列(非推奨)からの action_function() の呼び出しを無効にします 
+  * fn_actions 配列(非推奨)からの action_function() の呼び出しを無効にします 
 
 ## 有効にできる機能
 
 これらのオプションを定義すると、関連する機能が有効になり、コードサイズが大きくなるかもしれません。
 
 * `#define FORCE_NKRO`
-   * NKRO をデフォルトでオンにする必要があります。これにより EEPROM の設定に関係なく、キーボードの起動時に NKRO が強制的にオンになります。NKRO は引き続きオフにできますが、キーボードを再起動すると再びオンになります。
+  * NKRO をデフォルトでオンにする必要があります。これにより EEPROM の設定に関係なく、キーボードの起動時に NKRO が強制的にオンになります。NKRO は引き続きオフにできますが、キーボードを再起動すると再びオンになります。
 * `#define STRICT_LAYER_RELEASE`
-   * キーリリースがどのレイヤーから来たのかを覚えるのではなく、現在のレイヤースタックを使って強制的に評価されるようにします (高度なケースに使われます)
+  * キーリリースがどのレイヤーから来たのかを覚えるのではなく、現在のレイヤースタックを使って強制的に評価されるようにします (高度なケースに使われます)
 
 ## 設定可能な挙動
 
 * `#define TAPPING_TERM 200`
-   * タップがホールドになるまでの時間。500以上に設定された場合、タップ期間中にタップされたキーもホールドになります。(訳注: PERMISSIVE_HOLDも参照)
+  * タップがホールドになるまでの時間。500以上に設定された場合、タップ期間中にタップされたキーもホールドになります。(訳注: PERMISSIVE_HOLDも参照)
 * `#define TAPPING_TERM_PER_KEY`
-   * キーごとの `TAPPING_TERM` 設定の処理を有効にします
+  * キーごとの `TAPPING_TERM` 設定の処理を有効にします
 * `#define RETRO_TAPPING`
-   * 押下とリリースの間に他のキーによる中断がなければ、TAPPING_TERM の後であってもとにかくタップします
-   * 詳細は [Retro Tapping](ja/feature_advanced_keycodes.md#retro-tapping) を見てください
+  * 押下とリリースの間に他のキーによる中断がなければ、TAPPING_TERM の後であってもとにかくタップします
+  * 詳細は [Retro Tapping](ja/tap_hold.md#retro-tapping) を見てください
 * `#define TAPPING_TOGGLE 2`
-   * トグルを引き起こす前のタップ数
+  * トグルを引き起こす前のタップ数
 * `#define PERMISSIVE_HOLD`
-   * `TAPPING_TERM` にヒットしていなくても、リリースする前に別のキーが押されると、タップとフォールドキーがホールドを引き起こします
-   * 詳細は [Permissive Hold](ja/feature_advanced_keycodes.md#permissive-hold) を見てください
+  * `TAPPING_TERM` にヒットしていなくても、リリースする前に別のキーが押されると、タップとホールドキーがホールドを引き起こします
+  * 詳細は [Permissive Hold](ja/tap_hold.md#permissive-hold) を見てください
+* `#define PERMISSIVE_HOLD_PER_KEY`
+  * キーごとの `PERMISSIVE_HOLD` 設定の処理を有効にします
 * `#define IGNORE_MOD_TAP_INTERRUPT`
-   * 両方のキーに `TAPPING_TERM` を適用することで、ホールド時に他のキーに変換するキーを使ってローリングコンボ (zx) をすることができるようにします
-   * 詳細は [Mod tap interrupt](ja/feature_advanced_keycodes.md#ignore-mod-tap-interrupt) を見てください
+  * 両方のキーに `TAPPING_TERM` を適用することで、ホールド時に他のキーに変換するキーを使ってローリングコンボ (zx) をすることができるようにします
+  * 詳細は [Ignore Mod Tap Interrupt](ja/tap_hold.md#ignore-mod-tap-interrupt) を見てください
 * `#define IGNORE_MOD_TAP_INTERRUPT_PER_KEY`
-   * キーごとの `IGNORE_MOD_TAP_INTERRUPT` 設定の処理を有効にします
+  * キーごとの `IGNORE_MOD_TAP_INTERRUPT` 設定の処理を有効にします
 * `#define TAPPING_FORCE_HOLD`
-   * タップされた直後に、デュアルロールキーを修飾子として使用できるようにします
-   * [Hold after tap](ja/feature_advanced_keycodes.md#tapping-force-hold)を見てください
-   * タップトグル機能を無効にします (`TT` あるいは One Shot Tap Toggle)
+  * タップされた直後に、デュアルロールキーを修飾子として使用できるようにします
+  * [Tapping Force Hold](ja/tap_hold.md#tapping-force-hold)を見てください
+  * タップトグル機能を無効にします (`TT` あるいは One Shot Tap Toggle)
+* `#define TAPPING_FORCE_HOLD_PER_KEY`
+  * キーごとの `TAPPING_FORCE_HOLD` 設定処理を有効にします。
 * `#define LEADER_TIMEOUT 300`
-   * リーダーキーがタイムアウトするまでの時間
-      * タイムアウトする前にシーケンスを終了できない場合は、タイムアウトの設定を増やす必要があるかもしれません。あるいは、`LEADER_PER_KEY_TIMING` オプションを有効にすると良いでしょう。これは各キーがタップされた後でタイムアウトを再設定します。
+  * リーダーキーがタイムアウトするまでの時間
+    * タイムアウトする前にシーケンスを終了できない場合は、タイムアウトの設定を増やす必要があるかもしれません。あるいは、`LEADER_PER_KEY_TIMING` オプションを有効にすると良いでしょう。これは各キーがタップされた後でタイムアウトを再設定します。
 * `#define LEADER_PER_KEY_TIMING`
-   * 全体では無く各キーを押すたびに実行されるリーダーキーコードのタイマーを設定します
+  * 全体では無く各キーを押すたびに実行されるリーダーキーコードのタイマーを設定します
 * `#define LEADER_KEY_STRICT_KEY_PROCESSING`
-   * Mod-Tap および Layer-Tap キーコードのためのキーコードフィルタリングを無効にします。例えば、これを有効にすると、`KC_A` を使いたい場合は `MT(MOD_CTL, KC_A)` を指定する必要があります。
+  * Mod-Tap および Layer-Tap キーコードのためのキーコードフィルタリングを無効にします。例えば、これを有効にすると、`KC_A` を使いたい場合は `MT(MOD_CTL, KC_A)` を指定する必要があります。
 * `#define ONESHOT_TIMEOUT 300`
-   * ワンショットがタイムアウトするまでの時間
+  * ワンショットがタイムアウトするまでの時間
 * `#define ONESHOT_TAP_TOGGLE 2`
-   * ワンショットトグルが引き起こされるまでのタップ数
+  * ワンショットトグルが引き起こされるまでのタップ数
 * `#define QMK_KEYS_PER_SCAN 4`
-   * 走査ごとに1つ以上のキーを送信できるようにします。デフォルトでは、走査ごとに `process_record()` 経由で1つのキーイベントのみが送信されます。これはほとんどのタイピングにほとんど影響しませんが、多くのコードを入力しているか、走査レートが最初から遅い場合、キーイベントの処理に多少の遅延が生じる可能性があります。それぞれのプレスとリリースは別のイベントです。スキャン時間が 1ms 程度のキーボードの場合、とても高速なタイピストでさえ、実際にキーボードから数 ms 以上の遅延を発生させるのに必要な 500 キーストロークを1秒間に生成することはないでしょう。しかし、3～4ms の走査時間でコードを入力している場合はどうでしょうか？おそらくこれが必要です。
+  * 走査ごとに1つ以上のキーを送信できるようにします。デフォルトでは、走査ごとに `process_record()` 経由で1つのキーイベントのみが送信されます。これはほとんどのタイピングにほとんど影響しませんが、多くのコードを入力しているか、走査レートが最初から遅い場合、キーイベントの処理に多少の遅延が生じる可能性があります。それぞれのプレスとリリースは別のイベントです。スキャン時間が 1ms 程度のキーボードの場合、とても高速なタイピストでさえ、実際にキーボードから数 ms 以上の遅延を発生させるのに必要な 500 キーストロークを1秒間に生成することはないでしょう。しかし、3～4ms の走査時間でコードを入力している場合はどうでしょうか？おそらくこれが必要です。
 * `#define COMBO_COUNT 2`
-   * [コンボ](ja/feature_combo.md)機能で使っているコンボの数にこれを設定します。
+  * [コンボ](ja/feature_combo.md)機能で使っているコンボの数にこれを設定します。
 * `#define COMBO_TERM 200`
-   * コンボキーが検出されるまでの時間。定義されていない場合は、デフォルトは `TAPPING_TERM` です。
+  * コンボキーが検出されるまでの時間。定義されていない場合は、デフォルトは `TAPPING_TERM` です。
 * `#define TAP_CODE_DELAY 100`
-   * 適切な登録に問題がある場合(VUSB ボードで珍しくない)、`register_code` と `unregister_code` の間の遅延を設定します。値はミリ秒です。
+  * 適切な登録に問題がある場合(VUSB ボードで珍しくない)、`register_code` と `unregister_code` の間の遅延を設定します。値はミリ秒です。
 * `#define TAP_HOLD_CAPS_DELAY 80`
-   * MacOS で特別な処理が行われるため、`KC_CAPSLOCK` を使う時にタップホールドキー (`LT`, `MT`) に遅延を設定します。この値はミリ秒で、定義されていない場合はデフォルトは80msです。macOS については、これを200以上に設定すると良いでしょう。
+  * MacOS で特別な処理が行われるため、`KC_CAPSLOCK` を使う時にタップホールドキー (`LT`, `MT`) に遅延を設定します。この値はミリ秒で、定義されていない場合はデフォルトは80msです。macOS については、これを200以上に設定すると良いでしょう。
 
 ## RGB ライト設定 :id=rgb-light-configuration
 
 * `#define RGB_DI_PIN D7`
-   * WS2812 の DI 端子につなぐピン
+  * WS2812 の DI 端子につなぐピン
 * `#define RGBLIGHT_ANIMATIONS`
-   * RGB アニメーションを実行します
+  * RGB アニメーションを実行します
+* `#define RGBLIGHT_LAYERS`
+  * オンとオフを切り替えることができる [ライトレイヤー](ja/feature_rgblight.md) を定義できます。現在のキーボードレイヤーまたは Caps Lock 状態を表示するのに最適です。
 * `#define RGBLED_NUM 12`
-   * LED の数
+  * LED の数
 * `#define RGBLIGHT_SPLIT`
-   * 分割キーボードの左半分の RGB LED の出力を右半分の RGB LED の入力につなげるかわりに、それぞれの側で個別にコントローラの出力ピンが直接 RGB LED の入力に繋がっているときは、この定義が必要です。
+  * 分割キーボードの左半分の RGB LED の出力を右半分の RGB LED の入力につなげるかわりに、それぞれの側で個別にコントローラの出力ピンが直接 RGB LED の入力に繋がっているときは、この定義が必要です。
 * `#define RGBLED_SPLIT { 6, 6 }`
-   * 分割キーボードの各半分の `RGB_DI_PIN` に直接配線されている接続されているLEDの数
-   * 最初の値は左半分の LED の数を示し、2番目の値は右半分です。
-   * RGBLED_SPLIT が定義されている場合、RGBLIGHT_SPLIT は暗黙的に定義されます。
+  * 分割キーボードの各半分の `RGB_DI_PIN` に直接配線されている接続されている LED の数
+  * 最初の値は左半分の LED の数を示し、2番目の値は右半分です。
+  * RGBLED_SPLIT が定義されている場合、RGBLIGHT_SPLIT は暗黙的に定義されます。
 * `#define RGBLIGHT_HUE_STEP 12`
-   * 色相の増減時のステップ単位
+  * 色相の増減時のステップ単位
 * `#define RGBLIGHT_SAT_STEP 25`
-   * 彩度の増減時のステップ単位
+  * 彩度の増減時のステップ単位
 * `#define RGBLIGHT_VAL_STEP 12`
-   * 値(明度)の増減時のステップ単位
+  * 値(明度)の増減時のステップ単位
 * `#define RGBW`
-   * RGBW LED のサポートを有効にします
+  * RGBW LED のサポートを有効にします
 
 ## マウスキーオプション
 
@@ -212,11 +220,11 @@ QMK での全ての利用可能な設定にはデフォルトがあります。
 分割キーボード固有のオプション。あなたの rules.mk に 'SPLIT_KEYBOARD = yes' が有ることを確認してください。
 
 * `SPLIT_TRANSPORT = custom`
-   * 標準の分割通信ルーチンをカスタムのものに置き換えることができます。現在、ARM ベースの分割キーボードはこれを使わなければなりません。
+  * 標準の分割通信ルーチンをカスタムのものに置き換えることができます。現在、ARM ベースの分割キーボードはこれを使わなければなりません。
 
 ### 左右の設定
 
-一つ覚えておかなければならないことは、USB ポートが接続されている側が常にマスター側であるということです。USB に接続されていない側はスレーブです。
+1つ覚えておかなければならないことは、USB ポートが接続されている側が常にマスター側であるということです。USB に接続されていない側はスレーブです。
 
 分割キーボードの左右を設定するには、幾つかの異なる方法があります (優先度の順にリストされています):
 
@@ -231,49 +239,52 @@ QMK での全ての利用可能な設定にはデフォルトがあります。
 #### 左右を定義します
 
 * `#define SPLIT_HAND_PIN B7`
-   * high/low ピンを使って左右を決定します。low = 右手、high = 左手。`B7` を使っているピンに置き換えます。これはオプションで、`SPLIT_HAND_PIN` が未定義のままである場合、EE_HANDS メソッドまたは標準の Let's Splitが使っている MASTER_LEFT / MASTER_RIGHT 定義をまだ使うことができます。
+  * high/low ピンを使って左右を決定します。low = 右手、high = 左手。`B7` を使っているピンに置き換えます。これはオプションで、`SPLIT_HAND_PIN` が未定義のままである場合、EE_HANDS メソッドまたは標準の Let's Splitが使っている MASTER_LEFT / MASTER_RIGHT 定義をまだ使うことができます。
 
 * `#define EE_HANDS` (`SPLIT_HAND_PIN` が定義されていない場合のみ動作します)
-   * `eeprom-lefthand.eep`/`eeprom-righthand.eep` がそれぞれの半分に書き込まれた後で、EEPROM 内に格納されている左右の設定の値を読み込みます。
+  * `eeprom-lefthand.eep`/`eeprom-righthand.eep` がそれぞれの半分に書き込まれた後で、EEPROM 内に格納されている左右の設定の値を読み込みます。
 
 * `#define MASTER_RIGHT`
-   * マスター側が右側と定義されます。
+  * マスター側が右側と定義されます。
 
 ### 他のオプション
 
 * `#define USE_I2C`
-   * Serial の代わりに I2C を使う場合 (デフォルトは serial)
+  * Serial の代わりに I2C を使う場合 (デフォルトは serial)
 
 * `#define SOFT_SERIAL_PIN D0`
-   * serial を使う場合、これを定義します。`D0` あるいは `D1`,`D2`,`D3`,`E6`。
+  * serial を使う場合、これを定義します。`D0` あるいは `D1`,`D2`,`D3`,`E6`。
 
 * `#define MATRIX_ROW_PINS_RIGHT { <row pins> }`
 * `#define MATRIX_COL_PINS_RIGHT { <col pins> }`
-   * 右半分に左半分と異なるピン配置を指定したい場合は、`MATRIX_ROW_PINS_RIGHT`/`MATRIX_COL_PINS_RIGHT` を定義することができます。現在のところ、`MATRIX_ROW_PINS` のサイズは `MATRIX_ROW_PINS_RIGHT` と同じでなければならず、列の定義も同様です。
+  * 右半分に左半分と異なるピン配置を指定したい場合は、`MATRIX_ROW_PINS_RIGHT`/`MATRIX_COL_PINS_RIGHT` を定義することができます。現在のところ、`MATRIX_ROW_PINS` のサイズは `MATRIX_ROW_PINS_RIGHT` と同じでなければならず、列の定義も同様です。
 
 * `#define DIRECT_PINS_RIGHT { { F1, F0, B0, C7 }, { F4, F5, F6, F7 } }`
-   * 右半分に左半分と異なる直接ピン配置を指定したい場合は、`DIRECT_PINS_RIGHT` を定義することができます。現在のところ、`DIRECT_PINS` のサイズは `DIRECT_PINS_RIGHT` と同じでなければなりません。
+  * 右半分に左半分と異なる直接ピン配置を指定したい場合は、`DIRECT_PINS_RIGHT` を定義することができます。現在のところ、`DIRECT_PINS` のサイズは `DIRECT_PINS_RIGHT` と同じでなければなりません。
 
 * `#define RGBLED_SPLIT { 6, 6 }`
-   * [RGB ライト設定](#rgb-light-configuration)を見てください。
+  * [RGB ライト設定](#rgb-light-configuration)を見てください。
 
 * `#define SELECT_SOFT_SERIAL_SPEED <speed>` (デフォルトの速度は1です)
-   * serial 通信を使う時のプロトコルの速度を設定します。
-   * 速度:
-      * 0: 約189kbps (実験目的のみ)
-      * 1: 約 137kbps (デフォルト)
-      * 2: 約 75kbps
-      * 3: 約 39kbps
-      * 4: 約 26kbps
-      * 5: 約 20kbps
+  * serial 通信を使う時のプロトコルの速度を設定します。
+  * 速度:
+    * 0: 約 189kbps (実験目的のみ)
+    * 1: 約 137kbps (デフォルト)
+    * 2: 約 75kbps
+    * 3: 約 39kbps
+    * 4: 約 26kbps
+    * 5: 約 20kbps
 
 * `#define SPLIT_USB_DETECT`
-   * マスタ/スレーブを委任する時に(タイムアウト付きで) USB 接続を検出します
-   * ARM についてはデフォルトの挙動
-   * AVR Teensy については必須
+  * マスタ/スレーブを委任する時に(タイムアウト付きで) USB 接続を検出します
+  * ARM についてはデフォルトの挙動
+  * AVR Teensy については必須
 
-* `#define SPLIT_USB_TIMEOUT 2500`
-   * `SPLIT_USB_DETECT` を使う時のマスタ/スレーブを検出する場合の最大タイムアウト
+* `#define SPLIT_USB_TIMEOUT 2000`
+  * `SPLIT_USB_DETECT` を使う時のマスタ/スレーブを検出する場合の最大タイムアウト
+
+* `#define SPLIT_USB_TIMEOUT_POLL 10`
+  * `SPLIT_USB_DETECT` を使う時のマスタ/スレーブを検出する場合のポーリング頻度
 
 # `rules.mk` ファイル
 
@@ -282,11 +293,11 @@ QMK での全ての利用可能な設定にはデフォルトがあります。
 ## ビルドオプション
 
 * `DEFAULT_FOLDER`
-   * キーボードに1つ以上のサブフォルダがある場合にデフォルトのフォルダを指定するために使われます。
+  * キーボードに1つ以上のサブフォルダがある場合にデフォルトのフォルダを指定するために使われます。
 * `FIRMWARE_FORMAT`
-   * ビルドの後でルート `qmk_firmware` フォルダにコピーされる形式 (bin, hex) を定義します。
+  * ビルドの後でルート `qmk_firmware` フォルダにコピーされる形式 (bin, hex) を定義します。
 * `SRC`
-   * コンパイル・リンクリストにファイルを追加するために使われます。
+  * コンパイル・リンクリストにファイルを追加するために使われます。
 * `LIB_SRC`
   * コンパイル・リンクリストにライブラリとしてファイルを追加するために使われます。  
     `LIB_SRC` で指定されたファイルは、`SRC` で指定されたファイルの後にリンクされます。  
@@ -302,11 +313,11 @@ QMK での全ての利用可能な設定にはデフォルトがあります。
      ...  a.o c.o  ...  lib_b.a lib_d.a  ...
     ```
 * `LAYOUTS`
-   * このキーボードがサポートする[レイアウト](ja/feature_layouts.md)のリスト
+  * このキーボードがサポートする[レイアウト](ja/feature_layouts.md)のリスト
 * `LINK_TIME_OPTIMIZATION_ENABLE`
-   * キーボードをコンパイルする時に、Link Time Optimization (`LTO`) を有効にします。これは処理に時間が掛かりますが、コンパイルされたサイズを大幅に減らします (そして、ファームウェアが小さいため、追加の時間は分からないくらいです)。ただし、`LTO` が有効な場合、古いマクロと関数の機能が壊れるため、自動的にこれらの機能を無効にします。これは `NO_ACTION_MACRO` と `NO_ACTION_FUNCTION` を自動的に定義することで行われます。
+  * キーボードをコンパイルする時に、Link Time Optimization (`LTO`) を有効にします。これは処理に時間が掛かりますが、コンパイルされたサイズを大幅に減らします (そして、ファームウェアが小さいため、追加の時間は分からないくらいです)。ただし、`LTO` が有効な場合、古いマクロと関数の機能が壊れるため、自動的にこれらの機能を無効にします。これは `NO_ACTION_MACRO` と `NO_ACTION_FUNCTION` を自動的に定義することで行われます。
 * `LTO_ENABLE`
-   * LINK_TIME_OPTIMIZATION_ENABLE と同じ意味です。`LINK_TIME_OPTIMIZATION_ENABLE` の代わりに `LTO_ENABLE` を使うことができます。
+  * LINK_TIME_OPTIMIZATION_ENABLE と同じ意味です。`LINK_TIME_OPTIMIZATION_ENABLE` の代わりに `LTO_ENABLE` を使うことができます。
 
 ## AVR MCU オプション
 * `MCU = atmega32u4`
@@ -315,56 +326,56 @@ QMK での全ての利用可能な設定にはデフォルトがあります。
 * `F_USB = $(F_CPU)`
 * `OPT_DEFS += -DINTERRUPT_CONTROL_ENDPOINT`
 * `BOOTLOADER = atmel-dfu` と以下のオプション:
-   * `atmel-dfu`
-   * `lufa-dfu`
-   * `qmk-dfu`
-   * `halfkay`
-   * `caterina`
-   * `bootloadHID`
-   * `USBasp`
+  * `atmel-dfu`
+  * `lufa-dfu`
+  * `qmk-dfu`
+  * `halfkay`
+  * `caterina`
+  * `bootloadHID`
+  * `USBasp`
 
-## 機能オプション
+## 機能オプション :id=feature-options
 
 これらを使って特定の機能のビルドを有効または無効にします。有効にすればするほどファームウェアが大きくなり、MCU には大きすぎるファームウェアを構築するリスクがあります。
 
 * `BOOTMAGIC_ENABLE`
-   * 仮想 DIP スイッチ設定
+  * 仮想 DIP スイッチ設定
 * `MOUSEKEY_ENABLE`
-   * マウスキー
+  * マウスキー
 * `EXTRAKEY_ENABLE`
-   * オーディオ制御とシステム制御
+  * オーディオ制御とシステム制御
 * `CONSOLE_ENABLE`
-   * デバッグ用コンソール
+  * デバッグ用コンソール
 * `COMMAND_ENABLE`
-   * デバッグ及び設定用のコマンド
+  * デバッグ及び設定用のコマンド
 * `COMBO_ENABLE`
-   * キーコンボ機能
+  * キーコンボ機能
 * `NKRO_ENABLE`
-   * USB N-キーロールオーバー - これが動作しない場合は、ここを見てください: https://github.com/tmk/tmk_keyboard/wiki/FAQ#nkro-doesnt-work
+  * USB N-キーロールオーバー - これが動作しない場合は、ここを見てください: https://github.com/tmk/tmk_keyboard/wiki/FAQ#nkro-doesnt-work
 * `AUDIO_ENABLE`
-   * オーディオサブシステムを有効にします。
+  * オーディオサブシステムを有効にします。
 * `RGBLIGHT_ENABLE`
-   * キーボードアンダーライト機能を有効にします
+  * キーボードアンダーライト機能を有効にします
 * `LEADER_ENABLE`
-   * リーダーキーコードを有効にします
+  * リーダーキーコードを有効にします
 * `MIDI_ENABLE`
-   * MIDI 制御
+  * MIDI 制御
 * `UNICODE_ENABLE`
-   * Unicode
+  * Unicode
 * `BLUETOOTH_ENABLE`
-   * Adafruit EZ-Key HID で Bluetooth を有効にするレガシーオプション。BLUETOOTH を見てください
+  * Adafruit EZ-Key HID で Bluetooth を有効にするレガシーオプション。BLUETOOTH を見てください
 * `BLUETOOTH`
-   * 現在のオプションは、AdafruitEzKey、AdafruitBLE、RN42
+  * 現在のオプションは、AdafruitEzKey、AdafruitBLE、RN42
 * `SPLIT_KEYBOARD`
-   * 分割キーボード (let's split や bakingpy のキーボードのようなデュアル MCU) のサポートを有効にし、quantum/split_common にある全ての必要なファイルをインクルードします
+  * 分割キーボード (let's split や bakingpy のキーボードのようなデュアル MCU) のサポートを有効にし、quantum/split_common にある全ての必要なファイルをインクルードします
 * `CUSTOM_MATRIX`
-   * 標準マトリックス走査ルーチンを独自のものに置き換えることができます。
+  * 標準マトリックス走査ルーチンを独自のものに置き換えることができます。
 * `DEBOUNCE_TYPE`
-   * 標準キーデバウンスルーチンを代替または独自のものに置き換えることができます。
+  * 標準キーデバウンスルーチンを代替または独自のものに置き換えることができます。
 * `WAIT_FOR_USB`
-   * キーボードが起動する前に、USB 接続が確立されるのをキーボードに待機させます
+  * キーボードが起動する前に、USB 接続が確立されるのをキーボードに待機させます
 * `NO_USB_STARTUP_CHECK`
-   * キーボードの起動後の usb サスペンドチェックを無効にします。通常、キーボードはタスクが実行される前にホストがウェイク アップするのを待ちます。分割キーボードは半分はウェイクアップコールを取得できませんが、マスタにコマンドを送信する必要があるため、役に立ちます。
+  * キーボードの起動後の usb サスペンドチェックを無効にします。通常、キーボードはタスクが実行される前にホストがウェイク アップするのを待ちます。分割キーボードは半分はウェイクアップコールを取得できませんが、マスタにコマンドを送信する必要があるため、役に立ちます。
 
 ## USB エンドポイントの制限
 

docs/ja/contributing.md

@@ -1,8 +1,8 @@
 # 貢献方法
 
 <!---
-  original document: d47809575:docs/contributing.md
-  git diff d47809575 HEAD -- docs/contributing.md | cat
+  original document: 0.8.62:docs/contributing.md
+  git diff 0.8.62 HEAD -- docs/contributing.md | cat
 -->
 
 👍🎉 まず、これを読み貢献する時間を作ってくれてありがとうございます！🎉👍
@@ -106,7 +106,7 @@ enum my_keycodes {
 };
 ```
 
-### ドキュメントのプレビュー
+### ドキュメントのプレビュー :id=previewing-the-documentation
 
 開発環境をセットアップした場合は、プルリクエストを開く前に以下のコマンドを `qmk_firmware/` フォルダから実行することで、あなたの変更をプレビューすることができます:
 
@@ -122,7 +122,7 @@ enum my_keycodes {
 
 ほとんどの初めての QMK 貢献者は、個人のキーマップから始めます。キーマップの標準はかなりカジュアルなものにしようとしています(キーマップは結局のところ作成者の性格を反映しています)が、他の人があなたのキーマップを簡単に見つけて学ぶことができるように、これらのガイドラインに従うようにお願いします。
 
-* [the template](documentation_templates.md) を使って `readme.md` を書きます。
+* [テンプレート](documentation_templates.md) を使って `readme.md` を書きます。
 * 全てのキーマップの PR は squash されるため、コミットがどのように squash されるかを気にする場合は、自分で行う必要があります。
 * キーマップの PR に機能をまとめないでください。最初に機能をサブミットし、次にキーマップのための2つ目の PR をサブミットします。
 * `Makefile` をキーマップフォルダに含めないでください(もう使われていません)。
@@ -134,7 +134,7 @@ enum my_keycodes {
 
 また以下のガイドラインに従うことをお願いします:
 
-* [the template](ja/documentation_templates.md) を使って `readme.md` を書きます。
+* [テンプレート](ja/documentation_templates.md) を使って `readme.md` を書きます。
 * コミットの数を適切に保ってください。そうでなければあなたの PR を squash します。
 * コア機能を新しいキーボードにまとめないでください。最初に機能をサブミットし、次にキーボード用に別の PR をサブミットしてください。
 * `.c`/`.h` ファイルにすぐ上の親フォルダに従って名前を付けます。例えば、`/keyboards/<kb1>/<kb2>/<kb2>.[ch]`

docs/ja/custom_matrix.md

@@ -0,0 +1,114 @@
+# カスタムマトリックス
+
+<!---
+  grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
+  original document: 0.8.46:docs/custom_matrix.md
+  git diff 0.8.46 HEAD -- docs/custom_matrix.md | cat
+-->
+
+QMKは、デフォルトのマトリックススキャンルーチンを独自のコードで部分的に入れ替えたり全部入れ替えたりしたりするメカニズムを提供します。
+
+この機能を使用する理由は次のとおりです:
+
+* キーボードのスイッチと MCU ピンの間に追加のハードウェアがある場合
+  * I/O マルチプレクサ
+  * ラインデコーダー
+* 一般的ではないキースイッチマトリックス
+  * `COL2ROW` と `ROW2COL` の同時使用
+
+## 前提条件
+
+カスタムマトリックスの実装には、通常、追加のソースファイルのコンパイルが含まれます。
+一貫性を保つために、このソースファイルのファイル名は `matrix.c` とすることをお勧めします。
+
+あなたのキーボードディレクトリに新しいファイルを追加します:
+```text
+keyboards/<keyboard>/matrix.c
+```
+
+そして、新しいファイルのコンパイルを指定するため、以下を `rules.mk` に追加します
+```make
+SRC += matrix.c
+```
+
+## マトリックスコードの部分置き換え
+
+カスタムマトリックスを実装する際、定型コードを書かなくてすむように、さまざまなスキャン関数のデフォルト実装を提供しています。
+
+設定するには、以下を `rules.mk` に追加します：
+```make
+CUSTOM_MATRIX = lite
+```
+
+そして、キーボードディレクトリの `matrix.c` ファイルに次の関数を実装します。
+
+```c
+void matrix_init_custom(void) {
+    // TODO: ここでハードウェアの初期化をする
+}
+
+bool matrix_scan_custom(matrix_row_t current_matrix[]) {
+    bool matrix_has_changed = false;
+
+    // TODO: ここで、マトリックススキャンを行なう
+
+    return matrix_has_changed;
+}
+```
+
+## マトリックスコードの全面置き換え
+
+スキャンルーチンをさらに変更する必要がある場合は、完全なスキャンルーチンを実装することを選択できます。
+
+設定するには、以下を `rules.mk` に追加します：
+```make
+CUSTOM_MATRIX = yes
+```
+
+そして、キーボードディレクトリの `matrix.c` ファイルに次の関数を実装します。
+
+```c
+matrix_row_t matrix_get_row(uint8_t row) {
+    // TODO: 要求された行データを返します
+}
+
+void matrix_print(void) {
+    // TODO: printf() を使って現在のマトリックスの状態をコンソールにダンプします
+}
+
+void matrix_init(void) {
+    // TODO: ここでハードウェアとグローバルマトリックスの状態を初期化します
+
+    // ハードウェアによるデバウンスがない場合 - 設定されているデバウンスルーチンを初期化します
+    debounce_init(MATRIX_ROWS);
+
+    // 正しいキーボード動作のためにこれを呼び出す*必要があります*
+    matrix_init_quantum();
+}
+
+uint8_t matrix_scan(void) {
+    bool matrix_has_changed = false;
+
+    // TODO: ここにマトリックススキャンルーチンを追加します
+
+    // ハードウェアによるデバウンスがない場合 - 設定されているデバウンスルーチンを使用します
+    debounce(raw_matrix, matrix, MATRIX_ROWS, changed);
+
+    // 正しいキーボード動作のためにこれを呼び出す*必要があります*
+    matrix_scan_quantum();
+
+    return matrix_has_changed;
+}
+```
+
+また、次のコールバックのデフォルトも提供します。
+
+```c
+__attribute__((weak)) void matrix_init_kb(void) { matrix_init_user(); }
+
+__attribute__((weak)) void matrix_scan_kb(void) { matrix_scan_user(); }
+
+__attribute__((weak)) void matrix_init_user(void) {}
+
+__attribute__((weak)) void matrix_scan_user(void) {}
+```