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

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:04:19 -04:00
parent c9471ebe90
commit 8780e5cffb

View file

@ -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