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:
parent
c9471ebe90
commit
8780e5cffb
1 changed files with 55 additions and 3 deletions
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue