From 12f736000c86ddb04a00605eaa319dd4e29b47b1 Mon Sep 17 00:00:00 2001
From: A-Walrus <ofek.r.guy@gmail.com>
Date: Wed, 14 Sep 2022 16:53:03 +0300
Subject: [PATCH] Add back changes from #3827

---
 book/src/generated/static-cmd.md | 38 ++++++++++++++++++++++++++---
 book/src/modes/insert.md         | 42 +++++++++++++++++++++++++++++---
 2 files changed, 72 insertions(+), 8 deletions(-)

diff --git a/book/src/generated/static-cmd.md b/book/src/generated/static-cmd.md
index 7789752e86fe5..6ba369d4424fb 100644
--- a/book/src/generated/static-cmd.md
+++ b/book/src/generated/static-cmd.md
@@ -272,10 +272,12 @@ looking over text and not actively editing it).
 | `n` | Select next search match | `search_next` |
 | `N` | Select previous search match | `search_prev` |
 ## Insert
-We support many readline/emacs style bindings in insert mode for convenience.
-These can be helpful for making simple modifications without escaping to normal
-mode, but beware that you will not have an undo-able "save point" until you
-return to normal mode.
+Insert mode bindings are somewhat minimal by default. Helix is designed to
+be a modal editor, and this is reflected in the user experience and internal
+mechanics. For example, changes to the text are only saved for undos when
+escaping from insert mode to normal mode. For this reason, new users are
+strongly encouraged to learn the modal editing paradigm to get the smoothest
+experience.
 
 | Key | Description | Command |
 | --- | --- | --- |
@@ -291,6 +293,34 @@ return to normal mode.
 | `C-u` | Delete till start of line | `kill_to_line_start` |
 | `C-x` | Invoke completion popup | `completion` |
 | `C-r` | Insert register | `insert_register` |
+
+However, if you really want navigation in insert mode, this is supported. An
+example config that gives the ability to use arrow keys while still in insert
+mode:
+
+```toml
+[keys.insert]
+"up" = "move_line_up"
+"down" = "move_line_down"
+"left" = "move_char_left"
+"right" = "move_char_right"
+"C-b" = "move_char_left"
+"C-f" = "move_char_right"
+"A-b" = "move_prev_word_end"
+"C-left" = "move_prev_word_end"
+"A-f" = "move_next_word_start"
+"C-right" = "move_next_word_start"
+"A-<" = "goto_file_start"
+"A->" = "goto_file_end"
+"pageup" = "page_up"
+"pagedown" = "page_down"
+"home" = "goto_line_start"
+"C-a" = "goto_line_start"
+"end" = "goto_line_end_newline"
+"C-e" = "goto_line_end_newline"
+"A-left" = "goto_line_start"
+```
+
 ## Select
 This mode echoes Normal mode, but changes any movements to extend
 selections rather than replace them. Goto motions are also changed to
diff --git a/book/src/modes/insert.md b/book/src/modes/insert.md
index 31e773aeed403..230ba8a14f54b 100644
--- a/book/src/modes/insert.md
+++ b/book/src/modes/insert.md
@@ -1,4 +1,38 @@
-We support many readline/emacs style bindings in insert mode for convenience.
-These can be helpful for making simple modifications without escaping to normal
-mode, but beware that you will not have an undo-able "save point" until you
-return to normal mode.
\ No newline at end of file
+Insert mode bindings are somewhat minimal by default. Helix is designed to
+be a modal editor, and this is reflected in the user experience and internal
+mechanics. For example, changes to the text are only saved for undos when
+escaping from insert mode to normal mode. For this reason, new users are
+strongly encouraged to learn the modal editing paradigm to get the smoothest
+experience.
+
+
+
+
+
+
+However, if you really want navigation in insert mode, this is supported. An
+example config that gives the ability to use arrow keys while still in insert
+mode:
+
+```toml
+[keys.insert]
+"up" = "move_line_up"
+"down" = "move_line_down"
+"left" = "move_char_left"
+"right" = "move_char_right"
+"C-b" = "move_char_left"
+"C-f" = "move_char_right"
+"A-b" = "move_prev_word_end"
+"C-left" = "move_prev_word_end"
+"A-f" = "move_next_word_start"
+"C-right" = "move_next_word_start"
+"A-<" = "goto_file_start"
+"A->" = "goto_file_end"
+"pageup" = "page_up"
+"pagedown" = "page_down"
+"home" = "goto_line_start"
+"C-a" = "goto_line_start"
+"end" = "goto_line_end_newline"
+"C-e" = "goto_line_end_newline"
+"A-left" = "goto_line_start"
+```