From fda8c1208cf100d1e6ca49bef1cc4bd826714b48 Mon Sep 17 00:00:00 2001
From: Barrett Ruth <62671086+barrettruth@users.noreply.github.com>
Date: Sun, 8 Mar 2026 19:16:49 -0400
Subject: [PATCH] docs: add `queue_sort` and `category_sort` config fields
 (#100) (#105)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Problem: The queue view sort order (priority → due → order) is hardcoded
with no documentation of a configurable alternative.

Solution: Document `queue_sort` and `category_sort` config fields with
named presets, sort key syntax, `-` direction prefix, and the `status`
key opt-in for disabling the pending/done split. Update the views
section to reference the new `pending-sort` tag.
---
 doc/pending.txt | 55 ++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 52 insertions(+), 3 deletions(-)

diff --git a/doc/pending.txt b/doc/pending.txt
index edb9022..d062375 100644
--- a/doc/pending.txt
+++ b/doc/pending.txt
@@ -414,13 +414,16 @@ Category view (default): ~                             *pending-view-category*
     order tasks were added unless `category_order` is set (see
     |pending-config|). Blank lines separate categories. Within each category,
     tasks are sorted by status (wip → pending → blocked → done), then by
-    priority, then by insertion order. Category sections are foldable with
-    `zc` and `zo`.
+    priority, then by insertion order. The within-category sort order is
+    configurable via `category.sort` (see |pending-sort|). Category sections
+    are foldable with `zc` and `zo`.
 
 Queue view: ~                                             *pending-view-queue*
     A flat list of all tasks sorted by status (wip → pending → blocked →
     done), then by priority, then by due date (tasks without a due date sort
-    last), then by internal order. Category names are shown as right-aligned virtual
+    last), then by internal order. The sort order is configurable via
+    `queue.sort` (see |pending-sort|). Category names are shown as
+    right-aligned virtual
     text alongside the due date virtual text so tasks remain identifiable
     across categories. The buffer is named `pending://queue`.
 
@@ -729,6 +732,11 @@ Fields: ~
                                       in this list appear in the given order;
                                       others are appended after.
 
+                           {sort}     (string|string[], default: 'default')
+                                      Sort order within each category. See
+                                      |pending-sort| for syntax. The `'default'`
+                                      preset is priority → order → id.
+
                            {folding}  (boolean|table, default: true)
                                       *pending.FoldingConfig*
                                       Controls category-level folds. `true`
@@ -743,6 +751,43 @@ Fields: ~
                          {queue}     (table)            *pending.QueueViewConfig*
                                     Queue (priority) view settings.
 
+                           {sort}     (string|string[], default: 'default')
+                                      Sort order for the queue view. See
+                                      |pending-sort| for syntax. The `'default'`
+                                      preset is priority → due → order → id.
+
+                         Sort keys: ~                          *pending-sort*
+                         Both `category.sort` and `queue.sort` accept a named
+                         preset string or an ordered list of sort keys.
+
+                         Presets: ~
+                           `'default'`       priority → due → order → id
+                           `'due-first'`     due → priority → order → id
+                           `'alphabetical'`  description → priority → order → id
+                           `'newest-first'`  entry (desc) → priority → order → id
+                           `'recent'`        modified (desc) → priority → order → id
+
+                         Available keys: ~
+                           `'priority'`      Higher priority first (descending)
+                           `'due'`           Earlier due date first (nil last)
+                           `'status'`        Pending before done
+                           `'category'`      Alphabetical by category
+                           `'description'`   Alphabetical by task text
+                           `'entry'`         Oldest creation date first
+                           `'modified'`      Oldest modification first
+                           `'order'`         Internal insertion order
+                           `'id'`            Task creation order
+
+                         Prefix a key with `-` to flip its default direction
+                         (e.g. `'-due'` for latest-first). `'priority'`
+                         defaults to descending; all others default to
+                         ascending. Implicit `order`, `id` tiebreakers are
+                         appended when absent for stable, deterministic sort.
+
+                         When `'status'` appears in the key list, the
+                         pending-before-done split is disabled and status
+                         participates as a normal sort field.
+
                          Examples: >lua
                              vim.g.pending = {
                                view = {
@@ -750,8 +795,12 @@ Fields: ~
                                  eol_format = '%d | %r',
                                  category = {
                                    order = { 'Work', 'Personal' },
+                                   sort = { 'due', 'priority', 'order' },
                                    folding = { foldtext = '%c: %n items' },
                                  },
+                                 queue = {
+                                   sort = 'due-first',
+                                 },
                                },
                              }
 <