diff --git a/alacritty.yml b/alacritty.yml
index b57de3d6..adfad388 100644
--- a/alacritty.yml
+++ b/alacritty.yml
@@ -10,6 +10,7 @@
   # each instance of Alacritty. If it is not present, alacritty will
   # check the local terminfo database and use 'alacritty' if it is
   # available, otherwise 'xterm-256color' is used.
+  #
   #TERM: xterm-256color
 
 window:
@@ -88,19 +89,19 @@ font:
   normal:
     family: monospace
     # The `style` can be specified to pick a specific face.
-    #style: Regular
+    # style: Regular
 
   # Bold font face
   bold:
     family: monospace
     # The `style` can be specified to pick a specific face.
-    #style: Bold
+    # style: Bold
 
   # Italic font face
   italic:
     family: monospace
     # The `style` can be specified to pick a specific face.
-    #style: Italic
+    # style: Italic
 
   # Point size
   size: 11.0
@@ -147,6 +148,7 @@ colors:
     # The dimmed foreground color is calculated automatically if it is not present.
     # If the bright foreground color is not set, or `draw_bold_text_with_bright_colors`
     # is `false`, the normal foreground color will be used.
+    #
     #dim_foreground: '0x9a9a9a'
     #bright_foreground: '0xffffff'
 
@@ -197,6 +199,7 @@ colors:
   #
   # The indexed colors include all colors from 16 to 256.
   # When these are not set, they're filled with sensible defaults.
+  #
   #indexed_colors:
   #  - { index: 16, color: '0x000000' }
 
@@ -302,6 +305,7 @@ live_config_reload: true
 #
 # You can set `shell.program` to the path of your favorite shell, e.g. `/bin/fish`.
 # Entries in `shell.args` are passed unmodified as arguments to the shell.
+#
 #shell:
 #  program: /bin/bash
 #  args:
diff --git a/alacritty_macos.yml b/alacritty_macos.yml
index 8f52853d..9d1fa378 100644
--- a/alacritty_macos.yml
+++ b/alacritty_macos.yml
@@ -10,6 +10,7 @@
   # each instance of Alacritty. If it is not present, alacritty will
   # check the local terminfo database and use 'alacritty' if it is
   # available, otherwise 'xterm-256color' is used.
+  #
   #TERM: xterm-256color
 
 window:
@@ -83,19 +84,19 @@ font:
   normal:
     family: Menlo
     # The `style` can be specified to pick a specific face.
-    #style: Regular
+    # style: Regular
 
   # Italic font face
   bold:
     family: Menlo
     # The `style` can be specified to pick a specific face.
-    #style: Bold
+    # style: Bold
 
   # Italic font face
   italic:
     family: Menlo
     # The `style` can be specified to pick a specific face.
-    #style: Italic
+    # style: Italic
 
   # Point size
   size: 12.0
@@ -146,6 +147,7 @@ colors:
     # The dimmed foreground color is calculated automatically if it is not present.
     # If the bright foreground color is not set, or `draw_bold_text_with_bright_colors`
     # is `false`, the normal foreground color will be used.
+    #
     #dim_foreground: '0x9a9a9a'
     #bright_foreground: '0xffffff'
 
@@ -196,6 +198,7 @@ colors:
   #
   # The indexed colors include all colors from 16 to 256.
   # When these are not set, they're filled with sensible defaults.
+  #
   #indexed_colors:
   #  - { index: 16, color: '0x000000' }
 
@@ -299,6 +302,7 @@ live_config_reload: true
 #
 # You can set `shell.program` to the path of your favorite shell, e.g. `/bin/fish`.
 # Entries in `shell.args` are passed unmodified as arguments to the shell.
+#
 #shell:
 #  program: /bin/bash
 #  args:
diff --git a/alacritty_windows.yml b/alacritty_windows.yml
index 0b904f4c..23c817cd 100644
--- a/alacritty_windows.yml
+++ b/alacritty_windows.yml
@@ -1,30 +1,29 @@
-# Configuration for Alacritty, the GPU enhanced terminal emulator.
+# Configuration for Alacritty, the GPU enhanced terminal emulator
+
 
 # Any items in the `env` entry below will be added as
 # environment variables. Some entries may override variables
-# set by alacritty itself.
-#env:
-  # TERM variable
+# set by alacritty it self.
+env:
+  # TERM env customization.
   #
-  # This value is used to set the `$TERM` environment variable for
-  # each instance of Alacritty. If it is not present, alacritty will
-  # check the local terminfo database and use 'alacritty' if it is
-  # available, otherwise 'xterm-256color' is used.
-  #TERM: xterm-256color
+  # If this property is not set, alacritty will set it to xterm-256color.
+  #
+  # Note that some xterm terminfo databases don't declare support for italics.
+  # You can verify this by checking for the presence of `smso` and `sitm` in
+  # `infocmp xterm-256color`.
+  TERM: xterm-256color
 
 window:
-  # Window dimensions (changes require restart)
-  #
-  # Specified in number of columns/lines, not pixels.
-  # If both are `0`, this setting is ignored.
+  # Window dimensions in character columns and lines
+  # (changes require restart)
   dimensions:
     columns: 80
     lines: 24
 
-  # Window padding (changes require restart)
-  #
-  # Blank space added around the window in pixels. This padding is not scaled
-  # by DPI and the specified value is always added at both opposing sides.
+  # Adds this many blank pixels of padding around the window
+  # Units are physical pixels; this is not DPI aware.
+  # (change requires restart)
   padding:
     x: 2
     y: 2
@@ -37,77 +36,98 @@ window:
   decorations: full
 
 scrolling:
-  # Maximum number of lines in the scrollback buffer.
-  # Specifying '0' will disable scrolling.
+  # How many lines of scrollback to keep,
+  # '0' will disable scrolling.
   history: 10000
 
-  # Number of lines the viewport will move for every line scrolled when
-  # scrollback is enabled (history > 0).
+  # Number of lines the viewport will move for every line
+  # scrolled when scrollback is enabled (history > 0).
   multiplier: 3
 
   # Faux Scrolling
   #
-  # The `faux_multiplier` setting controls the number of lines the terminal
-  # should scroll when the alternate screen buffer is active. This is used
-  # to allow mouse scrolling for applications like `man`.
+  # The `faux_multiplier` setting controls the number
+  # of lines the terminal should scroll when the alternate
+  # screen buffer is active. This is used to allow mouse
+  # scrolling for applications like `man`.
   #
-  # Specifying `0` will disable faux scrolling.
+  # To disable this completely, set `faux_multiplier` to 0.
   faux_multiplier: 3
 
-  # Scroll to the bottom when new text is written to the terminal.
+  # Automatically scroll to the bottom when new text is written
+  # to the terminal.
   auto_scroll: false
 
-# Spaces per Tab (changes require restart)
-#
-# This setting defines the width of a tab in cells.
-#
-# Some applications, like Emacs, rely on knowing about the width of a tab.
-# To prevent unexpected behavior in these applications, it's also required to
-# change the `it` value in terminfo when altering this setting.
+# Display tabs using this many cells (changes require restart)
 tabspaces: 8
 
+# When true, bold text is drawn using the bright variant of colors.
+draw_bold_text_with_bright_colors: true
+
 # Font configuration (changes require restart)
+#
+# Important font attributes like antialiasing, subpixel aa, and hinting can be
+# controlled through fontconfig. Specifically, the following attributes should
+# have an effect:
+#
+# * hintstyle
+# * antialias
+# * lcdfilter
+# * rgba
+#
+# For instance, if you wish to disable subpixel antialiasing, you might set the
+# rgba property to "none". If you wish to completely disable antialiasing, you
+# can set antialias to false.
+#
+# Please see these resources for more information on how to use fontconfig
+#
+# * https://wiki.archlinux.org/index.php/font_configuration#Fontconfig_configuration
+# * file:///usr/share/doc/fontconfig/fontconfig-user.html
 font:
-  # Normal (roman) font face
+  # The normal (roman) font face to use.
   normal:
     family: Consolas
-    # The `style` can be specified to pick a specific face.
-    #style: Regular
+    # Style can be specified to pick a specific face.
+    # style: Regular
 
-  # Bold font face
+  # The bold font face
   bold:
     family: Consolas
-    # The `style` can be specified to pick a specific face.
-    #style: Bold
+    # Style can be specified to pick a specific face.
+    # style: Bold
 
-  # Italic font face
+  # The italic font face
   italic:
     family: Consolas
-    # The `style` can be specified to pick a specific face.
-    #style: Italic
+    # Style can be specified to pick a specific face.
+    # style: Italic
 
-  # Point size
+  # Point size of the font
   size: 11.0
 
-  # Offset is the extra space around each character. `offset.y` can be thought of
-  # as modifying the line spacing, and `offset.x` as modifying the letter spacing.
+  # Offset is the extra space around each character. offset.y can be thought of
+  # as modifying the linespacing, and offset.x as modifying the letter spacing.
   offset:
     x: 0
     y: 0
 
   # Glyph offset determines the locations of the glyphs within their cells with
-  # the default being at the bottom. Increasing `x` moves the glyph to the right,
-  # increasing `y` moves the glyph upwards.
+  # the default being at the bottom. Increase the x offset to move the glyph to
+  # the right, increase the y offset to move the glyph upward.
   glyph_offset:
     x: 0
     y: 0
 
-# Display the time it takes to redraw each frame.
+  # OS X only: use thin stroke font rendering. Thin strokes are suitable
+  # for retina displays, but for non-retina you probably want this set to
+  # false.
+  use_thin_strokes: false
+
+# Should display the render timer
 render_timer: false
 
-# Use custom cursor colors. If `true`, the `colors.cursor.foreground` and
-# `colors.cursor.background` colors will be used to display the cursor.
-# Otherwise the cell colors are inverted for the cursor.
+# Use custom cursor colors. If true, display the cursor in the cursor.foreground
+# and cursor.background colors, otherwise invert the colors of the cursor.
 custom_cursor_colors: false
 
 # Colors (Tomorrow Night Bright)
@@ -117,17 +137,16 @@ colors:
     background: '0x000000'
     foreground: '0xeaeaea'
 
-    # Bright and dim foreground colors
+    # (Optional) Bright and Dim foreground colors
     #
     # The dimmed foreground color is calculated automatically if it is not present.
     # If the bright foreground color is not set, or `draw_bold_text_with_bright_colors`
     # is `false`, the normal foreground color will be used.
-    #dim_foreground: '0x9a9a9a'
-    #bright_foreground: '0xffffff'
+    #
+    # dim_foreground: '0x9a9a9a'
+    # bright_foreground: '0xffffff'
 
-  # Cursor colors
-  #
-  # These will only be used when the `custom_cursor_colors` field is set to `true`.
+  # Colors the cursor will use if `custom_cursor_colors` is true
   cursor:
     text: '0x000000'
     cursor: '0xffffff'
@@ -154,10 +173,7 @@ colors:
     cyan:    '0x54ced6'
     white:   '0xffffff'
 
-  # Dim colors
-  #
-  # If the dim colors are not set, they will be calculated automatically based
-  # on the `normal` colors.
+  # Dim colors (Optional)
   dim:
     black:   '0x333333'
     red:     '0xf2777a'
@@ -168,13 +184,6 @@ colors:
     cyan:    '0x66cccc'
     white:   '0xdddddd'
 
-  # Indexed Colors
-  #
-  # The indexed colors include all colors from 16 to 256.
-  # When these are not set, they're filled with sensible defaults.
-  #indexed_colors:
-  #  - { index: 16, color: '0x000000' }
-
 # Visual Bell
 #
 # Any time the BEL code is received, Alacritty "rings" the visual bell. Once
@@ -183,44 +192,42 @@ colors:
 # setting the `duration` property (represented in milliseconds). You can also
 # configure the transition function by setting the `animation` property.
 #
-# Values for `animation`:
-#   - Ease
-#   - EaseOut
-#   - EaseOutSine
-#   - EaseOutQuad
-#   - EaseOutCubic
-#   - EaseOutQuart
-#   - EaseOutQuint
-#   - EaseOutExpo
-#   - EaseOutCirc
-#   - Linear
+# Possible values for `animation`
+# `Ease`
+# `EaseOut`
+# `EaseOutSine`
+# `EaseOutQuad`
+# `EaseOutCubic`
+# `EaseOutQuart`
+# `EaseOutQuint`
+# `EaseOutExpo`
+# `EaseOutCirc`
+# `Linear`
+#
+# To completely disable the visual bell, set its duration to 0.
 #
-# Specifying a `duration` of `0` will disable the visual bell.
 visual_bell:
   animation: EaseOutExpo
   duration: 0
 
 # Background opacity
-#
-# Window opacity as a floating point number from `0.0` to `1.0`.
-# The value `0.0` is completely transparent and `1.0` is opaque.
 background_opacity: 1.0
 
 # Mouse bindings
 #
-# Available fields:
-#   - mouse
-#   - action
-#   - mods (optional)
+# Currently doesn't support modifiers. Both the `mouse` and `action` fields must
+# be specified.
 #
 # Values for `mouse`:
-#   - Middle
-#   - Left
-#   - Right
-#   - Numeric identifier such as `5`
+# - Middle
+# - Left
+# - Right
+# - Numeric identifier such as `5`
 #
-# All available `mods` and `action` values are documented in the key binding
-# section.
+# Values for `action`:
+# - Paste
+# - PasteSelection
+# - Copy (TODO)
 mouse_bindings:
   - { mouse: Middle, action: PasteSelection }
 
@@ -259,8 +266,7 @@ hide_cursor_when_typing: false
 #   - Beam
 cursor_style: Block
 
-# If this is `true`, the cursor will be rendered as a hollow box when the
-# window is not focused.
+# Whether the cursor should be a hollow block on window focus loss
 unfocused_hollow_cursor: true
 
 # Live config reload (changes require restart)
@@ -268,90 +274,50 @@ live_config_reload: true
 
 # Shell
 #
-# You can set `shell.program` to the path of your favorite shell, e.g. `/bin/fish`.
-# Entries in `shell.args` are passed unmodified as arguments to the shell.
-#shell:
-  program: cmd
-  #args:
-  #  - --login
+# You can set shell.program to the path of your favorite shell, e.g. /bin/fish.
+# Entries in shell.args are passed unmodified as arguments to the shell.
+shell:
+   program: cmd
+  #  args:
+  #    - --login
+
 
 # Key bindings
 #
-# Key bindings are specified as a list of objects. Each binding will specify
-# a key and modifiers required to trigger it, terminal modes where the binding
-# is applicable, and what should be done when the key binding fires. It can
-# either send a byte sequnce to the running application (`chars`), execute
-# a predefined action (`action`) or fork and execute a specified command plus
-# arguments (`command`).
+# Each binding is defined as an object with some properties. Most of the
+# properties are optional. All of the alphabetical keys should have a letter for
+# the `key` value such as `V`. Function keys are probably what you would expect
+# as well (F1, F2, ..). The number keys above the main keyboard are encoded as
+# `Key1`, `Key2`, etc. Keys on the number pad are encoded `Number1`, `Number2`,
+# etc.  These all match the glutin::VirtualKeyCode variants.
 #
-# Example:
-#   `- { key: V, mods: Command, action: Paste }`
+# Possible values for `mods`
+# `Command`, `Super` refer to the super/command/windows key
+# `Control` for the control key
+# `Shift` for the Shift key
+# `Alt` and `Option` refer to alt/option
 #
-# Available fields:
-#   - key
-#   - mods (optional)
-#   - chars | action | command (exactly one required)
-#   - mode (optional)
+# mods may be combined with a `|`. For example, requiring control and shift
+# looks like:
 #
-# Values for `key`:
-#   - `A` -> `Z`
-#   - `F1` -> `F12`
-#   - `Key1` -> `Key0`
+# mods: Control|Shift
 #
-#   A full list with available key codes can be found here:
-#   https://docs.rs/glutin/*/glutin/enum.VirtualKeyCode.html#variants
+# The parser is currently quite sensitive to whitespace and capitalization -
+# capitalization must match exactly, and piped items must not have whitespace
+# around them.
 #
-#   Instead of using the name of the keys, the `key` field also supports using
-#   the scancode of the desired key. Scancodes have to be specified as a
-#   decimal number.
-#   This command will allow you to display the hex scancodes for certain keys:
-#     `showkey --scancodes`
+# Either an `action`, `chars`, or `command` field must be present.
+#   `action` must be one of `Paste`, `PasteSelection`, `Copy`, or `Quit`.
+#   `chars` writes the specified string every time that binding is activated.
+#     These should generally be escape sequences, but they can be configured to
+#     send arbitrary strings of bytes.
+#   `command` must be a map containing a `program` string, and `args` array of
+#     strings. For example:
+#     - { ... , command: { program: "alacritty", args: ["-e", "vttest"] } }
 #
-# Values for `mods`:
-#   - Command
-#   - Control
-#   - Shift
-#   - Alt
-#
-#   Multiple `mods` can be combined using `|` like this: `mods: Control|Shift`.
-#   Whitespace and capitalization is relevant and must match the example.
-#
-# Values for `chars`:
-#   The `chars` field writes the specified string to the terminal. This makes
-#   it possible to pass escape sequences.
-#   To find escape codes for bindings like `PageUp` ("\x1b[5~"), you can run
-#   the command `showkey -a` outside of tmux.
-#   Note that applications use terminfo to map escape sequences back to
-#   keys. It is therefore required to update the terminfo when
-#   changing an escape sequence.
-#
-# Values for `action`:
-#   - Paste
-#   - PasteSelection
-#   - Copy
-#   - IncreaseFontSize
-#   - DecreaseFontSize
-#   - ResetFontSize
-#   - ScrollPageUp
-#   - ScrollPageDown
-#   - ScrollToTop
-#   - ScrollToBottom
-#   - ClearHistory
-#   - Hide
-#   - Quit
-#
-# Values for `command`:
-#   The `command` field must be a map containing a `program` string and
-#   an `args` array of command line parameter strings.
-#
-#   Example:
-#       `command: { program: "alacritty", args: ["-e", "vttest"] }`
-#
-# Values for `mode`:
-#   - ~AppCursor
-#   - AppCursor
-#   - ~AppKeypad
-#   - AppKeypad
+# Want to add a binding (e.g. "PageUp") but are unsure what the X sequence
+# (e.g. "\x1b[5~") is? Open another terminal (like xterm) without tmux,
+# then run `showkey -a` to get the sequence associated to a key combination.
 key_bindings:
   - { key: V,        mods: Control|Shift,    action: Paste               }
   - { key: C,        mods: Control|Shift,    action: Copy                }