diff --git a/README.md b/README.md
index 949f71d..cb688cd 100644
--- a/README.md
+++ b/README.md
@@ -178,7 +178,13 @@ For other syntax elements, see `:h vimwiki-syntax`
 
 ## Key bindings
 
-Normal mode:
+### Normal mode
+
+**Note:** your terminal may prevent capturing some of the default bindings
+listed below. See `:h vimwiki-local-mappings` for suggestions for alternative
+bindings if you encounter a problem.
+
+#### Basic key bindings
 
  * `<Leader>ww` -- Open default wiki index file.
  * `<Leader>wt` -- Open default wiki index file in a new tab.
@@ -192,7 +198,10 @@ Normal mode:
  * `<Tab>` -- Find next wiki link
  * `<Shift-Tab>` -- Find previous wiki link
 
-For more keys, see `:h vimwiki-mappings`
+#### Advanced key bindings
+
+Refer to the complete documentation at `:h vimwiki-mappings` to see many
+more bindings.
 
 ## Commands
 
@@ -218,7 +227,7 @@ let g:vimwiki_list = [{'path': '~/vimwiki/',
 
 ## Getting help
 
-**Have a question?**  
+**Have a question?**
 Visit the IRC channel [`#vimwiki`](https://webchat.freenode.net/?channels=#vimwiki) on Freenode ([webchat](https://webchat.freenode.net/?channels=#vimwiki), also synced to Matrix/Riot: `#freenode_#vimwiki:matrix.org`) or post to the [mailing list](https://groups.google.com/forum/#!forum/vimwiki).
 
 ## Helping VimWiki
diff --git a/doc/vimwiki.txt b/doc/vimwiki.txt
index 2fccb20..c031756 100644
--- a/doc/vimwiki.txt
+++ b/doc/vimwiki.txt
@@ -3311,6 +3311,7 @@ Contributors and their Github usernames in roughly chronological order:
     - Steven Stallion (@sstallion)
     - Rane Brown (@ranebrown)
     - Patrik Willard (@padowi)
+    - Steve Dondley (@sdondley)
 
 
 ==============================================================================
@@ -3326,6 +3327,8 @@ https://github.com/vimwiki-backup/vimwiki/issues.
 2.5 (in progress)~
 
 New:~
+    * PR #683: Improve layout and format of key binding documentation in
+      README and include note about key bindings that may not work.
     * PR #675: Add option |vimwiki-option-name| to assign a per wiki name.
     * PR #661: Add option |g:vimwiki_auto_header| to automatically generate
       a level 1 header for new wiki pages.