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 order tasks were added unless `category_order` is set (see
|pending-config|). Blank lines separate categories. Within each category, |pending-config|). Blank lines separate categories. Within each category,
pending tasks appear before done tasks. Priority tasks (`!`) are sorted pending tasks appear before done tasks. Priority tasks (`!`) are sorted
first within each group. Category sections are foldable with `zc` and first within each group. The within-category sort order is configurable
`zo`. via `category_sort` (see |pending-sort|). Category sections are foldable
with `zc` and `zo`.
Queue view: ~ *pending-view-queue* Queue view: ~ *pending-view-queue*
A flat list of all tasks sorted by priority, then by due date (tasks 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 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 text alongside the due date virtual text so tasks remain identifiable
across categories. The buffer is named `pending://queue`. across categories. The buffer is named `pending://queue`.
@ -711,6 +713,56 @@ Fields: ~
given order. Categories not in the list are appended given order. Categories not in the list are appended
after the ordered ones in their natural order. 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* {folding} (boolean|table, default: true) *pending.FoldingConfig*
Controls category-level folds in category view. When Controls category-level folds in category view. When
`true`, folds are enabled with the default foldtext `true`, folds are enabled with the default foldtext