--- a/README.markdown	Sat Feb 21 23:21:59 2015 -0800
+++ b/README.markdown	Sun Feb 22 14:14:55 2015 -0800
@@ -9,7 +9,7 @@
 Linux is the ideal build environment (preferably recent'ish). In the near
 future I'll make available an Arch Linux VM for building/manufacturing tests.
 
-Building on Mac should be ok for 99% of users with Macports or Homebrew. For 
+Building on Mac should be ok for 99% of users with Macports or Homebrew. For
 Homebrew, use `brew tap PX4/homebrew-px4` to get the arm-none-eabi-gcc installer.
 The dfu Bootloader will not build correctly with the old version of
 arm-none-eabi-gcc that Macports currently has (4.7.3). This is due to a bug
@@ -263,6 +263,112 @@
 easier to just edit the file. e.g. `cmake -DScanModuleOverride=<module name>`.
 
 
+Keymap Configuration
+--------------------
+
+This is where you define the layout for your keyboard.
+Currently, the only way to define kebyoard layouts is using [KLL](https://www.overleaf.com/read/zzqbdwqjfwwf).
+
+KLL is built up of 3 different kinds of keymaps in total.
+The BaseMap, DefaultMap and PartialMaps.
+
+For each type of keymap, it is possible to combine multiple .kll files together to create new ones using
+the compiler. The order of the files matter, as the right-most file will overwrite any setting in the
+previous files.
+
+> NOTE: Each keymap is done after the entire file is processed. This means that within the file the order
+>       of assignment doesa *not* matter (if you assign the same thing twice, then yes the most recent one
+>       takes priority).
+
+
+BaseMap defines what the keyboard can do. This includes specific capabilities of the keyboard (such as USB),
+the mapping of Scan Codes to USB Codes and any specific configurations for the keyboard.
+In general, the BaseMap rarely needs to be changed. Usually only when adding a new keyboard to the firmware
+does the Basemap need any modification.
+The BaseMap is what both DefaultMap and PartialMaps are based upon. This allows for a common reference
+when defining custom keymappings.
+
+> NOTE: Don't use defaultMap.kll to change your layouts. This will work, but they will not be portable.
+
+
+The DefaultMap is the normal state of the keyboard, i.e. your default layer.
+Using the BaseMap as a base, the DefaultMap is a modification of the BaseMap to what the keyboard should do.
+Since the DefaultMap uses USB Code to USB Code translations, this means that keymaps used for one keyboard
+will work with another keyboard.
+For example, I use Colemak, so this means I only have to define Colemak once for every keyboard that supports
+the kiibohd firmware. This is possible because every BaseMap defines the keyboard as a US ANSI like keyboard
+layout.
+The DefaultMap can also be thought of as Layer 0.
+
+
+PartialMaps are optional keymaps that can be "stacked" on top of the DefaultMap.
+They can be dynamically swapped out using the layer control capabilities:
+
+- layerLatch( `<layer number>` )
+- layerLock( `<layer number>` )
+- layerShift( `<layer number>` )
+
+layerShift is usually what you want as it works just like a standard shift key.
+layerLock is similar to the CapsLock key. While layerLatch is a latch, where only the next key you press
+will use that layer (e.g. stickykeys).
+
+A unique aspect of KLL layers is that it's a true stack of layers.
+When a layer is activated, only the keys that are specified by the layer will change.
+This means, if you define a layer that only sets `CapsLock -> LCtrl` and `LCtrl->Capslock` only those keys
+will change when you active the layer. All the other keys will use the layer that is "underneath" to
+lookup the keypress (usually the DefaultMap).
+
+This means that you can combine .kll files statically using the compiler or dynamically using the firmware.
+
+You can set the max number of layers by changing the `stateWordSize` define in one of your kll files.
+By default it is set to 8 in Macro/PartialMap/capabilities.kll. This means you can have up to 256 layers
+total (this includes the DefaultMap).
+You can increase this number to either 16 or 32 (this will use more Flash and RAM btw) which will give you
+2^16 and 2^32 possible layers respectively (65 535 and 4 294 967 295).
+
+
+```cmake
+###
+# Keymap Configuration (do not include the .kll extension)
+#
+
+#| Do not include the .kll extension
+#| * BaseMap maps the native keyboard scan codes to USB Codes so the layout is compatible with all other layouts
+#| * DefaultMap allows the default keymap to be modified from the BaseMap
+#| * PartialMaps is a set of dynamically set layers (there is no limit, but too many may use up too much RAM...)
+#| BaseMap generally does not need to be changed from "defaultMap"
+#|
+#| Syntax:
+#|  myMap
+#|    * defines a single .kll layout file, double-quotes are needed to distinguish between layers
+#|  "myMap specialLayer"
+#|    * defines myMap to be the main layout, then replace specialLayers on top of it
+#|
+#| - Only for PartialMaps -
+#|  "myMap specialLayer" "myMap colemak" dvorak
+#|    * As before, but also generates a second layer at index 2 and third at index 3
+#|
+#| NOTE:  Remember to add key(s) to enable each Partial Layer
+#| NOTE2: Layers are always based up the BaseMap (which should be an ANSI-like mapping)
+#| NOTE3: Compiler looks in kll/layouts and the build directory for layout files (precedence on build directory)
+
+##| Set the base keyboard .kll map, defaults to "defaultMap" if not found
+##| Looks in Scan/<Module Name> for the available BaseMaps
+set(     BaseMap "defaultMap"
+        CACHE STRING "KLL BaseMap/Scancode Keymapping" )
+
+##| Layer additonal .kll maps on the BaseMap, layers are in order from 1st to nth
+##| Can be set to ""
+set(  DefaultMap "md1Overlay stdFuncMap"
+        CACHE STRING "KLL DefaultMap" )
+
+##| ParitalMaps available on top of the BaseMap. See above for syntax on specifying multiple layers vs. layering
+##| Can be set to ""
+set( PartialMaps "hhkbpro2"
+        CACHE STRING "KLL PartialMaps/Layer Definitions" )
+```
+
+
 Linux Building
 --------------