From 7a2d325fa66a932034c29f36444caddeae6b610e Mon Sep 17 00:00:00 2001
From: Caleb Larsen <caleb.john.larsen@gmail.com>
Date: Fri, 27 Jun 2025 15:06:07 -0500
Subject: [PATCH] docs: Add jumplist documentation to the book

My spin on adding documentation for the jumplist to the book. Would love
to have other eyes on this and suggest ways to improve it.

Closes: #13594
---
 book/src/SUMMARY.md  |  1 +
 book/src/jumplist.md | 36 ++++++++++++++++++++++++++++++++++++
 2 files changed, 37 insertions(+)
 create mode 100644 book/src/jumplist.md

diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
index 82715b7ef..aa0560d78 100644
--- a/book/src/SUMMARY.md
+++ b/book/src/SUMMARY.md
@@ -11,6 +11,7 @@
   - [Textobjects](./textobjects.md)
   - [Syntax aware motions](./syntax-aware-motions.md)
   - [Pickers](./pickers.md)
+  - [Jumplist](./jumplist.md)
   - [Keymap](./keymap.md)
   - [Command line](./command-line.md)
   - [Commands](./commands.md)
diff --git a/book/src/jumplist.md b/book/src/jumplist.md
new file mode 100644
index 000000000..97b4b5713
--- /dev/null
+++ b/book/src/jumplist.md
@@ -0,0 +1,36 @@
+## Using the jumplist
+
+To help with quick navigation, Helix maintains a list of "jumps" called the jumplist.
+Whenever you make a significant movement (see next section), Helix stores your selections from before the move as a jump.
+A jump serves as a kind of checkpoint, allowing you to jump to a separate location, make edits, and return to where you were with your previous selections.
+This way, the jumplist tracks both your previous location and your selections.
+You can manually save a jump by using `Ctrl-s`.
+To jump backward in the jumplist, use `Ctrl-o`; to go forward, use `Ctrl-i`. To view and select from the full jumplist, use `Space-j` to open the jumplist picker.
+
+### What makes a jump
+The following is a non-exhaustive list of which actions add a jump to the jumplist:
+- Switching buffers
+  - Using the buffer picker, going to the next/previous buffer
+  - Going to the last accessed/modified file
+  - Making a new file (`:new FILE`)
+  - Opening a file (`:open FILE`)
+    - Includes `:log-open`, `:config-open`, `:config-open-workspace`, `:tutor`
+  - Navigating by pickers, global search, or the file explorer
+  - `goto_file` (`gf`)
+- Big in-file movements
+  - `select_regex` (`s`)
+  - `split_regex` (`S`)
+  - `search` (`/`)
+  - `keep_selections` and `remove_selections` (`K` and `<A-K>`)
+  - `goto_file_start` (`gg`)
+  - `goto_file_end`
+  - `goto_last_line` (`ge`)
+  - `:goto 123` / `:123` / `123G`
+  - `goto_definition` (`gd`)
+  - `goto_declaration` (`gD`)
+  - `goto_type_definition` (`gy`)
+  - `goto_reference` (`gr`)
+- Other
+  - `Ctrl-s` manually creates a jump
+  - Trying to close a modified buffer can switch you to that buffer and create a jump
+  - The debugger can create jumps as you jump stack frames