barrett/pending.nvim
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 4

docs: add queue_sort and category_sort config fields (#100) (#105)

Browse source 
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.
This commit is contained in:
Barrett Ruth 2026-03-08 19:16:49 -04:00 • committed by GitHub
parent e534e869a8
commit 073541424e
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 52 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

55
doc/pending.txt
View file

@ -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',
},
},
}
<