From 8780e5cffb36ebff216f63443e0fcededa462b88 Mon Sep 17 00:00:00 2001
From: Barrett Ruth <br.barrettruth@gmail.com>
Date: Sun, 8 Mar 2026 19:04:19 -0400
Subject: [PATCH] docs: add `queue_sort` and `category_sort` config fields
 (#100)
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 | 58 ++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 55 insertions(+), 3 deletions(-)

diff --git a/doc/pending.txt b/doc/pending.txt
index 11c3973..7c63986 100644
--- a/doc/pending.txt
+++ b/doc/pending.txt
@@ -397,13 +397,15 @@ 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,
     pending tasks appear before done tasks. Priority tasks (`!`) are sorted
-    first within each group. Category sections are foldable with `zc` and
-    `zo`.
+    first within each group. 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 priority, then by due date (tasks
     without a due date sort last), then by internal order. Done tasks appear
-    after all pending tasks. Category names are shown as right-aligned virtual
+    after all pending tasks. 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`.
 
@@ -711,6 +713,56 @@ Fields: ~
                          given order. Categories not in the list are appended
                          after the ordered ones in their natural order.
 
+    {queue_sort}         (string|string[], default: 'default')   *pending-sort*
+                         Sort order for the queue (priority) view. Accepts 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
+
+                         Sort 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 other keys 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. Otherwise
+                         pending tasks always appear before done tasks.
+
+                         Examples: >lua
+                             vim.g.pending = { queue_sort = 'due-first' }
+                             vim.g.pending = {
+                               queue_sort = { 'priority', '-due', 'description' },
+                             }
+<
+
+    {category_sort}      (string|string[], default: 'default')
+                         Sort order for tasks within each category in
+                         category view. Same syntax as `queue_sort`. The
+                         `'default'` preset is priority → order → id.
+                         Example: >lua
+                             vim.g.pending = {
+                               category_sort = { 'due', 'priority', 'order' },
+                             }
+<
+
     {folding}            (boolean|table, default: true)  *pending.FoldingConfig*
                          Controls category-level folds in category view. When
                          `true`, folds are enabled with the default foldtext