From be81abfe48e59d9d6ff6b7acda6afbd351c4cbc7 Mon Sep 17 00:00:00 2001
From: Barrett Ruth <br.barrettruth@gmail.com>
Date: Wed, 25 Feb 2026 13:24:28 -0500
Subject: [PATCH] docs: update mappings and config for keymaps and new Plug
 entries

Problem: Vimdoc still listed g? help popup, lacked documentation for
the four new <Plug> mappings, and had no keymaps config section.

Solution: Remove g? from mappings table, document all nine <Plug>
mappings, add keymaps table to the config example and field reference,
and note that buffer-local keys are configurable.
---
 doc/pending.txt | 56 ++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 46 insertions(+), 10 deletions(-)

diff --git a/doc/pending.txt b/doc/pending.txt
index e9515d9..66882b9 100644
--- a/doc/pending.txt
+++ b/doc/pending.txt
@@ -250,27 +250,34 @@ MAPPINGS                                                    *pending-mappings*
 The following keys are set buffer-locally when the task buffer opens. They
 are active only in the `pending://` buffer.
 
-Buffer-local keys: ~
+Buffer-local keys are configured via the `keymaps` table in |pending-config|.
+The defaults are shown below. Set any key to `false` to disable it.
+
+Default buffer-local keys: ~
 
     Key         Action ~
     -------     ------------------------------------------------
-    `<CR>`        Toggle complete / uncomplete the task at cursor
-    `!`           Toggle the priority flag on the task at cursor
-    `D`           Prompt for a due date on the task at cursor
-    `<Tab>`       Switch between category view and priority view
-    `U`           Undo the last `:w` save
-    `g?`          Show a help popup with available keys
+    `q`           Close the task buffer (`close`)
+    `<CR>`        Toggle complete / uncomplete (`toggle`)
+    `!`           Toggle the priority flag (`priority`)
+    `D`           Prompt for a due date (`date`)
+    `<Tab>`       Switch between category / priority view (`view`)
+    `U`           Undo the last `:w` save (`undo`)
+    `o`           Insert a new task line below (`open_line`)
+    `O`           Insert a new task line above (`open_line_above`)
     `zc`          Fold the current category section (category view only)
     `zo`          Unfold the current category section (category view only)
 
-`o` and `O` are overridden to insert a correctly-formatted blank task line
-at the position below or above the cursor rather than using standard Vim
-indentation. `dd`, `p`, `P`, and `:w` work as expected.
+`dd`, `p`, `P`, and `:w` work as standard Vim operations.
 
                                                         *<Plug>(pending-open)*
 <Plug>(pending-open)
     Open the task buffer. Maps to |:Pending| with no arguments.
 
+                                                       *<Plug>(pending-close)*
+<Plug>(pending-close)
+    Close the task buffer window.
+
                                                       *<Plug>(pending-toggle)*
 <Plug>(pending-toggle)
     Toggle complete / uncomplete for the task under the cursor.
@@ -287,6 +294,18 @@ indentation. `dd`, `p`, `P`, and `:w` work as expected.
 <Plug>(pending-view)
     Switch between category view and priority view.
 
+                                                        *<Plug>(pending-undo)*
+<Plug>(pending-undo)
+    Undo the last `:w` save.
+
+                                                   *<Plug>(pending-open-line)*
+<Plug>(pending-open-line)
+    Insert a correctly-formatted blank task line below the cursor.
+
+                                             *<Plug>(pending-open-line-above)*
+<Plug>(pending-open-line-above)
+    Insert a correctly-formatted blank task line above the cursor.
+
 Example configuration: >lua
     vim.keymap.set('n', '<leader>t', '<Plug>(pending-open)')
     vim.keymap.set('n', '<leader>T', '<Plug>(pending-toggle)')
@@ -326,6 +345,16 @@ loads: >lua
       recur_syntax = 'rec',
       someday_date = '9999-12-30',
       category_order = {},
+      keymaps = {
+        close = 'q',
+        toggle = '<CR>',
+        view = '<Tab>',
+        priority = '!',
+        date = 'D',
+        undo = 'U',
+        open_line = 'o',
+        open_line_above = 'O',
+      },
       gcal = {
         calendar = 'Tasks',
         credentials_path = '/path/to/client_secret.json',
@@ -376,6 +405,13 @@ Fields: ~
                          given order. Categories not in the list are appended
                          after the ordered ones in their natural order.
 
+    {keymaps}            (table, default: see below)       *pending.Keymaps*
+                         Buffer-local key bindings. Each field maps an action
+                         name to a key string. Set a field to `false` to
+                         disable that binding. Unset fields use the default.
+                         See |pending-mappings| for the full list of actions
+                         and their default keys.
+
     {gcal}               (table, default: nil)
                          Google Calendar sync configuration. See
                          |pending.GcalConfig|. Omit this field entirely to